gsc-mcp-server

gsc-mcp-server


MCP server for Google Search Console. Query search performance, list properties, inspect URLs, and list sitemaps from Cursor, Claude Desktop, or any MCP-compatible client.

npm: @jlnkrth/gsc-mcp-server

Use the scoped package name @jlnkrth/gsc-mcp-server. The unscoped name gsc-mcp-server on npm is a different package.

Quick start

| Situation | Auth | Run MCP server | |-----------|------|----------------| | Cloned this repo (inside project folder) | npm run auth | npm start | | Installed from npm (any other directory) | npx -y -p @jlnkrth/gsc-mcp-server gsc-mcp-auth | npx -y @jlnkrth/gsc-mcp-server |

Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET before auth (see Google Cloud setup).

Using a Google passkey to sign in? That's fine — passkey only applies to signing into Google in the browser during auth. You still need your own GCP OAuth client ID and secret.

Tools

| Tool | Description | |------|-------------| | gsc_list_sites | List Search Console properties accessible to your Google account | | gsc_search_analytics | Query clicks, impressions, CTR, and position with dimensions and filters | | gsc_inspect_url | Inspect a URL's index status, crawl state, and mobile usability | | gsc_list_sitemaps | List submitted sitemaps with status, errors, and indexed counts |

gsc_search_analytics filters

| Parameter | Description | |-----------|-------------| | query_filter | Shorthand: queries containing this string | | page_filter | Shorthand: page URLs containing this string | | dimension_filters | Full GSC filter objects (advanced) |

Prerequisites

• Node.js 18+
• A Google Cloud project with the Search Console API enabled
• An OAuth 2.0 Desktop client (client ID + secret)
• A Google account with access to the Search Console properties you want to query

Google Cloud setup

1. Go to Google Cloud Console.
2. Create or select a project.
3. Open APIs & Services → Library and enable Google Search Console API.
4. Open APIs & Services → OAuth consent screen — configure the consent screen. If the app is in Testing mode, add your Google account under Test users or sign-in will fail.
5. Open APIs & Services → Credentials → Create Credentials → OAuth client ID.
6. Application type: Desktop app.
7. Add http://localhost:3336/callback as an authorized redirect URI (if prompted).
8. Copy the Client ID and Client secret.

Install and authenticate

From npm

export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"

npx -y -p @jlnkrth/gsc-mcp-server gsc-mcp-auth

From source

git clone https://github.com/jlnkrth/gsc-mcp-server.git
cd gsc-mcp-server
npm install

cp .env.example .env
# Edit .env with your credentials, then:
export $(grep -v '^#' .env | xargs)
npm run auth

The auth flow opens a browser on port 3336. Tokens are saved to ~/.config/gsc-mcp/tokens.json by default (override with GSC_TOKEN_PATH).

MCP client configuration

Cursor

Add to ~/.cursor/mcp.json (merge with existing servers):

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "@jlnkrth/gsc-mcp-server"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GSC_TOKEN_PATH": "/Users/you/.config/gsc-mcp/tokens.json"
      }
    }
  }
}

Keep mcp.json private — it contains your OAuth client secret. Do not commit it to git.

For local development, point command at Node directly:

{
  "mcpServers": {
    "google-search-console": {
      "command": "node",
      "args": ["/absolute/path/to/gsc-mcp-server/src/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID",
        "GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

See examples/cursor-mcp.json.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (see examples/claude-desktop.json).

After changing MCP config, fully quit and restart your client so the server reloads tokens.

Example prompts

Once connected, you can ask your AI assistant:

• "List my Search Console properties"
• "What are the top 20 queries by clicks for https://example.com/ in the last 28 days?"
• "Show me blog pages with the most impressions last week" (use page_filter)
• "Is https://example.com/blog/my-post indexed?"
• "List sitemaps for sc-domain:example.com"

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_CLIENT_ID | Yes | OAuth 2.0 Desktop client ID | | GOOGLE_CLIENT_SECRET | Yes | OAuth 2.0 Desktop client secret | | GSC_TOKEN_PATH | No | Token file path (default: ~/.config/gsc-mcp/tokens.json) | | GOOGLE_LOGIN_HINT | No | Pre-fill email in the OAuth browser sign-in |

Troubleshooting

| Symptom | Fix | |---------|-----| | Not authenticated | Run npx -y -p @jlnkrth/gsc-mcp-server gsc-mcp-auth (or npm run auth if inside a clone), then restart your MCP client | | npx fails inside cloned repo | Use npm run auth / npm start locally, or run npx from another directory | | Google sign-in fails / access denied | If OAuth app is in Testing mode, add your Google account as a test user in GCP | | No refresh_token in saved tokens | Revoke the app at Google Account permissions, then re-run auth | | Port 3336 in use | Free the port or stop the conflicting process, then re-run auth | | 403 / permission denied on API calls | Confirm the signed-in Google account has access to the property in Search Console | | MCP client can't find npx | Use the full path to node and src/index.js in your config | | Google OAuth fails after passkey sign-in | GOOGLE_CLIENT_ID / SECRET must be real GCP values — not placeholders. Check redirect URI http://localhost:3336/callback |

Related MCP servers

• Google Analytics MCP — official GA4 server
• DataForSEO MCP — official DataForSEO server

Contributing

See CONTRIBUTING.md for local development, tests, and publishing.

License

MIT