Cituna MCP server

Bring Cituna into Claude (Desktop, Code, or any MCP client). This server is a thin bridge over the Cituna backend: it authenticates as you and calls the same endpoints the app uses, so Google's OAuth refresh token and your database stay server-side and nothing sensitive lives in the MCP.

It exposes three things Claude can work with directly:

• Daily visibility tracking — the core deliverable. Your tracked prompts are re-asked every day across all six engines (ChatGPT, Perplexity, Gemini, Claude, Grok, Google AI Overviews); get_visibility returns the latest prompt×engine grid (cited? which position? which mode?) plus your current score, and get_engine_answers returns the receipts — what each engine actually said, the brands it cited, and the source URLs.
• AI-visibility audits — per-engine citation scores across all six engines, the query×engine citation matrix, competitors cited, and a prioritised gap/action queue you can update from the chat.
• Live Google Search Console — clicks / impressions / CTR / position, top queries and pages, and arbitrary Search Analytics queries.

Claude  ⇄  (stdio, MCP)  ⇄  this server  ⇄  (HTTPS + your key)  ⇄  Cituna backend  ⇄  AI engines + Google Search Console

Tools

Read tools work from Starter; write tools — the two tagged ✍︎ Pro — require Pro or higher (see Plans). The 7-day free trial is app-only and has no MCP access.

Tool	Plan	What it does
whoami	Starter+	The authenticated account (email, workspace, role), backend URL, and — when available — your plan (Starter/Pro/Max) and usage. Call first to confirm the connection.
list_audits	Starter+	Recent AI-visibility audits, newest first: scanId, domain, date, AI-citation score, SEO/GEO/authority scores, open-gap count. Optional domain filter.
get_audit	Starter+	One audit in detail by scanId: overall + per-engine scores, the query×engine citation matrix, competitors cited, top gaps, and pass/warn/fail check counts.
get_visibility	Starter+	Daily tracking. The latest prompt×engine grid for a brand (id or domain): per tracked prompt and engine — cited?, position, mode (live/value/lite/off), status — plus the current visibility score and the day it was measured.
get_engine_answers	Starter+	The receipts. For a brand + prompt (optional engine): the actual stored answer text each engine gave on the most recent day, the brands it cited, the source URLs, and your cited position. Answer text capped ~4k chars with a truncated flag.
list_gaps	Starter+	The fix queue for a domain (or scanId): each gap with its gapKey, status (todo/doing/done), title, category, impact, effort, and the concrete fix.
set_gap_status	✍︎ Pro	Update one gap's status (todo / doing / done) using the gapKey + domain from list_gaps.
run_scan	✍︎ Pro	Run a new audit for a URL and return the completed result. Takes ~1 min and consumes one scan from your monthly quota.
gsc_status	Starter+	Whether GSC is connected for your workspace, the connected Google email, and your verified GSC properties.
list_brands	Starter+	Domains tracked in your workspace — handy inputs for the audit and gsc_* tools.
gsc_overview	Starter+	GSC summary for a domain over the last N days: totals (clicks/impressions/CTR/position), top queries & pages, country/device splits, and a daily series.
gsc_query	Starter+	The flexible one. Arbitrary Search Analytics query: any dimensions, explicit date range or trailing window, row limit, and filters.

Plans

The MCP server is included from the Starter plan ($39/mo) and up (Starter / Pro / Max, which map to internal solo / agency / scale). There is no free MCP — the 7-day trial is app-only, and an ended trial with no plan can't call it.

Read / write split. On Starter the MCP is read-only: read your audits, gaps, brands, and Search Console data all you like. The write tools — run_scan (spends a scan) and set_gap_status (mutates your action queue) — require Pro or higher; on Starter you still run scans and work the queue in the app, just not from Claude. Every MCP call also counts against your plan's monthly MCP-call allowance (Starter 5k / Pro 10k / Max 30k). If a write tool returns "…is a write action — it needs the Pro/Max plan", upgrade at https://cituna.com/pricing.

Install

No clone, no build — npx fetches it:

npx -y cituna-mcp   # (normally launched by your MCP client, see below)

From source (for development):

git clone https://github.com/Cituna/cituna-mcp && cd cituna-mcp
npm install && npm run build   # → node dist/index.js

Configure

Set CITUNA_API_URL (backend base URL, default https://cituna.com) plus one auth option, checked in this priority order:

1. Personal API key — recommended. In the app: Integrations → "Claude / MCP access" → Generate token, copy the cituna_sk_… value. Long-lived, revocable in the app, and not your password. → CITUNA_API_KEY
2. A session JWT. Log into the app, DevTools → Application → Cookies, copy cituna_token. Works but expires ~30 days. → CITUNA_TOKEN
3. Email + password. The server logs in and auto-refreshes on expiry. → CITUNA_EMAIL + CITUNA_PASSWORD

Claude Code

claude mcp add cituna --scope user \
  --env CITUNA_API_KEY=cituna_sk_your_generated_key \
  -- npx -y cituna-mcp

(The backend URL defaults to https://cituna.com; add --env CITUNA_API_URL=… only to point at a different backend.)

Then in a Claude Code session: /mcp to confirm it's connected, and ask "what changed in my AI visibility this week?"

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "cituna": {
      "command": "npx",
      "args": ["-y", "cituna-mcp"],
      "env": {
        "CITUNA_API_KEY": "cituna_sk_your_generated_key"
      }
    }
  }
}

Restart Claude Desktop. The tools appear under the 🔌 menu.

Running from source instead of npm? Use "command": "node", "args": ["/absolute/path/to/mcp/dist/index.js"].

Built-in prompts (v1.5+)

The server ships five reusable analysis workflows via the MCP prompts API. In Claude they show up in the prompt/command picker; each one runs a worked recipe over the tools, including the joins between Search Console and the engine answers that a generic SEO tool cannot make.

Prompt	Arguments	What it does
why-am-i-not-cited	brand, prompt?	Classifies every uncited prompt into invisible-everywhere vs Google-visible-but-AI-invisible vs partially-cited, with evidence from the actual engine answers and GSC
gsc-to-ai-gap	domain, days?	Queries with real Google impressions where AI never cites you: the ranked AEO target list
competitor-teardown	brand, competitor?	Tallies who the engines actually cite from the answer text, and diffs it against your configured competitor list
weekly-review	brand	Wins, regressions and this week's 3 actions from audits + GSC + the gap queue. Reads only
prioritize-fixes	domain	Re-ranks the fix queue by the GSC impressions and uncited prompts each gap touches

All five are read-only by default; none of them triggers a paid scan on its own.

Example prompts

• "How is acme.com doing in AI search today — which prompts and engines cite us?" (get_visibility)
• "For acme.com, on the prompt best CRM for dentists, what did each engine actually say and who did they cite?" (get_engine_answers)
• "What changed in my AI visibility this week?" (uses list_audits → get_audit)
• "Which gaps are open for acme.com? Mark the schema one done." (list_gaps → set_gap_status)
• "Run a fresh visibility scan for acme.com and summarise the top 3 gaps." (run_scan)
• "Which AI engines cite us, and for which questions?" (the citation matrix from get_audit)
• "How did example.com do in Search over the last 28 days?" (gsc_overview)
• "Break down example.com traffic by country, then by device." (gsc_query)
• "Show queries containing 'pricing' for example.com — filter query contains pricing." (gsc_query)

Connecting Google Search Console

The gsc_* tools need a one-time connect in the Cituna app, not here. There is no Google OAuth in this server, by design: the browser consent flow happens in the app, and the resulting refresh token is stored server-side only.

1. In the app, open Integrations and click Connect Google Search Console (paid plans; the trial does not include GSC).
2. Google will ask to grant Cituna read-only Search Console access (webmasters.readonly). Cituna never gets write access to anything Google.
3. Pick the Google account where your domain is a verified Search Console property. This is the step people miss: if the account you choose has never verified the domain, everything connects fine and every query still comes back empty, because Google has nothing to show that account.
4. Back here, run gsc_status. It lists the connected account and every property it can query. If your domain is not in that list, fix it in Search Console (verify the property), not in Cituna.

Disconnecting in the app (Integrations, Disconnect) revokes access for this server instantly as well.

How auth reaches Google

This server never holds Google credentials. It sends your Cituna key/JWT as a Bearer token to the backend; the backend looks up your workspace's stored GSC refresh token, mints a short-lived Google access token, and queries the Search Console API. Disconnecting GSC in the app instantly cuts off this server too.

Troubleshooting

Symptom	Fix
No API key configured	No credential set. Generate a token (Integrations → Claude / MCP access) and set CITUNA_API_KEY.
API key invalid or expired	The key was revoked or the JWT expired. Mint a new key in the app, or re-copy cituna_token; email/password auto-refreshes.
…is a write action — it needs the Pro/Max plan	You called a write tool (run_scan / set_gap_status) on Starter or the trial, where the MCP is read-only. Run it in the app, or upgrade to Pro at https://cituna.com/pricing.
requires a paid plan (Starter/Pro/Max)	The tool is premium-gated and your plan isn't eligible. Upgrade at https://cituna.com/pricing.
{ "configured": false, ... }	GSC OAuth env isn't set on the backend, or you haven't connected GSC, or no property matches the domain. Follow the message.
Scan quota reached	You've used your monthly scans (or the anonymous daily limit). Upgrade or wait for the reset.
Tools don't appear	Run npm run build; confirm the absolute path to dist/index.js; check the client's MCP logs.
ECONNREFUSED	Backend isn't running / wrong CITUNA_API_URL.

Requires Node 18.17+.

---

About this repository

The public Cituna/cituna-mcp repo is a published mirror, not the working tree: the server is developed in Cituna's private monorepo and released on tag, so the tool surface and engine list stay pinned to what the API actually serves. Pull requests against the mirror can't be merged directly, but issues are read and acted on, so please do open them.

Looking for BI dashboards instead of a chat client? Cituna also ships a Looker Studio connector. See cituna.com/integrations.

MIT licensed. Bugs and requests: https://github.com/Cituna/cituna-mcp/issues