# SurfRank MCP Server

> Let your AI agent run AI-visibility reports, research keywords, and track competitors on [SurfRank](https://surfrank.ai) — directly from the chat window.

[![npm version](https://img.shields.io/npm/v/@surfrank/mcp-server.svg?color=7c3aed)](https://www.npmjs.com/package/@surfrank/mcp-server)
[![license](https://img.shields.io/npm/l/@surfrank/mcp-server.svg)](./LICENSE)
[![node](https://img.shields.io/node/v/@surfrank/mcp-server.svg)](https://nodejs.org)

This package exposes the [SurfRank](https://surfrank.ai) public API as [Model Context Protocol](https://modelcontextprotocol.io) (MCP) tools, so any MCP-compatible AI assistant — **Claude Desktop, Claude Code, Cursor, Windsurf, ChatGPT MCP connectors**, and others — can call SurfRank on your behalf.

---

## What is SurfRank?

SurfRank measures how visible your brand is inside AI answers (ChatGPT, Perplexity, Gemini, Claude, Grok, DeepSeek, Meta AI). It runs your tracked keywords against each engine, scores your mentions against competitors, and surfaces the content opportunities that would move the needle.

## What is MCP?

The **Model Context Protocol** is an open standard from Anthropic that lets AI agents discover and call external tools. Install this server once, and your agent gets 24 new abilities — no plugin APIs, no OAuth dance, no glue code.

---

## What you can ask your agent once this is connected

> 💬 *"Create a SurfRank project for surfrank.ai in the SaaS industry, then track these 10 keywords…"*

> 💬 *"What did my latest AI visibility report show? Which engines are missing my brand?"*

> 💬 *"Run a quick test for competitor.com and compare it to my score."*

> 💬 *"List my top 5 content opportunities and draft articles for the highest-impact ones."*

The agent picks the right tool, calls the SurfRank API with your key, and replies in natural language. Credits come out of your SurfRank account at the same rate as direct API calls.

---

## Requirements

- **Node.js 18 or newer** (required by the MCP SDK).
- A **SurfRank API key** on the **Pay As You Go** plan. Generate one at [app.surfrank.ai/api-management](https://app.surfrank.ai/api-management).
- An MCP-compatible client (see the Configuration section).

---

## Install

Run ad-hoc with `npx` — no install needed:

```bash
npx -y @surfrank/mcp-server
```

Or install globally:

```bash
npm install -g @surfrank/mcp-server
```

---

## Configuration

Pick your client below and paste the snippet into its MCP config file.

### Claude Desktop

Edit your Claude Desktop config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "surfrank": {
      "command": "npx",
      "args": ["-y", "@surfrank/mcp-server"],
      "env": {
        "SURFRANK_API_KEY": "sr_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. You should see **surfrank** appear in the MCP servers menu.

### Cursor

Edit `~/.cursor/mcp.json` (or use Settings → MCP → Add server):

```json
{
  "mcpServers": {
    "surfrank": {
      "command": "npx",
      "args": ["-y", "@surfrank/mcp-server"],
      "env": {
        "SURFRANK_API_KEY": "sr_your_key_here"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add surfrank -- npx -y @surfrank/mcp-server
export SURFRANK_API_KEY=sr_your_key_here
```

### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "surfrank": {
      "command": "npx",
      "args": ["-y", "@surfrank/mcp-server"],
      "env": { "SURFRANK_API_KEY": "sr_your_key_here" }
    }
  }
}
```

---

## Available tools

The server exposes every SurfRank public-API endpoint as a tool (24 in total). Your agent discovers them automatically — you don't need to list them in your prompt.

| Category | Tools |
|---|---|
| **Projects** | `list_projects`, `get_project`, `create_project`, `update_project`, `delete_project` |
| **Keywords** | `list_keywords`, `add_keyword`, `add_keywords_bulk`, `delete_keyword` |
| **Reports** | `trigger_report`, `list_reports`, `get_report`, `get_latest_analyses` |
| **Quick Test** | `run_quick_test`, `list_quick_tests`, `get_quick_test`, `select_quick_test_keywords` |
| **Keyword Research** | `research_keyword`, `list_keyword_research`, `get_keyword_research` |
| **Competitors** | `list_competitors`, `add_competitor`, `delete_competitor` |
| **Opportunities** | `list_opportunities` |

Each tool maps 1:1 to a REST endpoint under `https://api.surfrank.ai/api/v1/public/*`.

---

## Scoped API keys

If you generate a **project-scoped** API key, the MCP server can only operate on that project. Any tool call that references a different project ID is rejected with a `403` from the SurfRank API, and the error surfaces verbatim in the agent's response.

This is the recommended setup when you're connecting a single workspace or a teammate to a single brand.

---

## Credit usage

Credits are deducted from your SurfRank account per the same pricing as direct API calls:

| Operation | Cost |
|---|---|
| Quick test | 1 credit flat |
| Keyword research | 0.5 × number of engines |
| Report trigger | 0.3 × keywords × engines |
| Everything else (list / get / update) | free |

Every tool response includes a `credits` object so your agent (and you) can track usage in real time.

---

## Environment variables

| Variable | Required | Default | Purpose |
|---|---|---|---|
| `SURFRANK_API_KEY` | ✅ | — | Your API key (`sr_…`) |
| `SURFRANK_API_URL` | — | `https://api.surfrank.ai/api/v1/public` | Override for staging / local development |

---

## Debugging

Use the official MCP inspector to poke at the server directly — useful when onboarding a new client or diagnosing a connection issue:

```bash
SURFRANK_API_KEY=sr_your_key_here \
  npx @modelcontextprotocol/inspector npx @surfrank/mcp-server
```

The inspector opens a browser UI where you can list tools and call them manually, exactly as an AI agent would.

---

## Security notes

- API keys are **shown once** on creation and stored as SHA-256 hashes on SurfRank's servers. If you lose a key, revoke and regenerate it — it can't be recovered.
- Credentials stay in your local MCP config file. This package never writes them to disk and never phones home.
- Each API key is rate-limited to **60 requests per minute**. Exceeding it returns HTTP `429`.

---

## Links

- 🌐 SurfRank — [surfrank.ai](https://surfrank.ai)
- 🔑 API Management — [app.surfrank.ai/api-management](https://app.surfrank.ai/api-management)
- 📘 Public API docs — in the API Management → Documentation tab
- 🐛 Issues — [github.com/SurfRankAI/mcp-server/issues](https://github.com/SurfRankAI/mcp-server/issues)
- 📦 npm — [@surfrank/mcp-server](https://www.npmjs.com/package/@surfrank/mcp-server)

---

## License

MIT © SurfRank Pte. Ltd. — see [LICENSE](./LICENSE).