webmaster-mcp

Local-first MCP server for Google Search Console, Bing Webmaster Tools, and Yandex Webmaster. One normalized tool surface, local credential storage, SQLite response cache, and a shared background process through mcponce.

Requirements

• Node.js 20 or newer
• An OS credential store (macOS Keychain, Windows Credential Manager, or Linux Secret Service)
• Provider accounts with access to the sites you want to inspect

Install and run after publication:

npx webmaster-mcp auth google
npx webmaster-mcp auth bing
npx webmaster-mcp auth yandex
npx webmaster-mcp auth status
npx webmaster-mcp sites
npx webmaster-mcp mcp

For a local checkout:

npm install
npm run build
node dist/cli/index.js auth status
node dist/cli/index.js mcp

MCP Client Configuration

Add webmaster-mcp to your preferred AI environment's configuration file:

Google Antigravity

Add to ~/.gemini/config/mcp_config.json (global) or .agents/mcp_config.json (workspace):

{
  "mcpServers": {
    "webmaster": {
      "command": "npx",
      "args": ["-y", "webmaster-mcp", "mcp"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "webmaster": {
      "command": "npx",
      "args": ["-y", "webmaster-mcp", "mcp"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "webmaster": {
      "command": "npx",
      "args": ["-y", "webmaster-mcp", "mcp"]
    }
  }
}

OpenAI Codex CLI

Add via CLI or edit ~/.codex/config.json:

codex mcp add webmaster -- npx -y webmaster-mcp mcp

mcponce automatically starts and reuses one local background instance, so multiple clients safely share the SQLite response cache, rate limits, and authentication state.

Authentication

Google

Setting Up Google Cloud OAuth 2.0 (Step-by-Step)

1. Create a Google Cloud Project:

   • Go to the Google Cloud Console.
   • Click the project dropdown in the top bar and select New Project.
   • Enter a project name (e.g., Webmaster-MCP) and click Create.
   • Select your newly created project from the top dropdown.

2. Enable Google Search Console API:

   • Navigate to APIs & Services > Library in the left navigation menu.
   • Search for Google Search Console API.
   • Click on it and select Enable.

3. Configure OAuth Consent Screen:

   • Go to APIs & Services > OAuth consent screen.
   • User Type Selection:
     • Recommended for Google Workspace / Organization accounts: Choose Internal. This skips app verification, requires no test user management, and grants immediate access to any user in your domain.
     • For personal @gmail.com accounts: Choose External (Google only allows External for standard Gmail).
   • Enter the required application details:
     • App name: Webmaster MCP
     • User support email: Your email address.
     • Developer contact information: Your email address.
   • Click Save and Continue.
   • In the Scopes step, click Add or Remove Scopes, search for webmasters, select .../auth/webmasters.readonly (and optionally .../auth/webmasters if you need write scope), then click Update and Save and Continue.
   • In the Test users step (CRITICAL for External mode):
     • Click + Add Users and add your Google account email address.
     • (Note: If this step is omitted on External/Testing apps, Google blocks login with Error 403: access_denied).
     • Click Save and Continue.

4. Create Desktop OAuth Client Credentials:

   • Go to APIs & Services > Credentials.
   • Click + Create Credentials at the top and select OAuth client ID.
   • For Application type, choose Desktop app (Desktop application types automatically support dynamic loopback redirect URIs like http://127.0.0.1:<port>/callback without static URI registration).
   • Set a name (e.g., Webmaster CLI Client) and click Create.
   • Copy the generated Client ID and Client Secret.

5. Set Environment Variables:

   • On macOS / Linux (zsh / bash):

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

   • On Windows (PowerShell):

     $env:GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
     $env:GOOGLE_CLIENT_SECRET="your-client-secret"

6. Authorize via CLI:

   • Run:

     npx webmaster-mcp auth google
     # or locally:
     node dist/cli/index.js auth google

   • The CLI opens your default browser with a PKCE code challenge and starts a local loopback server.
   • Log in with your authorized Google account. If Google displays "Google hasn't verified this app", click Advanced > Go to Webmaster MCP (unsafe).
   • Once authorized, the refresh token is securely stored in your OS keychain / credential store. The loopback server shuts down immediately. Tokens are refreshed automatically.

The default scope is webmasters.readonly. Run auth google --write only if you explicitly want the broader webmasters scope; this version has no write MCP tools.

Bing

Generating a Bing Webmaster API Key (Step-by-Step)

1. Go to Bing Webmaster Tools and sign in with your Microsoft/Google account.
2. In the top-right corner, click the Settings gear icon (⚙️).
3. In the Settings menu, select API Access > API Key.
4. Click Generate API Key (or copy your existing API key).
5. Run:

   npx webmaster-mcp auth bing
   # or locally:
   node dist/cli/index.js auth bing

6. Paste your API key into the hidden terminal prompt. The key is securely saved to your OS keychain / credential store.

Bing's JSON API transmits the key as an HTTPS query parameter as required by that API; this application does not log request URLs or include them in MCP errors.

Yandex

Setting Up Yandex OAuth (Step-by-Step)

1. Go to the Yandex OAuth App Console.
2. Enter an App name (e.g., Webmaster MCP).
3. Under Platforms, select Web services and set the callback URL or use the default verification code flow (https://oauth.yandex.com/verification_code).
4. Under Data access (Permissions), search and add permissions for Yandex Webmaster (webmaster:hostinfo and webmaster:verify).
5. Save the application and copy your generated Client ID.
6. Set the environment variable:

   export YANDEX_CLIENT_ID="your-yandex-client-id"

7. Run:

   npx webmaster-mcp auth yandex
   # or locally:
   node dist/cli/index.js auth yandex

8. The CLI opens the Yandex authorization page in your browser. Copy the authorization token/code displayed on the page and paste it into the hidden terminal prompt. The token is securely stored in your OS keychain.

Multi-Account & Credential Management

• Named Accounts: Add --name personal or --name work to any auth command to manage multiple accounts:

  npx webmaster-mcp auth google --name agency
  npx webmaster-mcp auth bing --name client1

• Check Status: View all stored accounts and their connection status:

  npx webmaster-mcp auth status

• Disconnect / Logout: Remove a specific account:

  npx webmaster-mcp auth logout google --name agency

• MCP Tool Selection: Tools accept an optional account parameter. If omitted, connected accounts are queried automatically and one account per engine is selected for each property (preferring default).

For development only, environment fallback values can be set as WEBMASTER_GOOGLE_TOKEN, WEBMASTER_BING_TOKEN, or WEBMASTER_YANDEX_TOKEN for the default account, or WEBMASTER_GOOGLE_PERSONAL and analogous names for a named account. Google environment access tokens cannot refresh. No credentials are stored in SQLite.

Tools

sites, performance, queries, pages, sitemaps, inspect_url, compare_engines, opportunities, and indexing_gaps.

For example, call performance with:

{"site":"https://example.com/","from":"2026-08-01","to":"2026-08-28","engines":["google","bing"]}

Tools return results plus sanitized errors for individual providers. Provider requests run concurrently. The analysis tools use deterministic thresholds and return the metrics supporting each finding. indexing_gaps accepts up to 20 urls; it reports verified differences only when both provider results have a known state. It also reports search visibility gaps, which mean only that a provider returned no performance row, not that a page is unindexed.

Metric meaning and limits

• ctr is a fraction (0.02 means 2%). It is computed from clicks and impressions when both exist; missing metrics remain absent.
• Google Search Analytics returns top rows and can omit lower-traffic rows. performance groups by day; queries and pages group by their names. Google API reference
• Bing performance is daily. Its query and page statistics are weekly, and its GetPageStats uses a field named Query to hold the page URL. Bing traffic can include more than web search verticals, so cross-engine totals are directional comparisons. Bing traffic reference, page reference
• Yandex all-query history supports dated site totals. Popular queries support date ranges but return a bounded top set. URL-level query monitoring covers only the last two weeks, so longer pages requests return an UNSUPPORTED error for Yandex. Yandex history, URL monitoring
• Google URL inspection checks the version in Google's index. Yandex inspection can verify only URLs already present in Important Page Monitoring; other URLs return unknown. Bing URL information does not establish an indexing verdict, so the Bing adapter does not claim URL inspection support. Google inspection, Yandex important pages

No cross-engine position equivalence is assumed. Missing rows and unknown inspection states are never interpreted as proof of non-indexing.

Development

npm run build
npm test

src/core contains the provider-independent model, credential interface, cache, service, scheduler, and pure analysis functions. Each adapter lives under src/providers. The src/mcp layer contains only tool definitions and mcponce integration. Provider HTTP calls accept an injected fetch for offline tests.

Set MCP_BACKGROUND=0 to run one foreground MCP process for local debugging. Normal runs use mcponce's shared background mode.

SQLite defaults to the OS user cache/application-data directory. Override it with WEBMASTER_MCP_DATA_DIR for tests or isolated local use. History responses are cached for six hours, site lists for one hour, sitemaps for 30 minutes, and URL inspection for five minutes. Authentication failures are never cached.