AI assistant: Claude Code

Query GA4 and Search Console from the terminal with DuckDive in Claude Code

You script deploys, diffs and audits from the shell, yet your Google Analytics (GA4) and Search Console numbers still sit in a browser tab. Add one MCP server and Claude Code reads them, writes them to files in your repo and checks them before you ship.

Continue with Google

Free for 2 sites · No credit card

Or have your agent set it up

Set up DuckDive for my website. Follow https://analytics.duckdive.ai/agents.md

Updated 16 min read

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.json that 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:

$ terminal
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.

  1. Start Claude Code in the same folder

    The default local scope loads only in the project where you ran the add command. Open claude there, or use user scope (next section).

  2. Type /mcp and pick duckdive

    Choose DuckDive from the server list and start authentication. A DuckDive page opens in your browser.

  3. 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.

  4. Prove the tools loaded

    Ask something that touches the account. If your sites come back, you are done.

    Ask your agent
    which sites can you see in duckdive, and which ones are missing search console or ga4?

    Tools it calls list_websites

  5. 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.

Which scope to give the DuckDive server
QuestionLocal (default)UserProject
Flag--scope local or none--scope user--scope project
Written toPer project, in ~/.claude.json~/.claude.json.mcp.json in the repo root
Loads inThis project onlyEvery project on your machineThis project, for anyone who clones it
Shared through gitNoNoYes, the file is committed
Approval promptNoneNoneAsked once per person, interactive sessions only
Best forTrying it in one repoA marketer who works across many reposA 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:

$ terminal
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:

.mcp.json
{
  "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 agent
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.

Tools it calls list_websites get_search_console_summary

EXAMPLE DATAFictional business: Fallowfield Outfitters and Corriedale Wool Co.

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.

  1. list_websitesreturns two sites, both with Search Console connected
  2. get_search_console_summaryFallowfield Outfitters, last 30 days
  3. get_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:

WebsiteClicksImpressionsAvg position
Fallowfield Outfitters18,420612,30014.2
Corriedale Wool Co.6,935158,9009.8

I added impressions, since clicks alone hide whether a site lost visibility or lost the click. Want me to stage the file?

Search Console

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 agent
Regenerate 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

EXAMPLE DATAFictional business: Fallowfield Outfitters and Corriedale Wool Co., one month later
  1. get_search_console_summaryboth sites, last 30 days
  2. get_ga4_overviewboth sites, same 30 days: sessions, conversions, conversion rate
  3. git 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.

Search Console GA4

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.

Continue with Google

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 agent
Before 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_websites returns 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 diff readable.

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 agent
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.

Tools it calls list_websites get_search_console_pages

EXAMPLE DATAFictional business: Fallowfield Outfitters

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.

  1. list_websitesfilters on "Fallowfield" to get the website id
  2. get_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:

PathClicksRedirect check
/collections/tents4,812301 to /shop/tents
/blogs/trail/winter-layering-guide3,960Not affected
/collections/sleeping-bags2,744301 to /shop/sleeping-bags
/products/ridgeline-2p-tent2,105Two hops via an old rule
/collections/rain-shells1,688No rule, would 404
/pages/size-chart1,240Not affected
/collections/camp-kitchen1,102Lands on /shop/cooking

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.

Search Console

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 agent
Compare 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

EXAMPLE DATAFallowfield Outfitters: pages with clicks in the last 30 days that are missing from sitemap.xml
URL pathClicksLikely cause
/pages/size-chart402Static pages skipped by the generator
/blogs/trail/re-waterproof-a-shell377Blog sitemap missing from the index file
/products/ridgeline-2p-tent-2023151Discontinued; redirect or keep live
/collections/clearance96Hidden from navigation, still ranking

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:

$ terminal
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 json adds a session id and metadata; jq -r '.result' extracts the text.
  • --continue sends 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.json or ~/.claude.json never loads. Anthropic's headless guide calls --bare the recommended mode for scripted calls and says it will become the default for -p in 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.

scripts/search-monthly.sh
#!/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 agent
Read 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

$ terminal
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 .env file.
  • Output size. If a large pages pull trips the token cap, raise it for the shell with export MAX_MCP_OUTPUT_TOKENS=50000 before starting Claude Code.
  • Cloned repos. A -p run connects the servers in a project's .mcp.json without the approval prompt an interactive session shows, even in a folder you never trusted. Read .mcp.json in 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

  1. Set up DuckDive with your AI assistant, the agents.md file published by DuckDive AI, checked November 16, 2026.
  2. Connect Claude Code to tools via MCP, Anthropic, checked November 16, 2026.
  3. What are impressions, position, and clicks?, Search Console Help (Google), checked November 16, 2026.
  4. How to move a site, Google Search Central, checked November 16, 2026.
  5. Build and submit a sitemap, Google Search Central, checked November 16, 2026.
  6. Run Claude Code programmatically, Anthropic, checked November 16, 2026.
  7. Configure permissions, Anthropic, checked November 16, 2026.
  8. Error reference (section "Couldn't read the stored credentials for MCP server"), Anthropic, checked November 16, 2026.
  9. Conversions vs. key events in Google Analytics, Analytics Help (Google), checked November 16, 2026.
  10. DuckDive for Claude, ChatGPT and other AI apps, DuckDive AI connector docs, checked November 16, 2026.
  11. 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.

Add the server, then commit your first report

One command and one Google click, and next month's search numbers land in your repo as a file you can diff.

Free for 2 sites · No credit card · Working in an agent? Let it set DuckDive up