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