# MentionsAPI MCP Server

[![npm version](https://img.shields.io/npm/v/%40mentionsapi%2Fmcp)](https://www.npmjs.com/package/@mentionsapi/mcp)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Ask your AI agent whether AI recommends your brand. **MentionsAPI** tracks brand visibility across **every AI search surface** — ChatGPT, Claude, Gemini, Perplexity, Google AI Overviews, Google AI Mode, and Bing Copilot — and this MCP server puts that data inside any MCP-compatible client.

Ask in plain English. Get structured data back.

```
You: "Is HubSpot mentioned when users ask ChatGPT about CRMs?"
Claude: [calls mentions_check via MCP]
        "Yes — ranked 3rd in ChatGPT's answer. Top 3:
         HubSpot, Salesforce, Pipedrive. Fan-out queries
         issued during search: ..."
```

---

## Two ways to connect

### Option 1 — Remote server (recommended, zero install)

**`https://api.mentionsapi.com/mcp`** — Streamable HTTP with OAuth (one-click on claude.ai) or `Authorization: Bearer lvk_live_...`.

- **claude.ai / Claude Desktop:** Settings → Connectors → Add custom connector → paste the URL above, then approve via OAuth.
- **Claude Code:**

  ```bash
  claude mcp add --transport http mentionsapi https://api.mentionsapi.com/mcp
  ```

- **Any Streamable-HTTP client:** point it at the URL and send your API key as a Bearer token.

### Option 2 — Local stdio server (npm)

```bash
npx -y @mentionsapi/mcp@latest
```

#### Claude Code (`~/.claude.json`)

```json
{
  "mcpServers": {
    "mentionsapi": {
      "command": "npx",
      "args": ["-y", "@mentionsapi/mcp@latest"],
      "env": { "MENTIONSAPI_KEY": "lvk_live_..." }
    }
  }
}
```

#### Cursor (`~/.cursor/mcp.json`) — same shape

#### Windsurf (`~/.codeium/windsurf/mcp_config.json`) — same shape

#### ChatGPT Plus — see [docs/mcp/chatgpt-plus](https://mentionsapi.com/docs/mcp/chatgpt-plus)

---

## Get started in 60 seconds

1. **Sign up — free, no card, $1 free credit** → https://mentionsapi.com/signup
2. **Mint an API key** (looks like `lvk_live_...`) → https://mentionsapi.com/app/keys
3. **Connect** using either option above
4. **Ask:** *"Use mentions_check to see if Notion appears for 'best CRM for startups' across all 4 LLMs."*

---

## Tools (4)

| Tool | What it does | Cheapest mode |
|---|---|---|
| `mentions_check` | Check if a brand is mentioned across AI search surfaces | $0.02 (`mode:quick`, cached) |
| `mentions_watch` | Persistent monitor with HMAC-signed webhook on changes | $1/run |
| `mentions_discover` | Suggest 50 queries to track for a brand | $0.50 |
| `mentions_compare` | Side-by-side delta between two brands | $1.50 |

## 8 modes for `mentions_check`

| Mode | Cost | What |
|---|---|---|
| `quick` | $0.39 fresh / $0.02 cached | All 4 LLM APIs in parallel — ChatGPT, Claude, Gemini, Perplexity |
| `perplexity_live` | $0.25 | Real Perplexity UI scrape — citations + fan-out queries |
| `chatgpt_live` | $0.10 | Real ChatGPT UI scrape — fan-out + brand entities |
| `gemini_live` | $0.10 | Real Gemini UI scrape |
| `ai_overview` | $0.05 | Google's AI Overviews block |
| `ai_mode` | $0.10 | Google's dedicated AI Mode |
| `bing_copilot` | $0.05 | Bing Copilot AI overview |
| `all_live` | $0.50 | All 6 live UI scrapes in one call |

---

## Pricing

**PAYG only.** No subscriptions, no monthly minimums.

- **$1 free signup credit** — no card required
- **$5 minimum top-up** — Stripe Checkout, card saved
- **Optional auto-recharge** when wallet runs low

Top up: https://mentionsapi.com/app/billing

---

## Env vars (stdio server)

| Var | Required | Default |
|---|---|---|
| `MENTIONSAPI_KEY` | Yes | — |
| `MENTIONSAPI_URL` | No | `https://api.mentionsapi.com` |

---

## Error handling

The MCP returns structured errors the AI agent can relay to you in plain English:

- **`auth_required`** — no API key set; includes signup URL
- **`auth_invalid`** — key was rejected; rotate at /app/keys
- **`insufficient_balance`** — wallet empty; top-up URL included
- **`rate_limit_exceeded`** — includes `retry_after_seconds`
- **`mode_roadmap`** — for `deep`/`change_track` (Q3 2026)

The server starts even without an API key — your AI agent will guide you through setup the first time you call a tool.

---

## Agent skills

Prefer skills over raw tools? Install the companion skill pack:

```bash
npx skills add nikhonit/llm-mentions-skills
```

→ https://github.com/nikhonit/llm-mentions-skills

---

## Docs & links

- Quickstart — https://mentionsapi.com/docs/quickstart
- API reference — https://mentionsapi.com/docs/api/check
- MCP setup guides — https://mentionsapi.com/docs/mcp
- Recipes — https://mentionsapi.com/docs/recipes
- Privacy policy — https://mentionsapi.com/legal/privacy

---

## License

MIT