🚀 Quick Start

Two ways to connect — pick what fits your needs.

Option A: Direct Connection (30 seconds)

Works for site audits, crawling, schema validation, Core Web Vitals, and IndexNow. No Google account needed.

{
  "mcpServers": {
    "seo": {
      "url": "https://api.seomcp.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_key_here"
      }
    }
  }
}

Option B: Proxy (All 37 Tools + Google Data)

Unlocks GSC and GA4 tools. Your Google credentials never leave your machine — the proxy reads them locally and forwards requests securely.

{
  "mcpServers": {
    "seo": {
      "command": "npx",
      "args": ["-y", "github:quantacodes/seomcp-proxy"],
      "env": {
        "SEOMCP_API_KEY": "sk_live_your_key_here",
        "GOOGLE_SERVICE_ACCOUNT": "/path/to/service-account.json",
        "GSC_PROPERTY": "sc-domain:example.com",
        "GA4_PROPERTY": "properties/123456"
      }
    }
  }
}

🔑 Authentication

All MCP requests require an API key passed as a Bearer token.

API Key Format

API keys follow this format:

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Usage

Include your key in the Authorization header:

Authorization: Bearer sk_live_your_key_here

Key Management

• Create and revoke keys from your dashboard
• Keys are shown only once at creation — store them securely
• Revoked keys stop working immediately
• Free plan: 1 key, Pro: 5 keys, Agency: 20 keys

🔌 Connection Methods

seomcp.dev speaks the Model Context Protocol (MCP) — the standard for AI tool connections.

Endpoint

POST https://api.seomcp.dev/mcp

Transport

We use Streamable HTTP transport (the MCP standard). Your first request must be an initialize call. The server returns a session ID in the Mcp-Session-Id header.

Config Snippets

Claude Desktop / Claude Code

{
  "mcpServers": {
    "seo": {
      "url": "https://api.seomcp.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

Cursor / Windsurf

{
  "mcpServers": {
    "seo": {
      "url": "https://api.seomcp.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

Any MCP Client (cURL test)

curl -X POST https://api.seomcp.dev/mcp \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

🧰 Available Tools (37)

All tools are accessible through the MCP protocol. Your AI agent discovers them automatically via tools/list.

Crawl & Audit

Google Search Console (8 tools)

Google Analytics 4 (9 tools)

Schema & Validation (2 tools)

Core Web Vitals (1 tool)

IndexNow (4 tools)

Sitemaps & Storage

💡 GSC and GA4 tools require Google service account setup.

🔑 Google Service Account Setup

Required for GSC and GA4 tools. Takes about 5 minutes. Your credentials stay on your machine — they're never stored on our servers.

Step 1: Create a Google Cloud project

1. Go to Google Cloud Console
2. Create a new project (or select an existing one)

Step 2: Enable APIs

Enable these APIs in your project:

• Google Search Console API
• Google Analytics Data API
• PageSpeed Insights API (optional, for Core Web Vitals)

Step 3: Create service account

1. Go to IAM → Service Accounts
2. Click "Create Service Account"
3. Name it (e.g., seo-mcp)
4. Skip the optional role/permission steps
5. Click "Keys" → "Add Key" → "Create new key" → JSON
6. Save the downloaded JSON file (e.g., ~/service-account.json)

Step 4: Grant access

Share your properties with the service account email (looks like seo-mcp@your-project.iam.gserviceaccount.com):

• Google Search Console: Go to Search Console → Settings → Users and permissions → Add user (Full or Restricted)
• Google Analytics: Go to GA4 → Admin → Property → Property Access Management → Add user (Viewer role)

Step 5: Find your property IDs

# GSC property (one of these formats):
GSC_PROPERTY="sc-domain:example.com"          # Domain property
GSC_PROPERTY="https://www.example.com/"       # URL-prefix property

# GA4 property ID (find in GA4 → Admin → Property Details):
GA4_PROPERTY="properties/123456789"

Security

• The JSON file never leaves your machine — the proxy reads it locally
• Credentials are sent to our API over HTTPS, used for 1-15 seconds, then the process dies
• Nothing is logged, stored, or persisted on our servers
• Credentials are re-read from disk on every request — rotate keys without restarting

⏱️ Rate Limits

Rate limits are enforced per user (not per key) on a monthly rolling window.

When rate limited

The MCP tool call will return an error with a message indicating you've exceeded your plan limit. The usage counter resets on the 1st of each month.

❌ Error Handling

Errors follow MCP JSON-RPC error format.

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Rate limit exceeded"
  },
  "id": 1
}

HTTP Status Codes

💳 Billing

Billing is handled by Lemon Squeezy. Upgrade, downgrade, or cancel anytime from your dashboard.

Plan changes

• Upgrade: Takes effect immediately. Your usage limit increases right away.
• Downgrade: Takes effect at end of billing period. You keep your current limits until then.
• Cancel: Access continues until end of billing period. You can resume before it expires.

Payment methods

Cards (Visa, Mastercard, Amex), PayPal, and Apple Pay via Lemon Squeezy.