@mentionbeat/mcp-server

An MCP server that puts your AI-visibility measurements inside Claude (Code / Desktop), Cursor, or any other MCP client.

Ask "what's our share-of-voice trend, and is the latest change real or noise?" and the assistant answers from your live MentionBeat data — then works the fix queue with you.

claude mcp add mentionbeat --env MENTIONBEAT_API_KEY=<your key> -- npx -y @mentionbeat/mcp-server

Tools

Read the measurements:

| Tool | What it answers | | --- | --- | | list_projects | Which brands/products are tracked | | get_project(slug) | Project status, prompt counts, latest run id | | list_runs(project) | Run history, status, cost | | get_run_metrics(run_id) | Mention rate, share of voice, recommendation rate — with 95% CIs | | get_citations(run_id) | Which domains the engines cite (own / competitor / third party) | | get_benchmark(run_id) | You vs the field: rank, share, leader, median | | get_hallucinations(run_id) | Engine claims that contradict your facts | | get_trends(project, last?) | Headline metrics across runs, CI bands, likely-real deltas | | get_experiments(project) | Measured lift from content changes |

Work the fix queue:

| Tool | Writes? | What it does | | --- | --- | --- | | list_actions(product) | — | The work queue: what to fix, ranked, with the evidence | | get_fix(url) | — | Paste-ready JSON-LD / FAQ / intro for one page | | check_ai_access(domain) | — | Whether AI crawlers can actually reach a site | | run_site_audit(product, site, limit?) | yes | Crawl + audit, adding findings to the queue | | mark_action_fixed(product, action_id) | yes | Mark fixed → triggers an immediate re-check | | verify_actions(product) | yes | Re-check everything marked fixed |

mark_action_fixed returns cleared: false with the reason when the finding is still there, and the item goes back on the queue. An assistant using this server cannot mark its own homework.

Everything runs under your own token, and the server org-scopes every call to exactly what you can already see and do. It exposes no generic request method, so a prompt-injected instruction can't turn it into an arbitrary API proxy.

Setup

You need a MentionBeat account and an API key.

1. Sign in at app.mentionbeat.com.
2. Settings → API keys → Create key. Copy it — it is shown once.
3. Add the server to your client with that key.

The key is durable: it doesn't expire, and revoking it in Settings cuts the integration off immediately. Under the hood the server trades it for a short-lived token before each burst of calls, so nothing long-lived travels to the measurement API. Treat the key like a password.

Claude Code

claude mcp add mentionbeat --env MENTIONBEAT_API_KEY=<your key> -- npx -y @mentionbeat/mcp-server

Then /mcp in a session shows mentionbeat with 15 tools.

Claude Desktop / Cursor / any JSON-configured client

Settings → Developer → Edit Config, then:

{
  "mcpServers": {
    "mentionbeat": {
      "command": "npx",
      "args": ["-y", "@mentionbeat/mcp-server"],
      "env": {
        "MENTIONBEAT_API_KEY": "<your key>"
      }
    }
  }
}

Restart the app; the tools appear under the connectors menu.

Configuration

| Variable | Default | Purpose | | --- | --- | --- | | MENTIONBEAT_API_KEY | (unset) | Your org API key from Settings → API keys. Doesn't expire; revoking it cuts access off at once. Use this one. | | MENTIONBEAT_TOKEN | (unset) | A platform session token pasted directly. Works, but expires in 24 hours — fine for a one-off, wrong for a config file. | | LLMVIS_API_KEY | (unset) | A key minted by a self-hosted measure instance, sent as X-API-Key. Never exchanged. | | PLATFORM_URL | the hosted platform | Where API keys are exchanged for short-lived tokens. | | MEASURE_API_URL | the hosted API | Point at http://localhost:8000 to work against a local measure API. | | STUDIO_URL | the hosted studio | Point at http://localhost:4444 for a local studio. |

Precedence is top-down within the first three; exactly one credential is ever sent.

How the API key works. Measure and produce verify signed tokens — they can't look a key up, so a key can't be sent to them directly, and a long-lived token would be one nobody could revoke. The server therefore exchanges your key for a short-lived token (POST /v1/auth/api-token), caches it until just before it expires, and re-exchanges automatically. Rotate or revoke a key in Settings and the change takes effect within one token lifetime — no restart, no re-paste.

Example questions

• "List our measurement projects and tell me which has the most runs."
• "What's our share-of-voice trend for acme — is the latest change real or noise?"
• "In the latest run, which domains do the engines cite, and are competitors cited where we aren't?"
• "Show hallucinations from run 12 — what are the engines getting wrong about us?"
• "How do we rank against the field in run 12's category benchmark?"
• "Read our action queue, fix the top item on the pricing page, then mark it fixed and re-check."

Troubleshooting

• "Unauthorized (401)" — the key was revoked, or belongs to a different environment. Create a new one in Settings → API keys. (If you pasted a MENTIONBEAT_TOKEN instead, it has expired — switch to a key.)
• "Cannot reach the measure API at …" — no network access to the API, or MEASURE_API_URL points somewhere that isn't running.
• A 503 mentioning authentication — the API you're pointed at hasn't got auth configured yet. That's a server-side setting, not something the client can fix.
• The transport is stdio only; streamable HTTP is planned.

Development

cd packages/mcp-server
npm install
npm run build     # → dist/index.js
npm test          # offline tests (mocked fetch)
npm run dev       # runs the TypeScript source directly

Requires Node ≥ 22.6. Against a local stack:

MEASURE_API_URL=http://localhost:8000 STUDIO_URL=http://localhost:4444 npm start

MIT licensed. Questions: [email protected]