cituna-mcp

# Cituna MCP server [](https://www.npmjs.com/package/cituna-mcp) [](./LICENSE) 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](#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: ```bash npx -y cituna-mcp # (normally launched by your MCP client, see below) ``` From source (for development): ```bash 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 ```bash 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): ```json { "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](https://github.com/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](https://cituna.com/integrations). MIT licensed. Bugs and requests: <https://github.com/Cituna/cituna-mcp/issues>