Google Search Console MCP Server

中文文档

Connect Google Search Console to MCP clients such as Claude Desktop, Cursor, and Codex CLI. This lets your AI assistant read search performance, find SEO opportunities, and diagnose page indexing issues.

You do not need to remember tool parameters. In most cases, you can paste a site or page URL into the chat, and the AI client will match it to the right Search Console property before querying data.

What It Can Do

• Generate SEO weekly reports with clicks, impressions, CTR, average position, and trend changes.
• Find pages with high impressions but low CTR, then suggest title and snippet improvements.
• Show which search queries bring traffic to a specific page.
• Compare performance before and after a redesign, migration, or content update.
• Check whether a page is indexed by Google, including canonical, robots, crawl, and rich results details.

This project only reads and analyzes Search Console data. It does not add or remove sites, and it does not submit or delete Sitemaps.

For AI Coding Agents

Use this flow when you operate the MCP server from an AI agent:

1. Call get_capabilities to confirm that the server is reachable and authenticated.
2. Call list_properties before any site-specific request. Use the exact site_url it returns; do not infer or rewrite Search Console property strings.
3. For traffic and ranking questions, use Search Analytics tools such as get_performance_overview, get_search_analytics, get_search_by_page_query, compare_search_periods, or get_advanced_search_analytics.
4. For indexing, canonical, robots, crawl, or rich results questions, use URL Inspection tools such as inspect_url_enhanced, batch_url_inspection, or check_indexing_issues.
5. Sort or rank returned Search Analytics rows locally in the agent when needed. The Search Console API does not support arbitrary server-side metric sorting.
6. Treat URL Inspection results as Google's indexed-view data, not as a live crawl of the current page.

Requirements

You need:

• Node.js 20 or newer.
• A Google Cloud project with the Search Console API enabled.
• Access to the target site in Google Search Console.
• Either an OAuth Desktop Client JSON file or a Service Account JSON key.

Installation

Using npm:

npm install
npm run build

Or using pnpm:

pnpm install
pnpm build

Run in development mode:

npm run dev

Run the built server:

npm start

The built entry point is dist/index.js. When installed as a package, the binary name is google-search-console-mcp.

Authentication

OAuth

OAuth is the recommended option for local use because it authorizes with your own Google account.

1. In Google Cloud Console, select an existing project or create a new one.
2. Enable the Search Console API for that project.
3. Open Credentials and create an OAuth client ID.
4. Complete the OAuth consent screen setup when prompted, then choose Desktop app as the client type.
5. Download the client secrets JSON and keep it in a stable location, such as ~/Documents/client_secrets.json.
6. Start the server with the client secrets file:

GSC_OAUTH_CLIENT_SECRETS_FILE=/absolute/path/to/client_secrets.json npm run dev

The first tool call starts the browser-based Google sign-in flow. After authorization succeeds, the token is cached under google-search-console-mcp/token.json in your system user config directory, so later runs can reuse it. Set GSC_CONFIG_DIR if you want to use a different cache directory.

Service Account

Service Accounts are a better fit for automation, server deployments, and shared team setups.

1. In Google Cloud Console, select an existing project or create a new one.
2. Enable the Search Console API for that project.
3. Open Credentials and create a Service Account.
4. From the Service Account's Keys tab, create a new JSON key and download it.
5. Store the JSON key somewhere stable, such as ~/Documents/service_account.json.
6. In Search Console, add the Service Account email to the target property with Full access from Settings -> Users and permissions.
7. Start the server with Service Account-only auth:

GSC_CREDENTIALS_PATH=/absolute/path/to/service_account.json GSC_SKIP_OAUTH=true npm run dev

If you use a Domain property, the user or Service Account must be explicitly added to the sc-domain:example.com property.

Authentication Order

By default, the server tries OAuth first. If OAuth fails and GSC_CREDENTIALS_PATH is set, it falls back to the Service Account.

Set GSC_SKIP_OAUTH=true to skip OAuth and use only the Service Account.

MCP Client Setup

First, find your Node.js path:

which node

Replace the example paths below with real absolute paths on your machine:

• /absolute/path/to/node: the output of which node
• /absolute/path/to/google-search-console-mcp/dist/index.js: this project's built entry point
• /absolute/path/to/client_secrets.json: your OAuth Desktop Client JSON file
• /absolute/path/to/service_account.json: your Service Account JSON key

Choose the section for your MCP client below: Claude Desktop, Cursor, or Codex CLI. For macOS GUI apps, use the absolute Node.js path instead of just node. After changing the configuration, fully quit and restart the MCP client.

Claude Desktop

Edit the Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

OAuth configuration:

{
  "mcpServers": {
    "google_search_console": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/google-search-console-mcp/dist/index.js"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/absolute/path/to/client_secrets.json"
      }
    }
  }
}

Service Account configuration:

{
  "mcpServers": {
    "google_search_console": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/google-search-console-mcp/dist/index.js"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/absolute/path/to/service_account.json",
        "GSC_SKIP_OAUTH": "true"
      }
    }
  }
}

Cursor

Cursor can use a global MCP configuration or a project-specific configuration:

• Global: ~/.cursor/mcp.json
• Project: .cursor/mcp.json in your project root

OAuth configuration:

{
  "mcpServers": {
    "google_search_console": {
      "type": "stdio",
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/google-search-console-mcp/dist/index.js"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/absolute/path/to/client_secrets.json"
      }
    }
  }
}

Service Account configuration:

{
  "mcpServers": {
    "google_search_console": {
      "type": "stdio",
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/google-search-console-mcp/dist/index.js"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/absolute/path/to/service_account.json",
        "GSC_SKIP_OAUTH": "true"
      }
    }
  }
}

Codex CLI

Edit the Codex CLI configuration file at ~/.codex/config.toml.

OAuth configuration:

[mcp_servers.google_search_console]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/google-search-console-mcp/dist/index.js"]
enabled = true
env = { GSC_OAUTH_CLIENT_SECRETS_FILE = "/absolute/path/to/client_secrets.json" }

Service Account configuration:

[mcp_servers.google_search_console]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/google-search-console-mcp/dist/index.js"]
enabled = true
env = { GSC_CREDENTIALS_PATH = "/absolute/path/to/service_account.json", GSC_SKIP_OAUTH = "true" }

When using OAuth, the first tool call opens a browser so you can sign in with Google and authorize Search Console access.

Environment Variables

| Variable | Default | Description | | --- | --- | --- | | GSC_OAUTH_CLIENT_SECRETS_FILE | client_secrets.json next to the entry script | Path to the OAuth Desktop Client JSON file | | GSC_CREDENTIALS_PATH | Not set | Path to the Service Account JSON key | | GSC_SKIP_OAUTH | false | Set to true to skip OAuth | | GSC_CONFIG_DIR | System user config directory | OAuth token cache directory | | GSC_DATA_STATE | all | Global Search Analytics data state, either all or final | | MCP_TRANSPORT | stdio | stdio, http, sse, or streamable-http | | MCP_HOST | 127.0.0.1 | HTTP transport bind host | | MCP_PORT | 3001 | HTTP transport bind port | | MCP_MAX_BODY_BYTES | 1048576 | Maximum request body size for HTTP transport |

See .env.example for an example.

HTTP Transport

The default transport is stdio, which is the usual choice for local MCP clients. To use Streamable HTTP:

MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=3001 npm start

Endpoints:

POST /mcp
GET /health

Verify The Setup

In your MCP client, ask the AI assistant to call:

get_capabilities

Then list the Search Console properties your account can access:

list_properties

If you call tools directly, use the exact site_url returned by list_properties.

Try This First

In your MCP client, type:

Show the search performance for this site over the last 28 days: https://example.com/

If everything is configured correctly, the AI client will find the Search Console property your account can access, read the data, and summarize the results.

Example Prompts

Generate an SEO weekly report for https://example.com/ over the last 28 days. Include clicks, impressions, CTR, average position, and trend changes.

Find pages on https://example.com/ from the last 28 days that have high impressions but low CTR, then suggest title and meta description improvements.

Analyze which search queries brought traffic to this page over the last 90 days: https://example.com/blog/example-post

Search traffic for https://example.com/ has dropped recently. Help me find the main declining pages and likely causes.

Check whether these pages have indexing, canonical, robots, or crawl issues:
https://example.com/page-1
https://example.com/page-2
https://example.com/page-3

FAQ

The AI Cannot Find My Site

Make sure the Google account you authorized can see the site in Search Console. Domain properties usually look like sc-domain:example.com, while URL-prefix properties usually look like https://example.com/.

I Changed Google Accounts But It Still Fails

Ask the AI client to call:

reauthenticate

This clears the local OAuth token cache and starts a new browser-based authorization flow.

Is URL Inspection A Live Crawl?

No. URL Inspection returns Google's current indexed-view information. It does not represent a real-time crawl of a page you just changed.

More Documentation

• Tools reference
• Troubleshooting
• Contributing guide
• License

Development

npm install
npm run typecheck
npm run build

When you change a tool's input, output, or behavior, update the tools reference and the relevant tool document.

To check that tool docs still match the registered tools:

npm run docs:check

Security

Do not commit OAuth client secrets, Service Account keys, OAuth tokens, .env files, or Search Console exports that contain sensitive data.

License

MIT License. See LICENSE.