@signalsumo/mcp

Model Context Protocol server for SignalSumo. Lets Claude, Cursor, and any other MCP-compatible client read your SEO data, run technical audits, research keywords, and check backlink profiles through natural-language tool calls.

Every tool wraps a real endpoint on the SignalSumo REST API (/api/v1/*). Auth, plan gating, quotas and billing all happen server-side — the MCP layer is a thin, well-typed shim.

What it exposes today

Eleven read-only tools. Every one reads data your SignalSumo account already holds — this server computes nothing of its own, so the "Produced by" column is the product that generates each dataset.

Rankings

Research

Audits

AI visibility

Search Console

Account

Reading is free. run_site_audit and research_keyword start work that consumes plan credits; everything else reads data you have already paid for.

More tools follow the same pattern — one file per tool in src/tools/, registered in src/index.ts. Full REST reference: signalsumo.com/api-docs. Prefer no install? The hosted connector speaks the same tools over OAuth.

Related MCP server: Search Console MCP

Quick start

1. Get an API key

Sign in to SignalSumo → API Keys → create a key. Copy it once — it won't be shown again.

2. Install

npm install -g @signalsumo/mcp

Or run without installing via npx:

npx -y @signalsumo/mcp

3. Wire it into your MCP client

Claude Desktop — edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "signalsumo": {
      "command": "npx",
      "args": ["-y", "@signalsumo/mcp"],
      "env": {
        "SIGNALSUMO_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You should see the SignalSumo tools available in the tool picker.

Claude Code — add to ~/.claude/mcp_servers.json (same shape as above).

Cursor — Settings → MCP → Add a new server with command: npx, args: ["-y", "@signalsumo/mcp"], and set SIGNALSUMO_API_KEY in the env.

ChatGPT — this package will not help you, and that is not a limitation of the package. ChatGPT connects to MCP servers as remote HTTPS connectors rather than spawning a local process, so there is nothing for npx to do. Point it at the hosted connector instead:

https://signalsumo.com/mcp

It exposes the same tools, authenticates with OAuth rather than an API key, and needs no install. Setup steps are at signalsumo.com/mcp-server.

The same applies to any client that takes a URL rather than a command — the split is stdio versus HTTP, not one vendor versus another.

4. Try it

Ask Claude:

"What SEO tools do I have available through SignalSumo? Check my API usage first."

Claude will call get_api_usage and describe what it can do with the other tools.

Local development

git clone https://github.com/signalsumo/mcp
cd mcp
npm install
cp .env.example .env  # add your key
npm run build
SIGNALSUMO_API_KEY=sk_live_... node dist/index.js

Point Claude Desktop at your local build — replace the path with wherever you cloned the repo:

{
  "mcpServers": {
    "signalsumo-dev": {
      "command": "node",
      "args": ["/path/to/signalsumo-mcp/dist/index.js"],
      "env": {
        "SIGNALSUMO_API_KEY": "sk_live_..."
      }
    }
  }
}

Hosted / multi-tenant mode (HTTP + SSE)

The package ships a second entry point for self-hosting the MCP server as a shared HTTP endpoint. This is what remote MCP clients (claude.ai's remote MCP registry, hosted Cursor, browser-based inspectors) connect to.

Transport: Streamable HTTP per the MCP 2025-06-18 spec — POST for client → server calls, GET for the SSE stream, DELETE to end a session. Session isolation is per-connection; each session gets its own Server + SignalSumoClient so keys and state never leak between users.

Auth: every request must carry Authorization: Bearer <signalsumo_api_key>. The key is resolved at session-init and used for every subsequent call in that session — the process itself holds no keys.

Run the HTTP server

npm run start:http
# or as an installed bin:
signalsumo-mcp-http

Env vars:

• MCP_PORT — port to listen on (default 3000)

• MCP_HOST — bind address (default 0.0.0.0)

• SIGNALSUMO_API_BASE — API base URL (default https://signalsumo.com/api/v1)

Endpoints

Reverse proxy

Put it behind nginx/Caddy on a subdomain (e.g. mcp.signalsumo.com), terminate TLS there, and forward /mcp to the Node process. SSE requires HTTP/1.1 with buffering disabled — nginx snippet:

location /mcp {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header Authorization $http_authorization;
    proxy_buffering off;              # critical for SSE
    proxy_cache off;
    proxy_read_timeout 24h;
    chunked_transfer_encoding off;
}

Point a client at the hosted server

For MCP clients that accept a URL + Bearer token (e.g. custom scripts, MCP Inspector, ChatGPT, remote-server support in Claude clients), SignalSumo runs a hosted endpoint — nothing to deploy:

URL:     https://signalsumo.com/mcp
Header:  Authorization: Bearer sk_live_...

That endpoint also speaks OAuth 2.1, which is what the Claude and ChatGPT connector flows use instead of a raw key — see the section below and signalsumo.com/mcp-server.

If you have self-hosted this package on your own subdomain, substitute your own host and /mcp path in the URL above.

OAuth 2.1 (for the claude.ai/mcp remote registry)

OAuth is handled by the SignalSumo authorization server at https://signalsumo.com — the MCP HTTP endpoint here is just the resource server. MCP clients that speak OAuth 2.1 (Claude Desktop's remote MCP support, claude.ai/mcp) discover everything automatically:

1. Client hits /mcp without a token → server replies 401 with WWW-Authenticate: Bearer error="unauthorized", resource_metadata="https://signalsumo.com/.well-known/oauth-protected-resource"

2. Client fetches the resource metadata → learns the authorization server is https://signalsumo.com

3. Client fetches https://signalsumo.com/.well-known/oauth-authorization-server → learns the endpoints

4. Client POSTs to /oauth/register → gets a client_id (Dynamic Client Registration, RFC 7591)

5. Client opens /oauth/authorize?... in a browser tab → user logs into SignalSumo and clicks "Authorize"

6. Client POSTs to /oauth/token with the auth code + PKCE verifier → gets an access token

7. Client uses the access token as Authorization: Bearer <token> on /mcp

The access token is validated by SignalSumo's ApiAuth — the same class that validates raw API keys — so the MCP server itself doesn't need to know about OAuth. Access tokens live 1 hour; refresh tokens are rotated on every use per OAuth 2.1.

Architecture

src/
├── index.ts              # stdio entry (single-user, Claude Desktop / Cursor)
├── server-http.ts        # HTTP + SSE entry (multi-tenant, self-hosted)
├── build-server.ts       # shared: builds an MCP Server with all tools registered
├── client.ts             # Axios wrapper around SignalSumo /api/v1
└── tools/
    ├── types.ts          # Shared ToolDefinition interface
    ├── usage.ts          # get_api_usage
    ├── backlinks.ts      # get_backlinks
    ├── site_audit.ts     # run_site_audit (async)
    ├── keyword_research.ts # research_keyword (async)
    ├── job_status.ts     # get_job_status
    ├── rank_keywords.ts  # list_tracked_keywords
    ├── rank_history.ts   # get_rank_history
    ├── gsc_properties.ts # list_gsc_properties
    ├── gsc_queries.ts    # get_gsc_queries
    ├── ai_visibility_projects.ts # list_ai_visibility_projects
    └── ai_share_of_voice.ts      # get_ai_share_of_voice

Both transports register the same tools — the only difference is where the API key comes from (env var for stdio, per-request header for HTTP).

Adding a new tool — copy an existing file in src/tools/, wire the Zod input schema, call client.get() / client.post(), then register it in the tools array in src/index.ts. Rebuild, restart your MCP client, done.

Boundaries

The MCP inherits your API key's trust level. It can do anything the key can do — no more, no less. Endpoints intentionally not exposed as tools even though they exist on the REST API:

• Billing / plan changes / credit purchases

• User account or password reset

• Team management

• Admin-only endpoints

Roadmap

• Read-only rank tracker tools (list_tracked_keywords, get_rank_history)

• Read-only AI visibility tools (list_ai_visibility_projects, get_ai_share_of_voice)

• Read-only GSC tools (list_gsc_properties, get_gsc_queries)

• HTTP + SSE transport (in addition to stdio)

• OAuth 2.1 flow for the claude.ai/mcp remote registry

• Write-capable rank tracker tools (add_keyword_to_tracker, trigger_rank_scan)

• Local SEO tools (grid rank, review AI, citation status)

• Report generation (generate_executive_report)

License

MIT