Skip to main content
Glama
SurfRank MCP Server

SurfRank MCP Server

by SurfRankAI

SurfRank MCP 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.

Related MCP server: sightvane-mcp

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.



License

MIT Β© SurfRank Pte. Ltd. β€” see LICENSE.

Available Tools

24 tools
add_competitorC

Add a competitor domain to a project for side-by-side visibility tracking.

Inputs: projectId (required), domain (required), name.

add_keywordA

Add a single keyword (prompt) to a project. SurfRank will query every configured AI engine with this prompt on the next report run.

Inputs: projectId (required), phrase (required).

add_keywords_bulkA

Add multiple keywords to a project in one call. Respects per-plan keyword caps.

Inputs: projectId (required), keywords (required).

create_projectB

Create a new tracked project. Requires domain (the root URL without scheme) and brandName. industry and country are optional but improve analysis quality.

Inputs: domain (required), brandName (required), industry, country.

delete_competitorB

Remove a competitor from a project.

Inputs: projectId (required), competitorId (required).

delete_keywordC

Delete a single keyword from a project.

Inputs: projectId (required), keywordId (required).

delete_projectC

Permanently delete a project and all of its keywords, reports, and analyses.

Inputs: projectId (required).

get_keyword_researchC

Get a single keyword-research run by ID.

Inputs: researchId (required).

get_latest_analysesA

Get the per-keyword analyses from the project's most recent completed report. Useful for inspecting which prompts mention the brand and which engines surfaced it.

Inputs: projectId (required).

get_projectA

Get a single project by its ID. Returns domain, brand, industry, and config.

Inputs: projectId (required).

get_quick_testA

Get a single quick test by ID, including status and results.

Inputs: testId (required).

get_reportB

Get a single report by ID, including score, trends, and per-engine breakdowns.

Inputs: projectId (required), reportId (required).

list_competitorsB

List all tracked competitors for a project.

Inputs: projectId (required).

list_keyword_researchA

List past keyword research runs, optionally filtered by project.

Inputs: websiteId, page, limit.

list_keywordsB

List all tracked keywords (prompts) for a project.

Inputs: projectId (required).

list_opportunitiesA

List content / keyword opportunities flagged for a project β€” prompts where the brand is under-mentioned relative to competitors, ranked by expected impact.

Inputs: projectId (required), status, sortBy, page, +1 more.

list_projectsA

List every SurfRank project (tracked website) the caller has access to. If the API key is scoped to a single project, only that one is returned.

Inputs: no named parameters.

list_quick_testsB

List quick tests, optionally filtered by project.

Inputs: websiteId.

list_reportsA

List recent reports for a project (most recent first).

Inputs: projectId (required), limit.

research_keywordA

Research a keyword across every configured AI engine. Returns volume, intent, related prompts, and competitor mentions. Cost: ~0.5 credits Γ— engines. If the API key is scoped to a project, websiteId must be passed and must match that scope.

Inputs: keyword (required), country, websiteId.

run_quick_testA

Start a "quick test" β€” a low-cost (1 credit) AI-visibility snapshot for a domain. Returns immediately; the test runs asynchronously. Use get_quick_test to poll. If your API key is scoped to a project, websiteId must match that project.

Inputs: domain (required), brandName, country, engines, +1 more.

select_quick_test_keywordsA

After a quick test reaches awaiting_keyword_selection, pick 1–5 keywords to analyse in depth. This kicks off the main analysis pass.

Inputs: testId (required), keywords (required).

trigger_reportA

Queue a new AI-visibility report for a project. Cost: 0.3 credits Γ— keywords Γ— engines. Returns immediately with a job ID (202). Poll get_report or list_reports to check status.

Inputs: projectId (required).

update_projectA

Update an existing project. Pass only the fields you want to change.

Inputs: projectId (required), brandName, industry, country.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 24 tools

    Disambiguation5/5

    Each tool targets a distinct operation on a specific resource (project, keyword, competitor, report, quick test, analysis, opportunity). There is no functional overlap; even similar-sounding tools like get_keyword_research and research_keyword are clearly differentiated by one retrieving past results and the other initiating new research.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., create_project, add_keyword, delete_competitor). The few compound terms like add_keywords_bulk and select_quick_test_keywords still adhere to the pattern. No mixing of conventions like camelCase or inconsistent verb forms.

    Tool Count4/5

    The 24 tools cover the full domain of AI-visibility tracking (projects, keywords, competitors, reports, quick tests, research, opportunities). While slightly above the typical 3-15 range, the count is justified by the breadth of functionality and each tool serves a clear purpose.

    Completeness5/5

    The tool set provides full CRUD for projects, keywords, and competitors, plus lifecycle management for reports and quick tests. Additional tools for keyword research, opportunities, and analyses fill all plausible gaps. No essential operations appear missing.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Connects AI assistants to SE Ranking's SEO and project management APIs to enable natural language queries for keyword research, backlink analysis, and technical audits. It supports comprehensive tasks including competitive analysis, domain traffic tracking, and AI search visibility monitoring.
      100
      1
      Apache 2.0
    • -
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to perform comprehensive SEO and GEO measurements, including site audits, keyword research, ranking tracking, and brand visibility analysis across search engines and generative AI platforms.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to access self-hosted SEO data and workflows, including keyword research, rank tracking, competitor insights, backlinks, site audits, and AI visibility.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Connects AI agents to live SEO data and hosted tools for site audits, keyword research, competitor analysis, local SEO, and link prospecting, with guided workflows for structured search optimization.
      2
      MIT