@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

Tool	Wraps	Purpose	Produced by
list_tracked_keywords	GET /rank/keywords	Every keyword you track, with country, device and current position	Rank Tracker
get_rank_history	GET /rank/history	Daily position history for one keyword, plus the URL that ranked	Rank Tracker

Research

Tool	Wraps	Purpose	Produced by
research_keyword	POST /keyword-research	Start keyword research (async — returns job_id)	Keyword Research Tool
get_backlinks	GET /backlinks	Backlink profile for any domain (paginated)	Backlink Checker

Audits

Tool	Wraps	Purpose	Produced by
run_site_audit	POST /site-audit	Start a technical SEO audit (async — returns job_id)	Website Audit Tool
get_job_status	GET /jobs/:id	Poll any async job until done or failed	—

AI visibility

Tool	Wraps	Purpose	Produced by
list_ai_visibility_projects	GET /ai-visibility/projects	Brands you track across AI answer engines	AI Visibility Checker
get_ai_share_of_voice	GET /ai-visibility/share-of-voice	How often each engine names you versus competitors	AI Visibility Checker

Search Console

Tool	Wraps	Purpose	Produced by
list_gsc_properties	GET /gsc/properties	Connected Search Console properties	GSC Insights
get_gsc_queries	GET /gsc/queries	Queries, clicks, impressions and position from GSC	GSC Insights

Account

Tool	Wraps	Purpose	Produced by
get_api_usage	GET /usage	Current-month API usage, plan, quota reset date	Plans & pricing

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.

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

Method	Path	Purpose
GET	/healthz	Liveness probe. Returns {ok, transport, sessions}. No auth.
POST	/mcp	Every client → server MCP call. First call in a session must be initialize — server responds with an Mcp-Session-Id header that subsequent calls must echo.
GET	/mcp	SSE stream for server → client notifications and streamed tool results. Requires Mcp-Session-Id.
DELETE	/mcp	Cleanly terminate a session. Requires Mcp-Session-Id.

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

• [x] Read-only rank tracker tools (list_tracked_keywords, get_rank_history)
• [x] Read-only AI visibility tools (list_ai_visibility_projects, get_ai_share_of_voice)
• [x] Read-only GSC tools (list_gsc_properties, get_gsc_queries)
• [x] HTTP + SSE transport (in addition to stdio)
• [x] 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