SEO Analytics

MCP server for Google Search Console (GSC) + Google Analytics 4 (GA4).

How It Works

What .venv Means

• .venv is this project's private Python environment.
• It contains its own Python interpreter and dependencies for this repo only.
• run-local.sh activates .venv so the MCP server runs with the correct package versions.

What stdio Means

• stdio means the MCP client and server communicate through standard input/output streams.
• The client starts run-local.sh, sends tool requests in, and reads JSON responses out.
• No web server or HTTP endpoint is required for the default local setup.

1. Your MCP client (Claude/Codex) launches run-local.sh as a stdio server process.
2. run-local.sh prepares .venv, installs dependencies, loads config/.env, and validates config/service-account.json.
3. The Python server (seo-analytics-mcp) receives tool calls, fetches data from GSC/GA4 using the service account, and computes merged analysis outputs.
4. Results are returned to the MCP client as structured JSON.

Deployment Model

• This project is deployed as a local process on your machine via stdio.
• It is not an HTTP API service by default and does not require cloud hosting.
• To "deploy" it for another environment, clone the repo there, provide config/.env and config/service-account.json, then register that machine's run-local.sh path in the MCP client.

Prerequisites

• Python 3.11+

Quick Start

1. Create local config files from templates:

cp config/.env.example config/.env
cp config/service-account.example.json config/service-account.json

2. Fill required values:

• config/.env
  • DEFAULT_GSC_SITE_URL (required format: sc-domain:example.com)
  • DEFAULT_GA4_PROPERTY_ID
• config/service-account.json
  • Replace all REPLACE_WITH_... fields with real Google service-account values.

3. Run the server:

./run-local.sh

The script creates/uses .venv, installs dependencies, loads config/.env, validates credentials, and starts seo-analytics-mcp over stdio.

MCP Client Setup

Use the local launcher script as the MCP server command:

/absolute/path/to/analytics/run-local.sh

Codex App

Add server:

codex mcp add seo-analytics -- /absolute/path/to/analytics/run-local.sh

Verify:

codex mcp list

Remove:

codex mcp remove seo-analytics

Claude Code CLI

Add server:

claude mcp add -s project seo-analytics -- /absolute/path/to/analytics/run-local.sh

Verify:

claude mcp list

Remove:

claude mcp remove seo-analytics

Claude Desktop App (macOS)

1. Quit Claude Desktop completely.
2. Edit ~/Library/Application Support/Claude/claude_desktop_config.json.
3. Add this server entry (merge into existing mcpServers if present):

{
  "mcpServers": {
    "seo-analytics": {
      "type": "stdio",
      "command": "/absolute/path/to/analytics/run-local.sh",
      "args": []
    }
  }
}

4. Start Claude Desktop again.
5. In a new chat, run tool capabilities to confirm connection.

Main Tools

• capabilities
• gsc_list_sites
• gsc_top_pages
• gsc_top_queries
• ga4_landing_pages
• analytics_merge_page_metrics
• analytics_generate_action_items
• analytics_trend_report
• analytics_data_quality_report

Screenshots

These screenshots are example outputs produced by using Claude Code with this MCP server. The MCP provides the underlying GSC/GA4 data and analytics tools; dashboard rendering is not generated by default by the server itself. For privacy reasons, values shown in the screenshots are randomized; the actual workflow was executed against real data.

Troubleshooting

• service-account.json still contains placeholder values
  • Replace all REPLACE_WITH_... fields in config/service-account.json.
• No such file or directory: .../credentials/service-account.json
  • You have a stale credential env override from an older setup.
  • Re-add the MCP server so it runs the latest run-local.sh and uses config/service-account.json.
• Operation not permitted when Claude Desktop starts MCP
  • macOS is blocking execution from protected folders (commonly ~/Documents).
  • Either grant Claude Desktop access in System Settings -> Privacy & Security (Files and Folders and/or Full Disk Access) or move the repo to a non-protected path like ~/dev/analytics.
  • After changing permissions/path, restart Claude Desktop and re-add the MCP entry if needed.
• Missing property_id and DEFAULT_GA4_PROPERTY_ID is not set
  • Set DEFAULT_GA4_PROPERTY_ID in config/.env.
• Missing site_url...
  • Set DEFAULT_GSC_SITE_URL in config/.env.
• GSC permission error on https://... property
  • This server enforces GSC properties in sc-domain:<domain> format to avoid URL-prefix mismatch issues.
  • Use a Domain property in Search Console and grant your service account access there.

Security

• Never commit config/service-account.json or config/.env.
• Commit only template files:
  • config/service-account.example.json
  • config/.env.example