{
  "markdown": "# Citation Intelligence MCP\n\n**A free, self-hosted MCP server that tells your agent what LLMs cite - across Perplexity, Google AI Overviews, ChatGPT, Claude, Gemini, and Bing.**\n\n[![npm version](https://img.shields.io/npm/v/@automatelab/citation-intelligence.svg)](https://www.npmjs.com/package/@automatelab/citation-intelligence)\n[![license](https://img.shields.io/npm/l/@automatelab/citation-intelligence.svg)](./LICENSE)\n[![node](https://img.shields.io/node/v/@automatelab/citation-intelligence.svg)](https://nodejs.org)\n[![CI](https://github.com/AutomateLab-tech/citation-intelligence/actions/workflows/ci.yml/badge.svg)](https://github.com/AutomateLab-tech/citation-intelligence/actions/workflows/ci.yml)\n\n## What this is\n\nAn MCP server for agents and developers who need to know which URLs get cited by AI search engines for any query. Install once, query from any MCP-compatible client (Claude Desktop, Cursor, Claude Code, Continue, Cline, n8n, LangGraph). Self-hosted, no account, no centralized backend. Bring your own API keys; nothing is stored on a remote server.\n\n## Who this is for\n\nInstall this if you're:\n\n- Building an agent that does research and want it to cite sources LLMs already trust\n- A solo dev or indie hacker checking whether your SaaS is showing up in AI search\n- A content creator confirming your articles are being cited by ChatGPT, Claude, or Perplexity\n- An SEO or GEO practitioner who wants programmatic citation data without a $295-$499/mo dashboard\n- Running an editorial pipeline and want citation-deficit-driven topic selection\n- Comparing competitor visibility across AI engines for any niche\n\nDo NOT install this if you want:\n\n- A polished marketing dashboard with charts and team seats - try Profound, AthenaHQ, or Otterly.AI\n- A hosted service with SLAs - this is self-hosted by design\n- Citation tracking for academic papers - try citecheck\n- 350M+ pre-modeled prompts - that's Ahrefs Brand Radar\n\n## Why this exists\n\nThe AI citation tracking market is dominated by VC-funded dashboards starting at $295/mo. None ships MCP-first. If you're an agent or developer who wants citation data piped directly into your workflow - not into a SaaS login - there isn't a tool for you. This is that tool.\n\n---\n\n## Tools\n\nTools are grouped into seven namespaces: `citations_*`, `domain_*`, `signals_*`, `panel_*`, `report_*`, `competitors_*`, `audit_*`. The prefix is the question category; the suffix is the action. Wire names use underscores (not dots) so Anthropic-API-based MCP clients (Claude Desktop, Claude Code) can forward the tool list without HTTP 400.\n\n**Start with `citations_provenance` or `domain_am_i_cited`.** Single-engine results (`citations_check` with a pinned engine) are directional; multi-engine consensus is the honest signal. A URL cited by 4 of 5 engines is a very different finding than one cited by 1.\n\n### `citations_*` — query-level: who cites what, with what evidence\n\n| Tool | Purpose |\n|---|---|\n| `citations_provenance` | **Recommended first tool.** Fan a query across engines; per-URL cross-engine consensus matrix. Returns `interpretation_note` per engine. |\n| `citations_check` | URLs cited by Perplexity / Claude / ChatGPT / Gemini / Google AI Mode for a query; or web rank via bing_serp / brave_serp |\n| `citations_evidence` | Extract the cited snippet from `raw_answer` for each citation (why, not just that) |\n| `citations_predict` | Citation likelihood from public signals - no LLM fired |\n| `citations_trend` | Time-series report of citation rate + per-query gained/lost deltas |\n| `citations_freshness` | Recency score (halflife=365d) for the pages an engine cites |\n\n### `domain_*` — domain-level: am I cited, what for\n\n| Tool | Purpose |\n|---|---|\n| `domain_am_i_cited` | Domain citation check. With `engine=auto` (default): fans across all available LLM engines, returns per-engine breakdown + cross-engine consensus. Pin `engine=` to reduce cost. |\n| `domain_cited_for` | Queries the domain has been cited for, from local cache |\n| `domain_cited_for_diff` | Diff of `domain_cited_for` between two time windows for a domain |\n\n### `signals_*` — external signals: AI Overview, Wikipedia, GSC, answer-box position\n\n| Tool | Purpose |\n|---|---|\n| `signals_ai_overview` | Google AI Overview presence + cited sources |\n| `signals_wikipedia` | List Wikipedia articles referencing a domain (zero keys) |\n| `signals_gsc_gap` | Join Google Search Console performance with AI citation status |\n| `signals_answer_box` | Bin each citation's first mention in `raw_answer` into early/middle/late thirds |\n\n### `panel_*` — saved query panels (editorial watchlists)\n\n| Tool | Purpose |\n|---|---|\n| `panel_track` | Save / load / list named query panels (editorial watchlists) |\n| `panel_run` | Run a panel through `domain_am_i_cited` and snapshot to disk |\n\n### `report_*` — turnkey reporting artifacts\n\n| Tool | Purpose |\n|---|---|\n| `report_visibility` | One-call AI visibility report over a query set (or panel): citation rate (mention frequency), share of voice vs competitors, average rank, and brand sentiment. Returns structured data + a Markdown artifact for a public page. |\n\n### `competitors_*` — competitive landscape per query\n\n| Tool | Purpose |\n|---|---|\n| `competitors_canonical_set` | Top cited domains per query, aggregated across engines |\n| `competitors_compete` | End-to-end competitive snapshot: your URL vs top cited competitors |\n| `competitors_compare` | Side-by-side `citations_predict` across 2-10 URLs |\n\n### `audit_*` — fixable on-page / on-site checks\n\n| Tool | Purpose |\n|---|---|\n| `audit_schema` | Deep schema.org validation - required fields per `@type`, malformed JSON-LD |\n| `audit_structured_data` | Repair-oriented schema.org diagnostics + suggested patches |\n| `audit_crawler_access` | Verify GPTBot / ClaudeBot / PerplexityBot / CCBot / Google-Extended etc. can fetch a URL |\n| `audit_sitemap` | Bulk `citations_predict` across every URL in a sitemap, worst-first |\n| `audit_sitemap_map` | Cross-reference sitemap URLs with cached citations (inverse of `audit_sitemap`) |\n| `audit_llms_txt` | Generate an `llms.txt` (https://llmstxt.org) from a sitemap |\n\n### Prompts\n\nServer-side prompt templates the client can offer end users (call via the MCP prompt list):\n\n- `audit_citation_readiness(url)` - chains `citations_predict` + `audit_schema`\n- `audit_competitor_snapshot(query, your_url?)` - chains `competitors_canonical_set` + `competitors_compete`\n- `audit_crawler_checkup(url)` - runs `audit_crawler_access` and writes a remediation list\n- `audit_gap_analysis(domain, days?)` - drives `signals_gsc_gap` and suggests next moves\n- `audit_sitemap_coverage(sitemap_url)` - runs `audit_sitemap_map` and recommends priorities\n\n### Resources\n\nCache views the client can read or subscribe to (no tool call required):\n\n- `citation://cache/summary` - entry counts by type/engine, unique queries/URLs, oldest/newest\n- `citation://panels` - saved panels + per-panel snapshot counts\n- `citation://docs/llms-txt` - llms.txt primer (markdown)\n- `citation://docs/ai-crawlers` - AI crawlers cheatsheet (markdown)\n- `citation://domain/{domain}/cited-for` - dynamic template: citations for `{domain}`\n\n## What this actually measures\n\nEvery response includes a `surface` field that tells you exactly how the data was collected. Understanding this is important before drawing conclusions.\n\n| Surface | Engines | What it means |\n|---|---|---|\n| `consumer_scrape` | `perplexity`, `google_ai_mode` | Proxied through a real consumer-facing AI search product. Closest to what your users see. |\n| `api_proxy` | `claude`, `openai`, `gemini` | API call to a search-enabled LLM. **May differ from consumer product behavior** — different model versions, no UI-level ranking logic, no personalization. Use as a directional proxy, not as ground truth. |\n| `web_rank` | `bing_serp`, `brave_serp` | Traditional web search rank (not LLM citation). Measures whether a URL appears in SERP results, not whether an LLM cites it. |\n| `static_signal` | `citations_predict`, `signals_wikipedia` | Offline signal computed from public data. No live LLM query. |\n\n### Per-engine notes\n\n**`perplexity` (consumer_scrape)** — Sonar Pro via the Perplexity API with a consumer-equivalent system prompt. Reasonably close to Perplexity.ai. Citations come from `search_results` in the response; the `citations` fallback contains URL-only entries without title.\n\n**`claude` (api_proxy)** — Claude Sonnet via the Anthropic Messages API with `web_search` tool enabled. The consumer Claude.ai product uses different routing and ranking logic. Citation behavior can differ, especially for recent/time-sensitive queries.\n\n**`openai` (api_proxy)** — `gpt-4o` + the `web_search_preview` tool via the OpenAI Responses API. Replaces the deprecated `gpt-4o-search-preview` alias OpenAI retired; base `gpt-4o` plus the tool is the supported path.\n\n**`gemini` (api_proxy)** — Gemini 2.5 Pro via the Generative Language API with `google_search` grounding. Consumer Gemini uses the same grounding index but different re-ranking. Results are directional.\n\n**`google_ai_mode` (consumer_scrape)** — Google AI Mode results via SerpAPI. Closest to what users see in Google Search. Requires `SERPAPI_KEY`.\n\n**`bing_serp` / `brave_serp` (web_rank)** — Traditional SERP rank. Does NOT measure LLM citations. Use `citations_check` with these engines to compare organic web rank against LLM citation rank. `domain_am_i_cited` refuses these engines — it only measures LLM behavior.\n\nThe proxy nature of `api_proxy` engines is a feature, not a bug: it lets you run citation checks without consuming expensive consumer-product quota. Just don't report API-proxy numbers as \"ChatGPT cites you\" without the caveat.\n\nEvery tool response includes an `interpretation_note` field that summarizes the fidelity in one sentence. Full per-engine fidelity ratings: [docs/surface-fidelity.md](docs/surface-fidelity.md).\n\n---\n\n## Quick start\n\n```bash\nnpx -y @automatelab/citation-intelligence\n```\n\nRequires Node 20 or later.\n\n### Claude Desktop\n\nAdd to `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"citation-intelligence\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@automatelab/citation-intelligence\"],\n      \"env\": {\n        \"PERPLEXITY_API_KEY\": \"pplx-...\",\n        \"SERPAPI_KEY\": \"...\",\n        \"ANTHROPIC_API_KEY\": \"sk-ant-...\",\n        \"OPENAI_API_KEY\": \"sk-...\",\n        \"GEMINI_API_KEY\": \"...\"\n      }\n    }\n  }\n}\n```\n\nSet only the keys you have. Any MCP client that supports stdio transport works - same `command` / `args` pattern.\n\n## How it stays free\n\n- **No central backend.** The server runs on your machine. Nothing is uploaded.\n- **Free tier first.** SerpAPI gives 100 free Google AI Overview lookups/month. Bing Web Search has a free tier. Perplexity offers free Sonar access on signup.\n- **Bring your own paid keys** if you want the premium engines (Claude, ChatGPT, Gemini). Keys pass through to the vendor and never touch any third party.\n- **Local cache** at `~/.config/citation-intelligence/cache.json`. Repeated queries hit cache, not API. Default TTL: 7 days.\n- **`citations_predict` runs with zero keys** - it scores citation likelihood from public signals (Wikipedia, schema.org, llms.txt, GitHub) without firing any LLM.\n\n## Privacy\n\n- All API calls go from your machine directly to the vendor (Anthropic, OpenAI, Google, Perplexity, Bing, SerpAPI).\n- No proxy. No analytics. No telemetry by default.\n- API keys are read from environment variables on the MCP process - never logged, never persisted.\n- Cache file lives at `~/.config/citation-intelligence/cache.json`. Delete it any time.\n\n## Environment variables\n\n| Var | Purpose | Free tier? |\n|---|---|---|\n| `PERPLEXITY_API_KEY` | `citations_check` (perplexity — consumer_scrape) | Yes |\n| `SERPAPI_KEY` | `signals_ai_overview` + `citations_check` (google_ai_mode — consumer_scrape) | 100/month free |\n| `ANTHROPIC_API_KEY` | `citations_check` (claude — api_proxy) | Paid only |\n| `OPENAI_API_KEY` | `citations_check` (openai — api_proxy) | Paid only |\n| `GEMINI_API_KEY` | `citations_check` (gemini — api_proxy) | Yes |\n| `BING_API_KEY` | `citations_check` (bing_serp — web_rank) | Yes |\n| `BRAVE_API_KEY` | `citations_check` (brave_serp — web_rank) | Yes (2000/month) |\n| `CITATION_CACHE_TTL_DAYS` | Cache TTL for `citations_check` entries (default 7) | n/a |\n| `CITATION_AI_OVERVIEW_TTL_DAYS` | Cache TTL for `signals_ai_overview` entries (default 1) | n/a |\n| `CITATION_CONFIG_DIR` | Override config dir (default `~/.config/citation-intelligence`) | n/a |\n\n## Example: am I cited?\n\n```\nYou: For the queries \"best AI citation tracker\", \"MCP for AI search\", \"self-hosted GEO tool\",\n     is automatelab.tech cited?\n\n(agent invokes `domain_am_i_cited`)\n\nResult:\n{\n  \"domain\": \"automatelab.tech\",\n  \"engine\": \"perplexity\",\n  \"results\": [\n    { \"query\": \"best AI citation tracker\",   \"cited\": true,  \"rank\": 4 },\n    { \"query\": \"MCP for AI search\",          \"cited\": true,  \"rank\": 1 },\n    { \"query\": \"self-hosted GEO tool\",       \"cited\": false, \"matching_urls\": [] }\n  ],\n  \"summary\": {\n    \"queries_total\": 3,\n    \"queries_cited\": 2,\n    \"citation_rate\": 0.67,\n    \"average_rank\": 2.5\n  }\n}\n```\n\n## Example: predict citation likelihood (no key required)\n\n```\nYou: How likely is https://example.com/blog/post to be cited by AI?\n\n(agent invokes `citations_predict`)\n\nResult:\n{\n  \"url\": \"https://example.com/blog/post\",\n  \"score\": 62,\n  \"grade\": \"C\",\n  \"signals\": {\n    \"wikipedia_linked\": false,\n    \"github_referenced\": false,\n    \"reddit_referenced\": true,\n    \"llms_txt_present\": true,\n    \"https\": true,\n    \"has_article_schema\": true,\n    \"has_faq_schema\": false,\n    \"has_breadcrumb_schema\": true,\n    \"canonical_clean\": true,\n    \"word_count\": 1850,\n    \"reading_time_minutes\": 8,\n    \"h2_count\": 7,\n    \"h2_question_count\": 1,\n    \"authority_link_count\": 2,\n    \"external_link_count\": 6,\n    \"internal_link_count\": 11,\n    \"last_modified_days_ago\": 42,\n    \"has_open_graph\": true\n  },\n  \"fixes\": [\n    { \"signal\": \"has_faq_schema\", \"suggestion\": \"Page already has question-style H2s. Wrap them in FAQPage JSON-LD - high-leverage win.\", \"estimated_lift\": \"high\" },\n    { \"signal\": \"h2_question_count\", \"suggestion\": \"Reframe at least 2 H2s as questions users actually ask...\", \"estimated_lift\": \"medium\" }\n  ]\n}\n```\n\nThe Wikipedia signal is measured (it correlates with citation) but no \"go get a Wikipedia article\" suggestion is emitted - the advice would be non-actionable. Scoring is split across six buckets - domain authority, structured data, content depth, link graph, freshness, metadata - so a thin page and a deep page on the same domain get meaningfully different scores.\n\n---\n\n## Workflow recipes\n\nConcrete patterns that compose the 26 tools into something useful. Costs assume ChatGPT or Perplexity at ~$0.01-0.03/query.\n\n### 1. Weekly citation tracker\n\nThe single highest-ROI pattern. Pick 20-30 queries from your editorial backlog, snapshot weekly, watch the rate trend.\n\n```\n# One-time setup\npanel_track name=\"editorial-watchlist\" domain=\"example.com\" action=\"save\"\n            queries=[\"best widget tutorial\", \"how to set up X\", ...]\n\n# Weekly cron (5 min, ~$0.20-0.60 per run)\npanel_run name=\"editorial-watchlist\"\n\n# Anytime\ncitations_trend panel=\"editorial-watchlist\"\n```\n\n`citations_trend` returns per-query deltas: which queries flipped from `cited: false` to `cited: true` since the first snapshot. That's your real editorial-impact metric.\n\n### 2. Pre-publish gate\n\nBefore publishing a post, find out who owns the citation slot and whether the slot is worth competing for.\n\n```\n# 1. Is there an AI Overview to compete for?\nsignals_ai_overview query=\"<target query>\"\n\n# 2. Who is cited today?\ncitations_check query=\"<target query>\"\n\n# 3. After publish + 14 days: did the post break in?\ndomain_am_i_cited domain=\"example.com\" queries=[\"<target query>\"]\n```\n\nIf `citations_check` returns 5+ strong incumbents on a low-volume query, pick a different angle. If `ai_overview_present: false`, the query has no AI surface - reconsider.\n\n### 3. Bulk site audit\n\nCatch site-wide structural issues across every page in one pass. Zero API spend.\n\n```\naudit_sitemap sitemap_url=\"https://example.com/sitemap.xml\" limit=200\n```\n\nReturns `worst_first` sorted by citation-likelihood score. Surfaces missing schema, conflicting canonicals, missing `/llms.txt`, broken HTTPS.\n\n### 4. Competitor signal gap\n\nYou're not cited; they are. Why?\n\n```\n# 1. Find the top-cited URLs for your target query\ncitations_check query=\"<query>\"\n\n# 2. Compare your URL to theirs signal-by-signal\ncompetitors_compare urls=[\n  \"https://example.com/your-post\",\n  \"https://competitor-1.com/their-post\",\n  \"https://competitor-2.com/their-post\"\n]\n```\n\n`diverging_signals` is the list of where you're losing. Usually obvious once you see it - they have FAQ schema, GitHub references, Wikipedia links - you don't.\n\n### 5. Google-rank vs AI-citation gap\n\nThe closest editorial wins are queries where you already rank in Google's top 10 but are invisible to AI. Requires a GCP service account with `webmasters.readonly` scope.\n\n```\nsignals_gsc_gap\n  domain=\"example.com\"\n  queries=[\"...editorial watchlist...\"]\n  start_date=\"2026-04-01\"\n  end_date=\"2026-05-01\"\n```\n\n`closest_wins` returns queries with `position <= 10` and `ai_cited: false`, sorted by impressions desc. Push citation signals on those specific URLs first.\n\n### 6. Wikipedia mention monitor\n\nWikipedia is the top-correlation signal but the advice \"get on Wikipedia\" is useless. So instead: watch when it happens organically.\n\n```\nsignals_wikipedia domain=\"example.com\" limit=50\n```\n\nReturns Wikipedia article URLs that already link to the domain. Re-run quarterly; the diff is your \"we got a Wikipedia citation\" alert.\n\n## Schema.org\n\n```json\n{\n  \"@context\": \"https://schema.org\",\n  \"@type\": \"SoftwareApplication\",\n  \"name\": \"Citation Intelligence MCP\",\n  \"applicationCategory\": \"DeveloperApplication\",\n  \"operatingSystem\": \"Cross-platform\",\n  \"description\": \"Self-hosted MCP server for querying AI citation data from Perplexity, Claude, ChatGPT, Gemini, Bing, and Google AI Overviews.\",\n  \"offers\": { \"@type\": \"Offer\", \"price\": \"0\" },\n  \"url\": \"https://github.com/AutomateLab-tech/citation-intelligence\"\n}\n```\n\n## Contributing\n\nBug reports, feature ideas, and PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## Security\n\nReport a vulnerability via [SECURITY.md](./SECURITY.md).\n\n## License\n\nMIT - see [LICENSE](./LICENSE).\n\nBuilt by [automatelab.tech](https://automatelab.tech)\n",
  "bytes": 18653,
  "sha": "3bea95a963e8c1629583e5dbbee72282ad4d31c10156c9546f02779188da87b0",
  "repo_slug": "automatelab-tech/citation-intelligence",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_automatelab_tech_citation_inte_d5a35716/readme"
}