@shipseo/mcp

MCP (Model Context Protocol) server that exposes Shipseo's SEO analysis to any MCP-compatible client — Claude Desktop, Cursor, VS Code (Copilot Chat), Windsurf, Cline, Zed, etc.

Status: v0.4 — ten tools. Five offline (no account needed) + five workspace-scoped (require a Shipseo API key).

🎉 What's new in v0.4 — two read-only tools for surfacing your Shipseo state without leaving the editor:

• get_audit_history(siteId) — past audits with score + delta vs previous. "Cómo evolucionó mi score?"
• get_pending_fixes(siteId) — the actionable "what should I fix next" list from the latest audit

The eight v0.3 tools are untouched. See CHANGELOG.md for the full diff.

Tools

Offline (no account required)

| Tool | What it does | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | audit_url | Full SEO audit of one URL. Returns issues + 0-100 score + raw meta snapshot. | | check_meta | Lean read-only meta snapshot (no issue analysis). Faster than audit_url. | | compare_urls | Audit two URLs, diff them: score delta + which issues were fixed / regressed / unchanged. "Is my new landing page better?" | | suggest_meta | Given URL + target keyword, propose a rewritten <title> and <meta description> (rules-based, keyword front-loaded, length window enforced). | | explain_opportunity | Given URL + target keyword, checklist of what's aligned vs missing to rank for that keyword. Prioritised so the LLM knows where to intervene. |

Workspace-scoped (need SHIPSEO_API_KEY)

| Tool | What it does | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | list_sites | Enumerate every site in your workspace. Use before any tool that needs a siteId. | | run_audit_on_site | Trigger a full audit on a registered site. Persisted in your dashboard, feeds score-drop alerts, consumes 1 from monthly audit quota. | | fetch_audit | Full audit detail by id: severity-sorted issues + descriptions + recommended fixes + per-issue affected URLs. | | get_audit_history | Past audits for a site + score delta between consecutive runs. Answers "how has the score trended?" in one call. | | get_pending_fixes | Auto-fixable issues in the latest audit that still have URLs waiting. The "what should I fix next" list — same source as the dashboard button. |

Prefer the workspace-scoped tools when the site is REGISTERED in Shipseo — audits go into your dashboard history, feed score-drop alerts, and don't count against the preview rate limit.

Install

Claude Desktop

Edit ~/.claude_desktop_config.json (or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "shipseo": {
      "command": "npx",
      "args": ["-y", "@shipseo/mcp"]
    }
  }
}

Restart Claude Desktop. Ask: "Audit the SEO of https://your-site.com" — Claude will call audit_url and render the result.

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "shipseo": {
      "command": "npx",
      "args": ["-y", "@shipseo/mcp"]
    }
  }
}

Restart Cursor. Open Composer/Chat. Ask the same thing — Cursor's agent can now call audit_url and, because it's editing your codebase, iterate on the fixes directly in layout.tsx / sitemap.ts / your metadata files.

VS Code (GitHub Copilot Chat — Agent mode)

Requires VS Code ≥ 1.99 with the GitHub Copilot Chat extension. There are two ways to wire the server.

Option A — Per-workspace (recommended for teams). Create .vscode/mcp.json at the root of your repo:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "shipseo-key",
      "description": "Shipseo API key (sk_live_... from your Pro workspace)",
      "password": true
    }
  ],
  "servers": {
    "shipseo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@shipseo/mcp"],
      "env": {
        "SHIPSEO_API_KEY": "${input:shipseo-key}"
      }
    }
  }
}

You can safely commit this file — the API key never lands in it. VS Code prompts for the value on first use and stores it in the OS-level secret store. Omit the inputs array + env block entirely if you only want the five offline tools.

Option B — Global user setting. Open the Command Palette (Ctrl/Cmd + Shift + P) → MCP: Add Server → pick Command (stdio) → fill in:

• Command: npx
• Args: -y @shipseo/mcp
• Env: SHIPSEO_API_KEY=sk_live_... (skip for offline-only)
• Scope: User

The server is now available in every workspace you open.

Use the tools. Open Copilot Chat (Ctrl/Cmd + Alt + I) → switch the chat mode dropdown to Agent → the Shipseo tools appear in the tools picker. Ask "audit https://myapp.com and fix the top 3 issues" — Copilot picks the right tool and applies edits to your codebase in the same session.

Enable workspace-scoped tools (Pro plan+)

For the three v0.3 tools (list_sites, run_audit_on_site, fetch_audit), grab an API key from your dashboard at /team → API keys (Pro plan or higher) and add it under env:

{
  "mcpServers": {
    "shipseo": {
      "command": "npx",
      "args": ["-y", "@shipseo/mcp"],
      "env": {
        "SHIPSEO_API_KEY": "sk_live_..."
      }
    }
  }
}

Restart the client. Now your LLM can list your sites, trigger persisted audits, and pull full issue detail — all still with natural-language prompts like "audit my landing page in Shipseo and tell me what to fix".

If you don't set SHIPSEO_API_KEY, the five offline tools work fine; the three workspace tools return a friendly "configure this env var" message.

Local dev (from this monorepo, before publishing)

pnpm --filter @shipseo/mcp build

Then point the client at the built entrypoint:

{
  "mcpServers": {
    "shipseo": {
      "command": "node",
      "args": ["/absolute/path/to/shipseo/packages/mcp/dist/index.js"]
    }
  }
}

Try it (manual smoke test)

pnpm --filter @shipseo/mcp dev

The server speaks JSON-RPC over stdin/stdout. Not intended for interactive use — spawn from an MCP client.

Example prompts

Once wired into Claude Desktop / Cursor:

• "Audit https://myapp.com and list the highest-severity SEO issues."
• "Compare the SEO of https://myapp.com/pricing-v1 vs https://myapp.com/pricing-v2 — did the redesign hurt or help?"
• "Propose better <title> and meta description for https://myapp.com/blog/x targeting the keyword 'next.js sitemap'."
• "Why isn't https://myapp.com/blog/x ranking for 'next.js sitemap'? What's the gap?"

The client's LLM (Claude / GPT / whatever) picks the right tool from the descriptions above.

Privacy / telemetry

Since v0.4.1 the server sends an anonymous usage ping to https://shipseo.dev/api/telemetry/mcp after every tool call. Its only purpose is to prioritise the v0.5+ roadmap on real usage data instead of guesses (which tools get called, in which MCP host, how often — nothing tied to your account or code).

What IS sent

• The tool name (e.g. get_pending_fixes).
• The result class: ok, error, or no_key (missing SHIPSEO_API_KEY).
• How long the call took (ms).
• A random sessionId regenerated each time the MCP server starts (so we can group calls from one editor session without any user link).
• The MCP client name + version from the initialize handshake (e.g. Cursor 0.44.2, Claude, vscode).
• Your OS platform (darwin / linux / win32) and Node version.

What is NOT sent — by design

• Any URL you passed to any tool.
• Your SHIPSEO_API_KEY.
• Your workspaceId, userId, or any account identifier (the server never sees them).
• Error messages or stack traces (they might contain URLs / keys).
• Your IP address (the server sees it for rate-limit only, never stores it).

Opt-out

Add SHIPSEO_TELEMETRY: "0" under env in your MCP client config:

{ "mcpServers": { "shipseo": {
  "command": "npx", "args": ["-y", "@shipseo/mcp"],
  "env": {
    "SHIPSEO_API_KEY": "sk_live_...",
    "SHIPSEO_TELEMETRY": "0"
  }
} } }

All tools work identically with telemetry disabled — no feature is gated on it.

Roadmap

v0.4 added the two read-only surfaces (get_audit_history, get_pending_fixes). Next batch (v0.5 — destructive / billed, needs the extra rate-limit + gating design):

• apply_fix(issue_id, page_url) — push a fix to the connected CMS (WordPress, Shopify, Webflow, …) without leaving the editor. The server generates the patch (server-side prompt with the resolved auth) — the LLM cannot inject markup directly.
• check_ai_visibility(prompt) — trigger a Perplexity / Gemini / AI-Overview visibility check. Gated by a daily budget cap on top of the existing per-hour rate limit because each call spends real Perplexity/Gemini quota.

Priority is decided by which tools the dev community actually calls in real Cursor / Claude Desktop / VS Code sessions (we instrument anonymised tool-name counts before v1).