SurferSEO MCP Server

The most comprehensive Model Context Protocol (MCP) server for the SurferSEO API. Gives Claude direct access to all 23 SurferSEO tools across 5 domains — Content Editor, SERP Analyzer, Audit, AI Tools, and Account.

Open source & API-key agnostic. You bring your own SurferSEO API key. No key is bundled.

Quick Start (Zero Install)

The fastest way — no cloning, no building. Just add this to your Claude Desktop config and restart.

Get your SurferSEO API key — requires the API add-on or Enterprise plan. Contact [email protected].

Option A — npx (recommended, once published to npm)

{
  "mcpServers": {
    "surferseo": {
      "command": "npx",
      "args": ["-y", "surferseo-mcp"],
      "env": {
        "SURFER_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

npx -y surferseo-mcp downloads and runs the latest published version automatically — no local install needed.

Option B — Clone & Build (available right now from GitHub)

1. Clone the repo

   git clone https://github.com/altlalit/SurferSEO-MCP.git
   cd SurferSEO-MCP

2. Install & build

   npm install
   npm run build

3. Add to Claude Desktop config — replace the path with your actual clone location:

   Windows:

   {
     "mcpServers": {
       "surferseo": {
         "command": "node",
         "args": ["C:/path/to/SurferSEO-MCP/dist/index.js"],
         "env": {
           "SURFER_API_KEY": "YOUR_API_KEY_HERE"
         }
       }
     }
   }

   macOS / Linux:

   {
     "mcpServers": {
       "surferseo": {
         "command": "node",
         "args": ["/path/to/SurferSEO-MCP/dist/index.js"],
         "env": {
           "SURFER_API_KEY": "YOUR_API_KEY_HERE"
         }
       }
     }
   }

4. Restart Claude Desktop — you will see all 23 SurferSEO tools available.

Claude Desktop Config File Location

| OS | Path | |----|------| | Windows | %APPDATA%\Claude\claude_desktop_config.json | | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

Available Tools (23 total)

Content Editor (10 tools)

| Tool | Description | |------|-------------| | surfer_content_editor_list | List all content editors with pagination | | surfer_content_editor_create | Create a new content editor for a keyword | | surfer_content_editor_get | Get content editor status and metadata | | surfer_content_editor_poll | Wait for content editor to complete (async) | | surfer_content_editor_update | Update content or included terms | | surfer_content_editor_get_terms | Get NLP/keyword terms with targets | | surfer_content_editor_get_content | Get HTML content stored in editor | | surfer_content_editor_auto_optimize | Run Auto-Optimize on content | | surfer_content_editor_get_content_score | Get optimization score (0-100) | | surfer_content_editor_get_structural_guidelines | Get word/heading/image count targets |

SERP Analyzer (6 tools)

| Tool | Description | |------|-------------| | surfer_serp_analyzer_create | Run SERP analysis for a keyword | | surfer_serp_analyzer_create_batch | Batch create multiple SERP analyses | | surfer_serp_analyzer_poll | Wait for SERP analysis to complete (async) | | surfer_serp_analyzer_list | List all SERP analyzer queries (CSV) | | surfer_serp_analyzer_get_search_results | Get competitor data CSV | | surfer_serp_analyzer_get_prominent_terms | Get prominent terms CSV |

Audit (3 tools)

| Tool | Description | |------|-------------| | surfer_audit_create | Audit a URL for a target keyword | | surfer_audit_get | Get audit status and results | | surfer_audit_poll | Wait for audit to complete (async, 5-10 min) |

AI Tools (2 tools)

| Tool | Description | |------|-------------| | surfer_humanizer_humanize | Humanize AI-generated text (min 128 chars) | | surfer_ai_detector_detect | Detect AI content probability (model v1/v2/v3) |

Account & Utility (2 tools)

| Tool | Description | |------|-------------| | surfer_workspaces_list | List your organization workspaces | | surfer_locations_list | List supported locations (no auth needed) |

Requirements

• Node.js 18+
• SurferSEO API key — requires the API add-on or Enterprise plan

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | SURFER_API_KEY | Yes | Your SurferSEO API key |

The server exits immediately with a clear error if SURFER_API_KEY is missing.

API & Rate Limit Notes

| Endpoint group | Rate limit | |----------------|------------| | Most endpoints | 10 req/sec | | SERP Analyzer batch | 10 req/min | | AI Detector | 60 req/min | | SERP queries | 100/day |

• Authentication: Uses API-KEY header (not Authorization: Bearer)
• Async operations: Content Editor, Audit, and SERP Analyzer run asynchronously. Use the _poll tool to wait for completion or _get to check status manually.
• Credits: Each API operation consumes SurferSEO credits. No sandbox environment.
• Workspace: Most write operations accept an optional workspace_id to target a specific workspace.

Development

git clone https://github.com/altlalit/SurferSEO-MCP.git
cd SurferSEO-MCP
npm install

# Run without building (ts-node)
SURFER_API_KEY=your_key npm run dev

# Production build
npm run build
npm start

Publish to npm (maintainers)

npm login
npm publish

After publishing, the zero-install npx config above works for all users.

Project Structure

src/
├── index.ts              # Entry point — wires all 5 domains
├── client.ts             # Axios HTTP client, retry + polling helpers
├── types.ts              # Shared TypeScript interfaces
├── schemas/              # Zod validation schemas per domain
│   ├── content-editor.schemas.ts
│   ├── serp-analyzer.schemas.ts
│   ├── audit.schemas.ts
│   ├── ai-tools.schemas.ts
│   └── account.schemas.ts
└── tools/                # MCP tool registrations per domain
    ├── content-editor.ts
    ├── serp-analyzer.ts
    ├── audit.ts
    ├── ai-tools.ts
    └── account.ts

Contributing

Pull requests welcome! Please open an issue first to discuss what you'd like to change.

1. Fork the repo
2. Create a feature branch: git checkout -b feat/my-feature
3. Commit and push your changes
4. Open a Pull Request

Resources

• SurferSEO API Docs
• API Introduction
• API Examples
• Model Context Protocol

License

MIT — see LICENSE for details.