com.metricspot/seo-mcp

Official6 tools

by MetricSpot · TypeScript

Six tools for SEO and AI-readability audits. 91 checks, 11 score modules.

Run SEO audits and AI-readability checks with 91 metrics and scoring modules.

Topics

ai-agentsanthropicbunclaudemcpmodel-context-protocolseotypescriptmetricspot

Captured live from the server via tools/list.

run_audit_anonymous

Run a one-shot SEO + AI-readability audit on any public URL. Returns scores across 11 modules and ~90 checks, plus actionable findings with rule docs. Limited to 1 audit per IP per 24 hours — for higher volume, get an API key at https://app.metricspot.com/settings/api-keys and use `run_audit`. Synchronous: blocks until the audit completes. Does NOT include Core Web Vitals (use `run_audit` for full PSI scoring). No auth required.

Parameters (1)

urlstringrequired

run_audit

Queue a full SEO + AI-readability audit (includes Core Web Vitals from Google PSI and organic traffic if Google is linked). Returns the audit envelope immediately with `status: queued` and an `audit_id`. Poll `get_audit` with the returned `audit_id` until `status` becomes `complete` (typical 10-30s). Counts against the user's plan allowance. Requires an API key as a Bearer token. Quota and per-domain cooldowns mirror the dashboard.

Parameters (1)

urlstringrequired

get_audit

Fetch a previously-run audit by id. Returns module scores (0-100), total score, all findings with severity, recommendation text, and links to the HTML report. Use this to poll a queued `run_audit` until `status: complete`. Requires an API key.

Parameters (1)

audit_idstringrequired

list_audits

List the user's audits (most recent first, deduplicated by URL). Returns `audit_id`, `url`, `status`, `total_score`, `created_at`. Default limit 24, max 100. Use the returned `audit_id` with `get_audit` for full findings. Requires an API key.

Parameters (1)

limitinteger

get_audit_pdf

Return a signed download URL for the branded PDF report for a given audit id. If no PDF has been rendered yet, queues a render and returns `status: queued` — poll the same tool again, or fetch the URL directly once ready. Requires an API key.

Parameters (1)

audit_idstringrequired

get_organic_traffic

If the user has linked GA4 + Google Search Console, return the 28-day organic traffic snapshot for an audit: session count, daily trend, top landing pages, top queries, and indexing health. Returns `connected: false` if Google is not linked. Cached 24h server-side. Requires an API key.

Parameters (1)

audit_idstringrequired

README.md2 KBView on GitHub

@metricspot/mcp-server

Model Context Protocol server for MetricSpot. Exposes 6 SEO + AI-readability audit tools to AI agents (Claude, ChatGPT, Gemini, Perplexity, Cursor, Zed, OpenClaw, custom bots).

Hosted Streamable HTTP endpoint: https://mcp.metricspot.com/mcp
Local stdio binary: npx @metricspot/mcp-server
Agent guide: https://metricspot.com/AGENTS.md

Tools

Tool	Auth	Description
`run_audit_anonymous`	none	One-shot audit, 1/IP/24h, no Core Web Vitals
`run_audit`	Bearer key	Full audit with PSI, returns `audit_id`
`get_audit`	Bearer key	Fetch audit + findings by id
`list_audits`	Bearer key	List the user's recent audits (max 100)
`get_audit_pdf`	Bearer key	Signed URL for the branded PDF report
`get_organic_traffic`	Bearer key	28-day GA4 + GSC snapshot (if Google linked)

Local install (stdio)

Claude Code (~/.claude/mcp.json):

json

{
  "mcpServers": {
    "metricspot": {
      "command": "npx",
      "args": ["-y", "@metricspot/mcp-server"],
      "env": {
        "MCP_API_KEY": "ms_live_xxx"
      }
    }
  }
}

Cursor (~/.cursor/mcp.json) and Zed use the same shape.

Omit MCP_API_KEY to only use run_audit_anonymous.

Hosted (Streamable HTTP)

code

POST https://mcp.metricspot.com/mcp
Authorization: Bearer ms_live_xxx
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Env vars

Var	Default	Purpose
`PORT`	`3000`	HTTP listen port
`APP_API_BASE_URL`	`https://app.metricspot.com`	MetricSpot app API base (the `dev`/`dev:stdio` scripts override it to `http://localhost:3000`)
`APP_PUBLIC_BASE_URL`	falls back to `APP_API_BASE_URL`	Used to build `report_url`
`MCP_INTERNAL_TOKEN`	—	Service-to-service secret forwarded as `X-MCP-Internal-Token`
`MCP_API_KEY`	—	(stdio only) User API key, sent as `Authorization: Bearer` to the HTTP layer

Develop

bash

bun install
bun run typecheck
bun test
bun run dev          # Streamable HTTP on :3000
bun run dev:stdio    # stdio loop (send JSON-RPC on stdin)

Deploy

Multi-stage Dockerfile produces a Bun runtime image. Independent Dokku app on the same Hetzner droplet as app/ and web/.

License

MIT

Install

Configuration

Environment variables

MCP_API_KEYsecret

Your MetricSpot API key (ms_live_...) from app.metricspot.com/settings/api-keys. Required for 5 of the 6 tools; omit to use only run_audit_anonymous (1 audit per IP per 24 hours, no auth).

claude_desktop_config.json

{
  "mcpServers": {
    "seo-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@metricspot/mcp-server@0.1.1"
      ],
      "env": {
        "MCP_API_KEY": "<YOUR_MCP_API_KEY>"
      }
    }
  }
}