The short answer
Run claude mcp add --transport http duckdive https://api.duckdive.ai/mcp, type /mcp inside Claude Code and continue with Google. Claude Code can then read the stored Google Analytics (GA4) and Search Console history for every site in your DuckDive account, write the results to files in your repo, and rerun the same prompt headless with claude -p.
- Pick user scope to get DuckDive in every repo; project scope commits a
.mcp.jsonthat holds no secret. - Each data tool reads one website, so portfolio questions are a loop that starts at
list_websites. - Date ranges are rolling windows such as the last 30 or 90 days, not calendar months.
One command to add DuckDive
DuckDive runs as a remote MCP server over streamable HTTP. No package, no Python, no Google Cloud project, no key file. Run this, exactly as DuckDive's agent setup guide gives it:
claude mcp add --transport http duckdive https://api.duckdive.ai/mcp
The word duckdive is your local name for the server. Claude Code builds tool names from it (mcp__duckdive__list_websites), and every permission rule you write later uses that prefix, so keep it short and lowercase.
Leave off the --header "Authorization: Bearer ..." flag that Anthropic's MCP docs for Claude Code show for token-based servers. DuckDive's guide says plainly: no Authorization header, no API key; the client signs in with OAuth. Run claude mcp list to confirm the entry, or claude mcp get duckdive for its details.
Behind that URL: when you link a website's sources, DuckDive imports their history and keeps it, one store per website, across Search Console, GA4, Google Ads, Local Services Ads, Yext and Local Falcon. A question that walks thirty sites becomes thirty reads of stored data, not thirty fresh trips through Google's APIs while your terminal waits.
The tools Claude Code will list
DuckDive exposes 22 tools; these carry most terminal work. Every data tool takes one website_id and a fixed range: last7days, last14days, last30days (the default), last90days, last6months or last12months.
list_websites- Your websites and the sources each has connected. Returns 50 per call by default, 100 at most, with an offset for the next page and an optional text filter.
get_search_console_summary- One site's search clicks, impressions, CTR and average position, as a series across the range you name.
get_search_console_pages- The URLs that earned one site the most Google search clicks; 100 rows at most.
get_ga4_overview- GA4 sessions and conversions per day, with totals and conversion rate. The tool says conversions; Google's Analytics Help page on key events explains that GA4 now calls those important actions key events, so expect both words in your files.
get_sync_status- Per source, whether data is ready, importing or failing, and how recent it is.
One caution for reports: Google defines average position as the topmost spot your link held for a query, averaged across queries, per Search Console Help on impressions, position and clicks. A site-wide figure describes the query mix, not your rank for any one keyword.
Signing in from the /mcp menu
Adding the server only registers it. Tools appear after an OAuth sign-in in your browser, started from inside Claude Code.
-
Start Claude Code in the same folder
The default local scope loads only in the project where you ran the add command. Open
claudethere, or use user scope (next section). -
Type /mcp and pick duckdive
Choose DuckDive from the server list and start authentication. A DuckDive page opens in your browser.
-
Continue with Google, or Allow
New to DuckDive: select Continue with Google, which creates the account with no form. Already signed in: an approval screen appears. Keep Also allow actions ticked only if you want Claude Code to add sites or link sources; untick it for a read-only connection. Then select Allow.
-
Prove the tools loaded
Ask something that touches the account. If your sites come back, you are done.
Ask your agentwhich sites can you see in duckdive, and which ones are missing search console or ga4?
Tools it calls
list_websites -
Add a site if the list is empty
With actions allowed and an admin seat, Claude Code can run setup itself: paste the setup prompt from the top of this page. The walkthrough of agent-run setup shows each state it moves through.
If sign-in stalls
The DuckDive sign-in page expires after 30 minutes; run /mcp again. If it loops, sign in to DuckDive in that browser first. Over SSH, with no browser on the box, claude mcp login duckdive --no-browser prints the sign-in URL to open on your laptop, then asks you to paste back the redirect URL, per Anthropic's MCP docs; connect with ssh -t so the paste step has a terminal.
Project, user or local scope for the server
Claude Code keeps MCP servers at three scopes. Your choice decides which repos see DuckDive and whether teammates get it through git.
| Question | Local (default) | User | Project |
|---|---|---|---|
| Flag | --scope local or none | --scope user | --scope project |
| Written to | Per project, in ~/.claude.json | ~/.claude.json | .mcp.json in the repo root |
| Loads in | This project only | Every project on your machine | This project, for anyone who clones it |
| Shared through git | No | No | Yes, the file is committed |
| Approval prompt | None | None | Asked once per person, interactive sessions only |
| Best for | Trying it in one repo | A marketer who works across many repos | A team repo of reports or site code |
Source: Connect Claude Code to tools via MCP, Anthropic, checked November 2026.
The user-scope command, with the flag placed the way Anthropic's examples place it:
claude mcp add --transport http duckdive --scope user https://api.duckdive.ai/mcp
Swap in --scope project and Claude Code writes a .mcp.json like this to the repo root:
{
"mcpServers": {
"duckdive": {
"type": "http",
"url": "https://api.duckdive.ai/mcp"
}
}
}
That file is safe to commit: a URL and a transport, nothing else. Each teammate signs in through /mcp with their own Google login and sees only the websites their own DuckDive seat can see.
Two traps. When one server name exists at several scopes, Claude Code uses a single definition (local beats project beats user) and merges nothing, so a stale local entry shadows a fixed project file. And the same precedence list ends with claude.ai connectors. If you already added DuckDive as a connector in Claude on the web, check /mcp before running any command; its tools may already be listed, under an mcp__claude_ai_ prefix instead of mcp__duckdive__.
Worked example: a markdown report written into your repo
In the terminal, answers become files that get diffed, reviewed and read by the next script. Here the team behind two fictional online shops keeps an ops repo and wants a search table in reports/ every month.
Ask your agentFor every website in DuckDive, get Search Console clicks and average position for the last 30 days and write the results to reports/search-monthly.md as a table sorted by clicks.
Tools it calls list_websites get_search_console_summary
For every website in DuckDive, get Search Console clicks and average position for the last 30 days and write the results to reports/search-monthly.md as a table sorted by clicks.
list_websitesreturns two sites, both with Search Console connectedget_search_console_summaryFallowfield Outfitters, last 30 daysget_search_console_summaryCorriedale Wool Co., last 30 days
Created reports/search-monthly.md. The header line reads "Search Console, last 30 days, pulled November 16" so nobody mistakes the rolling window for October. Rendered, the table is:
| Website | Clicks | Avg position |
|---|---|---|
| Fallowfield Outfitters | 18,420 | 14.2 |
| Corriedale Wool Co. | 6,935 | 9.8 |
I added impressions, since clicks alone hide whether a site lost visibility or lost the click. Want me to stage the file?
Next month the useful number is the change. Claude Code has git in reach, so compare against the committed file instead of a spreadsheet of old numbers, and add GA4 to see whether clicks became conversions.
Ask your agentRegenerate reports/search-monthly.md, then add GA4 sessions and conversions for the same 30 days. Diff it against the version in the last commit that touched the file and add a change column for clicks. Don't commit, just show me git diff.
Tools it calls list_websites get_search_console_summary get_ga4_overview
get_search_console_summaryboth sites, last 30 daysget_ga4_overviewboth sites, same 30 days: sessions, conversions, conversion rategit diffrun by Claude Code's own shell tool, not by DuckDive
Rewrote the file with two GA4 columns and a click change against the committed version. Nothing staged. git diff reports/search-monthly.md:
-Search Console, last 30 days, pulled November 16 +Search Console and GA4, last 30 days, pulled December 16 -| Website | Clicks | Avg position | -| Fallowfield Outfitters | 18,420 | 14.2 | -| Corriedale Wool Co. | 6,935 | 9.8 | +| Website | Clicks | Change | Avg position | GA4 sessions | Conversions | +| Fallowfield Outfitters | 16,980 | -1,440 | 14.6 | 41,250 | 612 | +| Corriedale Wool Co. | 7,310 | +375 | 9.5 | 15,870 | 298 |
Fallowfield lost 7.8% of its clicks while its average position slipped only from 14.2 to 14.6, so check which pages fell before blaming rankings. On the GA4 side, Fallowfield turned 1.5% of sessions into conversions and Corriedale 1.9%. The GA4 numbers have no previous row to compare yet; next month's diff will show their change too.
Two habits keep that diff honest. Write raw counts, never pre-rounded percentages, so the next run's change column is computed from the same base. And keep GA4 and Search Console in separate columns rather than a clicks-to-sessions ratio: Search Console counts clicks from Google search only, while GA4 sessions include every channel, so a single blended number hides which source moved.
Save the first prompt as prompts/search-monthly.md: a versioned recipe the headless run below can read.
Your sites, your reports folder, one prompt
Connect a site, then ask Claude Code to put the last 30 days of clicks and position in a file you can diff.
Free for 2 sites · No credit card
Looping over every site from one prompt
"For every website" reads like one query. It is not. DuckDive has no portfolio endpoint: every data tool reads a single website. Claude Code calls list_websites, then the data tool once per site, then merges. Each call reads stored data, so the loop is quick, but two limits shape your prompts. Claude Code warns when one MCP tool result passes 10,000 tokens and caps it at 25,000 by default, per Anthropic's docs. One 100-row pages call fits under that cap; forty of them in one session crowd the context, so write each site to disk as you go. Site names, paths and queries are outside text, too; DuckDive's guide tells agents to treat them as data, never instructions, as the guide to connecting AI to analytics safely explains.
Check freshness before a loop feeds a report. A failing import returns thin numbers that look like a traffic collapse.
Ask your agentBefore you build anything: page through all my DuckDive websites and run a sync check on each. Print only the sites where Search Console or GA4 is failing, still importing, or more than 3 days old. If that list is empty, say so in one line.
Tools it calls list_websites get_sync_status
Before a loop over a long site list
- Name the range. Say "last 90 days" in the prompt, or every call quietly uses the 30-day default.
- Ask for paging.
list_websitesreturns 50 by default, 100 at most, with an offset. Say "keep paging" past 50. - Write as you go. Append each site to a file instead of holding it in context.
- Filter by name. The same tool takes a text filter, which saves calls and context.
- Pin the sort and the columns. The same headers every month make
git diffreadable.
When a loop turns up one site that fell hard, switch to the method for diagnosing a traffic drop across many sites.
Worked example: a search check before a redirect deploy
Your branch holds a redirect map; DuckDive holds the pages that earn search clicks. Claude Code reads both in one session. Google's guide to moving a site says to map your important URLs first, use server-side permanent redirects (301 or 308), avoid chains, and keep redirects for at least a year. Search clicks are a fast list of which URLs count.
Fallowfield Outfitters is renaming /collections/ to /shop/ on an unmerged branch.
Ask your agentBefore I deploy this redirect change, list the 20 pages on Fallowfield Outfitters with the most search clicks in the last 90 days so I can check none of them break.
Tools it calls list_websites get_search_console_pages
Before I deploy this redirect change, list the 20 pages on Fallowfield Outfitters with the most search clicks in the last 90 days so I can check none of them break.
list_websitesfilters on "Fallowfield" to get the website idget_search_console_pagestop pages by clicks, last 90 days, first 20 kept
I checked those 20 paths against the rules in redirects/collections-to-shop.conf on this branch. Fifteen get a single 301 to the right place and two are untouched by the change. Three need a fix before merge. The top seven:
| Path | Clicks | Redirect check |
|---|---|---|
| /collections/ | 4,812 | 301 to /shop/ |
| /blogs/ | 3,960 | Not affected |
| /collections/ | 2,744 | 301 to /shop/ |
| /products/ | 2,105 | Two hops via an old rule |
| /collections/ | 1,688 | No rule, would 404 |
| /pages/ | 1,240 | Not affected |
| /collections/ | 1,102 | Lands on /shop/ |
The other 13 each map to their /shop/ twin in one hop. Add a rule for rain-shells to /shop/rain-jackets, point the tent straight at its final URL, and confirm camp-kitchen should really land on a page with no stoves.
DuckDive supplied the ranked list; Claude Code's own file tools read the config. That split is why this fits a pre-merge habit, not a project plan.
The sitemap cross-check
The same pairing finds URLs that earn clicks but that your sitemap forgot. Google's sitemap documentation says to include the URLs you want in search results, as absolute URLs, and calls a submitted sitemap merely a hint. A missing page with clicks usually means a generator skipped a template.
Ask your agentCompare the sitemap.xml in this repo with Fallowfield Outfitters' top 100 Search Console pages and list URLs that get clicks but are missing from the sitemap.
Tools it calls list_websites get_search_console_pages
| URL path | Clicks |
|---|---|
| /pages/ | 402 |
| /blogs/ | 377 |
| /products/ | 151 |
| /collections/ | 96 |
Normalize first
Tell Claude Code to compare paths after stripping protocol, host, trailing slashes and query strings. Otherwise /tents versus /tents/ makes every URL look missing. And 100 pages per call catches the misses that matter, not every orphan.
Running a prompt without the interactive session
Once a prompt works, make it a command. Claude Code's -p flag (long form --print) runs one prompt and exits, with exit code 0 on success, as described in Anthropic's guide to running Claude Code programmatically. The catch: in a -p run, a tool call that needs approval is denied unless pre-approved. Name the DuckDive read tools and the file tools the report needs:
claude -p "$(cat prompts/search-monthly.md)" \ --allowedTools "mcp__duckdive__list_websites,mcp__duckdive__get_search_console_summary,mcp__duckdive__get_ga4_overview,Read,Write,Edit"
You could write mcp__duckdive__* instead, which Anthropic's permissions reference documents as matching every tool on the server. For unattended runs, list tools one by one: the wildcard also approves action tools such as add_website if your connection kept actions, and a report job has no use for them.
--output-format jsonadds a session id and metadata;jq -r '.result'extracts the text.--continuesends a follow-up to the most recent conversation.- Leave off
--bare, and plan for the day it is on by default. Bare mode connects only servers passed with--mcp-config, so a DuckDive entry in.mcp.jsonor~/.claude.jsonnever loads. Anthropic's headless guide calls--barethe recommended mode for scripted calls and says it will become the default for-pin a future release. When that ships, an untouched cron line keeps running and silently loses DuckDive, which is the failure the preflight below exists to stop.
A preflight that stops the job
Anthropic's guide says newer builds print a text summary of server status when /mcp is the whole prompt of a -p run. On the older Claude Code build we tried while writing this page, that call replied "/mcp isn't available in this environment", so check from the shell instead. claude mcp list prints one line per server, its name first, then a health status such as Connected or Needs authentication.
#!/bin/sh
# Stop before the report if the duckdive server is not connected.
claude mcp list | grep -q '^duckdive:.*Connected' || { echo "duckdive: not connected" >&2; exit 1; }
claude -p "$(cat prompts/search-monthly.md)" \
--allowedTools "mcp__duckdive__list_websites,mcp__duckdive__get_search_console_summary,mcp__duckdive__get_ga4_overview,Read,Write,Edit"
Keep the ^duckdive: anchor. If you also added DuckDive as a claude.ai connector, that entry prints on its own line under another name and may read Connected while the duckdive server your tool list names is signed out.
A follow-up job that needs git
This prompt compares the file with its previous commit, so a -p run needs shell rights for git. Without them, Claude Code denies the Bash call and the job ends with no "Biggest mover" section.
Ask your agentRead reports/search-monthly.md, find the site with the biggest drop in clicks against the previous commit, and for that site only pull its top 10 pages for the last 30 days. Append them under a "Biggest mover" heading. Plain markdown, no commentary.
Tools it calls list_websites get_search_console_pages
claude -p "$(cat prompts/biggest-mover.md)" \ --allowedTools "mcp__duckdive__list_websites,mcp__duckdive__get_search_console_pages,Read,Edit,Bash(git log *),Bash(git show *)"
In Anthropic's rule syntax the space before the star makes Bash(git log *) a prefix match on the git log command and nothing broader. The job can read history, but a git commit or git push still needs approval nobody is there to give, so the run denies it.
Config files, tokens and CI
- Server entries. Local and user scope live in
~/.claude.json; project scope lives in.mcp.json. Only the last belongs in git. - The sign-in token. Claude Code keeps it in its own credential store and refreshes it; you never handle it. There is no DuckDive key for a
.envfile. - Output size. If a large pages pull trips the token cap, raise it for the shell with
export MAX_MCP_OUTPUT_TOKENS=50000before starting Claude Code. - Cloned repos. A
-prun connects the servers in a project's.mcp.jsonwithout the approval prompt an interactive session shows, even in a folder you never trusted. Read.mcp.jsonin any repo before scripting against it.
Scheduled runs: what holds up, and what to test first
DuckDive signs clients in through a browser, with OAuth, and offers no API key. A fresh GitHub Actions or GitLab runner has never signed in, so it cannot reach DuckDive.
A machine you control is different. Anthropic's MCP docs say a -p run cannot do the OAuth flow itself and tell you to finish sign-in interactively first, with /mcp or claude mcp login. So a cron job on a box where you signed in once should work. We have not proved it end to end, though, and macOS adds a known snag: Anthropic's error reference documents -p runs failing with "Couldn't read the stored credentials" while the login keychain is locked, which is a state a job started from cron can meet. Run the preflight from the real crontab, not from your open terminal, and read the first few logs before you trust the schedule.
If an inbox is enough, skip the machine. Ask Claude Code to create a DuckDive scheduled report: the tool sends a recurring email, daily, weekly or monthly, for up to 50 websites, and it always goes to your own account email.
To remove access cleanly, run claude mcp logout duckdive before claude mcp remove duckdive. Removing a server alone deletes the local token without revoking it, per Anthropic. On the DuckDive side, its connector guide says you can disconnect under AI Connectors in the app, and access ends at once.
When the terminal route is the wrong one
The pairing earns its keep on checks you repeat and want on disk. Pick another route when:
- You would rather chat than script. Use the Claude connector for the web and desktop apps, or the Cursor install link if you live in an editor. Other clients are covered on the remote MCP page for any client.
- The job has to run on a throwaway CI runner. Nobody can click Continue with Google on an ephemeral machine, so it never signs in. A DuckDive scheduled email, or code you write against Google's own APIs, fits that shape better.
- You want deep GA4 work on one property. Funnels, realtime and custom dimensions live in Google's read-only Google Analytics MCP server, which lists Claude Code as a client but runs locally on Python with a Google Cloud project. Our comparison of Google's server and a hosted connector weighs the trade.
- The file feeds invoices or anything that must match to the digit on every run. A model writes the markdown, so column order and rounding can drift unless your prompt pins them. Numbers that bill a client deserve a deterministic export.
The tool limits travel with you into the terminal: rolling windows rather than calendar dates, 100 rows per call, no query-by-page breakdown. For a full export of a 20,000-URL catalog or an exact October, use Search Console's own export or API.
If you are building your own tooling on top of these reads, the page for developers goes deeper on the endpoint and auth, and the Search Console source page details exactly what the three search tools return.
What terminal users ask before adding the server
Why does claude mcp list show Needs authentication for duckdive?
Adding the server never signs you in. Claude Code marks a remote server that way when it answers 401 or 403, which is what DuckDive's endpoint returns until you authenticate. Open /mcp in a session and sign in, or run claude mcp login duckdive from the shell, then run claude mcp list again and look for Connected.
Why are the DuckDive tools missing in my other repo?
The default local scope loads only in the project where you ran the add command. Add it again with --scope user for every project, or --scope project to share it through the repo.
How do I let Claude Code use only DuckDive's read tools?
Use two layers. At sign-in, untick Also allow actions, so the connection itself only gets read access. Then add four entries to permissions.deny in settings.json: mcp__duckdive__add_website, mcp__duckdive__connect_website_sources, mcp__duckdive__refresh_website_data and mcp__duckdive__create_scheduled_report. Claude Code checks deny rules before allow rules, so a broad mcp__duckdive__* allow added later cannot reopen them.
Can a claude -p job in GitHub Actions read DuckDive?
Not on a fresh runner. DuckDive signs in through OAuth in a browser and has no API key, and Anthropic's docs say a -p run cannot complete that sign-in itself. Sign in once, interactively, on a machine you control and schedule the job there after the preflight passes from the real schedule, or use a DuckDive scheduled email report.
Does DuckDive load when I run claude with --bare?
Not from your saved config. Bare mode skips the servers in .mcp.json and ~/.claude.json and connects only those passed with --mcp-config. Anthropic's docs also say a bare run never reads OAuth credentials or the system keychain, so do not count on it reusing your DuckDive sign-in. Leave scheduled jobs on the normal mode and keep the preflight.
Where does Claude Code keep the DuckDive sign-in, and how do I revoke it?
In Claude Code's own credential store, not in .mcp.json; on a Mac, Anthropic's error reference ties that store to the login keychain. Clear authentication in /mcp, or claude mcp logout duckdive, revokes the token. Run the logout before claude mcp remove, because removal alone only deletes the local copy.
Sources
- Set up DuckDive with your AI assistant, the agents.md file published by DuckDive AI, checked November 16, 2026.
- Connect Claude Code to tools via MCP, Anthropic, checked November 16, 2026.
- What are impressions, position, and clicks?, Search Console Help (Google), checked November 16, 2026.
- How to move a site, Google Search Central, checked November 16, 2026.
- Build and submit a sitemap, Google Search Central, checked November 16, 2026.
- Run Claude Code programmatically, Anthropic, checked November 16, 2026.
- Configure permissions, Anthropic, checked November 16, 2026.
- Error reference (section "Couldn't read the stored credentials for MCP server"), Anthropic, checked November 16, 2026.
- Conversions vs. key events in Google Analytics, Analytics Help (Google), checked November 16, 2026.
- DuckDive for Claude, ChatGPT and other AI apps, DuckDive AI connector docs, checked November 16, 2026.
- Google Analytics MCP server, Google for Developers, checked November 16, 2026.
Last reviewed . Claude Code flags and menus change between releases; recheck Anthropic's docs if a command fails. Fallowfield Outfitters, Corriedale Wool Co. and every number in EXAMPLE DATA blocks are fictional.
