SurfRank Server

Let your AI agent run AI-visibility reports, research keywords, and track competitors on SurfRank — directly from the chat window.

npm version license node

This package exposes the SurfRank public API as Model Context Protocol (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.
• An MCP-compatible client (see the Configuration section).

---

Install

Run ad-hoc with npx — no install needed:

npx -y @surfrank/mcp-server

Or install globally:

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

{
  "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):

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

Claude Code

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

Windsurf

Edit ~/.codeium/windsurf/mcp_config.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:

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
• 🔑 API Management — app.surfrank.ai/api-management
• 📘 Public API docs — in the API Management → Documentation tab
• 🐛 Issues — github.com/SurfRankAI/mcp-server/issues
• 📦 npm — @surfrank/mcp-server

---

License

MIT © SurfRank Pte. Ltd. — see LICENSE.