{
  "markdown": "<p align=\"center\">\n  <img src=\"logo.svg\" alt=\"mcp-gsc\" width=\"280\" />\n</p>\n\n<h1 align=\"center\">mcp-gsc</h1>\n\n<p align=\"center\">\n  Google Search Console MCP server — query search analytics, inspect URLs, manage sitemaps & more via natural language.\n  <br/>\n  Built with Bun + TypeScript. Works with Claude, Cursor, and any MCP client.\n</p>\n\n---\n\n## Quick Start\n\n### 1. Get Credentials\n\nYou need OAuth client credentials from Google Cloud Console.\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)\n2. Create a project (or select existing)\n3. Enable the **Google Search Console API**:\n   - APIs & Services → Library → search \"Google Search Console API\" → Enable\n4. Configure **OAuth consent screen** (if not done):\n   - APIs & Services → OAuth consent screen → External\n   - Fill in app name + your email, add scope `https://www.googleapis.com/auth/webmasters`\n5. Create credentials:\n   - APIs & Services → Credentials → Create Credentials → **OAuth client ID**\n   - Application type: **Desktop app** (allows localhost redirects automatically)\n   - Download the JSON file\n\n6. Set the credentials path:\n\n```bash\nexport GOOGLE_GSC_CREDENTIALS_PATH=/path/to/credentials.json\n```\n\n7. Run setup to authorize:\n\n```bash\nnpx mcp-gsc setup\n```\n\nThis opens your browser for OAuth consent, saves a refresh token, verifies access to your GSC properties, and prints config snippets for your MCP client.\n\n### 2. Add to Claude Code\n\n```bash\nclaude mcp add gsc --scope user --transport stdio \\\n  -e GOOGLE_GSC_CREDENTIALS_PATH=/path/to/credentials.json \\\n  -- npx -y mcp-gsc@latest\n```\n\nThat's it. Restart Claude Code and the tools are available.\n\n> Also works with `bunx mcp-gsc@latest` if you have [Bun](https://bun.sh/).\n> Requires Node 22+ when running via `npx`.\n\n### Claude Desktop / Cursor\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gsc\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-gsc@latest\"],\n      \"env\": {\n        \"GOOGLE_GSC_CREDENTIALS_PATH\": \"/path/to/credentials.json\"\n      }\n    }\n  }\n}\n```\n\n### Codex CLI\n\nAdd to `~/.codex/config.toml` (TOML, not JSON):\n\n```toml\n[mcp_servers.gsc]\ncommand = \"npx\"\nargs = [\"-y\", \"mcp-gsc@latest\"]\nstartup_timeout_sec = 30\nenv = { GOOGLE_GSC_CREDENTIALS_PATH = \"/path/to/credentials.json\" }\n```\n\n> Codex defaults to a 10s startup timeout, which is often too short for a cold `npx` fetch. Bump `startup_timeout_sec` (30 is safe) or install the package globally (`npm i -g mcp-gsc`) and use `command = \"mcp-gsc\"` instead.\n\n### Service Account (alternative)\n\nFor server-to-server auth without browser-based OAuth:\n\n1. Create a service account in Google Cloud Console\n2. Download the JSON key file\n3. In Google Search Console, add the service account email as a **user** for each property\n4. Point `GOOGLE_GSC_CREDENTIALS_PATH` to the key file — auth type is auto-detected\n\n## Tools (25)\n\n### Core Tools (always available)\n\n#### Sites\n| Tool | Description |\n|------|-------------|\n| `list_properties` | List all GSC properties with permission levels |\n| `get_property_details` | Verification info, ownership, permissions for a property |\n\n#### Search Analytics\n| Tool | Description |\n|------|-------------|\n| `search_analytics` | Query search performance (clicks, impressions, CTR, position) with dimensions, filters, and brand segmentation |\n\nDimensions: `query`, `page`, `country`, `device`, `date`, `searchAppearance`, `hour`\n\nTypes: `web`, `image`, `video`, `news`, `discover`, `googleNews`\n\nNote: `searchAppearance` cannot combine with `query` or `page`. `hour` requires `data_state=\"hourly_all\"` (last 10 days only). Country codes are ISO 3166-1 alpha-3 (`usa`, `gbr`, `deu`).\n\n#### Sitemaps\n| Tool | Description |\n|------|-------------|\n| `list_sitemaps` | List sitemaps with status, type, indexed counts, errors |\n| `get_sitemap` | Detailed sitemap info with content breakdown |\n\n#### URL Inspection\n| Tool | Description |\n|------|-------------|\n| `inspect_url` | URL indexing status, crawl info, rich results, canonicals |\n| `batch_inspect_urls` | Inspect up to 10 URLs at once with categorized results |\n\nRate limits: 600/minute + 2,000/day per site (tracked automatically).\n\n#### Export\n| Tool | Description |\n|------|-------------|\n| `export_csv` | Export full search analytics to CSV file (auto-paginates, up to 25K rows) |\n\n### Extended Tools (disabled by default)\n\nEnable with `GOOGLE_GSC_ENABLE_EXTENDED_TOOLS=true`:\n\n#### Reporting Suite\n| Tool | Description |\n|------|-------------|\n| `performance_overview` | Aggregate metrics + daily trend breakdown |\n| `compare_periods` | Compare two date ranges with delta calculations |\n| `top_movers` | Biggest gains and drops between periods |\n| `device_country_breakdown` | Performance by device and/or country |\n\n#### SEO Suite\n| Tool | Description |\n|------|-------------|\n| `quick_wins` | High-impression, low-CTR queries in striking distance (position 4-20) |\n| `cannibalization` | Multiple pages competing for the same query |\n| `opportunity_finder` | Emerging queries, growing impressions with low CTR, declining performers |\n| `position_tracking` | Position changes over time for specific queries/pages |\n| `ctr_anomalies` | Queries with abnormal CTR relative to position |\n| `content_decay` | Pages/queries with impressions dropping >50% from historical peak |\n| `weekly_seo_report` | All-in-one report: overview + quick wins + top movers |\n\n#### Technical SEO Suite\n| Tool | Description |\n|------|-------------|\n| `indexing_coverage` | Batch URL inspection with categorized indexing status |\n| `sitemap_health` | Sitemap error patterns, freshness, indexed vs submitted ratio |\n\n### Write Tools (disabled by default)\n\nEnable with `GOOGLE_GSC_ENABLE_WRITES=true`:\n\n| Tool | Description |\n|------|-------------|\n| `add_site` | Add a new site to GSC |\n| `delete_site` | Remove a site from GSC |\n| `submit_sitemap` | Submit a new sitemap |\n| `delete_sitemap` | Remove/unsubmit a sitemap |\n| `request_indexing` | Ask Google to crawl a URL via the Indexing API |\n| `get_indexing_status` | When a URL was last submitted for indexing |\n\n> **Indexing API prerequisites.** The last two use a different Google API to the\n> rest of this server, so they need three things the other tools don't:\n>\n> 1. **Re-run `mcp-gsc setup`** — credentials created before this feature lack\n>    the `auth/indexing` scope. The tools say so explicitly if yours do.\n> 2. **Enable the Indexing API** on your Google Cloud project —\n>    [console.cloud.google.com/apis/library/indexing.googleapis.com](https://console.cloud.google.com/apis/library/indexing.googleapis.com)\n> 3. **Be a verified _owner_** of the property in Search Console. Full-user\n>    access is not enough.\n>\n> Google officially supports the Indexing API only for pages carrying\n> `JobPosting` or `BroadcastEvent` structured data, with a default quota of\n> 200 URLs/day. It requests a crawl — it never guarantees indexing.\n\n## Configuration\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `GOOGLE_GSC_CREDENTIALS_PATH` | Yes | — | Path to OAuth client JSON or service account key |\n| `GOOGLE_GSC_TOKEN_PATH` | No | Derived | Path to cached OAuth token (default: `*_token.json` next to credentials) |\n| `GOOGLE_GSC_PROPERTY` | No | — | Default property URL (e.g., `sc-domain:example.com`). Accepts bare domains. |\n| `GOOGLE_GSC_ENABLE_WRITES` | No | `false` | Enable write tools |\n| `GOOGLE_GSC_ENABLE_EXTENDED_TOOLS` | No | `false` | Enable extended analytics tools (13 extra) |\n| `GOOGLE_GSC_ENV_FILE` | No | `.env` | Path to .env file |\n| `DEBUG` | No | — | Enable debug logging |\n\n**Property resolution:** You can pass bare domains like `example.com` — the server auto-resolves to `sc-domain:example.com` or `https://example.com/` by matching against your verified properties.\n\n## Examples\n\nAsk your AI assistant:\n\n- \"Show me my top 10 queries this month\"\n- \"Find quick wins for example.com\"\n- \"Which pages have declining traffic over the last 3 months?\"\n- \"Check if these URLs are indexed: url1, url2, url3\"\n- \"Compare this week's performance to last week\"\n- \"Export all search analytics data to CSV for the last 28 days\"\n- \"Run a weekly SEO report for my site\"\n- \"Find keyword cannibalization issues\"\n\n## Future Tool Ideas\n\n- Content gap analysis (requires competitor data integration)\n- Core Web Vitals integration (via PageSpeed Insights API)\n- Multi-property comparison\n- Search appearance deep analysis\n- Integration with Google Analytics for conversion data\n- Automated reporting schedules\n\n## Updates\n\n**Using `npx @latest`** (recommended): You always get the latest version.\n\n**Using a binary**: The server checks for new releases on startup and logs to stderr if outdated.\n\n```bash\nmcp-gsc --version\n```\n\n## Development\n\nRequires [Bun](https://bun.sh/).\n\n```bash\ngit clone https://github.com/pijusz/mcp-gsc.git\ncd mcp-gsc\nbun install\nbun test           # tests\nbun run build      # standalone binary\nbun run inspect    # MCP Inspector\nbun run check      # biome format + lint\n```\n\n## License\n\nMIT\n",
  "bytes": 9069,
  "sha": "ee4a46ea0c056af3db99e470782a9de80d98bfe87e827f4b3afbab1baf02d094",
  "repo_slug": "pijusz/mcp-gsc",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pijusz_mcp_gsc_615a4354/readme"
}