{"_id":"gsc-magic-mcp","_rev":"2-e67a0a99ef4d70b2d5c9094018831cd2","name":"gsc-magic-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.0-stage":{"name":"gsc-magic-mcp","version":"0.0.0-stage","_id":"gsc-magic-mcp@0.0.0-stage","stub":true,"maintainers":[{"name":"samurai6655","email":"blanialukasz@gmail.com"}],"dist":{"shasum":"6dbf3efed4b3a8b077f5a96b919747515b0147e4","tarball":"https://registry.npmjs.org/gsc-magic-mcp/-/gsc-magic-mcp-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-RlcfZ5JojRp3TOX3GzPc93c8TakeFrnLlvQKFE2J9zzluNaA1QWSXCPWHSDDX9KdPyagpKNAsynTdytwCoTmPg==","signatures":[{"sig":"MEUCIG5JQ6WR0crQpEmo7KLZ345K+q/GXRKcmVHjLhMblbO2AiEAoarDZQCtOCftWGv0T8Clx31KGGl9ckxUEOcLdQdTE/E=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":335},"_npmUser":{"name":"samurai6655","email":"blanialukasz@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"0.1.0":{"_id":"gsc-magic-mcp@0.1.0","bin":{"gsc-magic":"dist/index.js","gsc-magic-mcp":"dist/index.js"},"bugs":{"url":"https://gscmagic.com/integrations","email":"support@gscmagic.com"},"dist":{"shasum":"25b4d4ff4666ca00d72a2f9f13e9f20f8d2e6ade","tarball":"https://registry.npmjs.org/gsc-magic-mcp/-/gsc-magic-mcp-0.1.0.tgz","fileCount":63,"integrity":"sha512-tWrGQ6isoeYHpTvV+xyA97s0S90Z2FCPbPI3FZ1fNyFVvstTl38rrLPV0qGNkN0B5nHfkk83IP1B22gNikg66g==","signatures":[{"sig":"MEYCIQDFTFVSTdNfueflcTpmq2yXd57+OV707zLobk0P/r/XqQIhAIc01EQsCuuvkr/nu58nP3KGMmu2kprYkUI4t/zbxQ8Q","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICXq+zF2Xm1h17C4361U9bVcfUooae4W8R96Wc2C7jY1AiATyoqoTwkenX7JVUwibqVkSLCqOW8ZkdEGt26WX41maA=="}],"unpackedSize":352241},"name":"gsc-magic-mcp","type":"module","author":{"url":"https://gscmagic.com","name":"Lumi Zone","email":"contact@gscmagic.com"},"engines":{"node":">=22"},"gitHead":"77413fdebf9f0a68ed886c8ed09a4c2fc9409e6f","license":"MIT","mcpName":"com.gscmagic/gsc-magic","version":"0.1.0","_npmUser":{"name":"samurai6655","email":"blanialukasz@gmail.com"},"homepage":"https://gscmagic.com","keywords":["mcp","mcp-server","model-context-protocol","google-search-console","search-console","bing-webmaster-tools","indexnow","core-web-vitals","google-analytics","ga4","seo","seo-tools","claude","chatgpt","cursor"],"_npmVersion":"11.19.0","description":"MCP server and CLI for Google Search Console, Bing Webmaster Tools, IndexNow, Core Web Vitals, Google Analytics 4, with ready-made SEO reports. Hosted at gscmagic.com.","directories":{},"maintainers":[{"name":"samurai6655","email":"blanialukasz@gmail.com"}],"_nodeVersion":"26.7.0","dependencies":{"zod":"^4.6.5","fflate":"^0.8.3","fast-xml-parser":"^5.11.2","@resvg/resvg-wasm":"^2.6.2","google-auth-library":"^11.3.2","@modelcontextprotocol/sdk":"^1.32.2"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/gsc-magic-mcp_0.1.0_1794074710718_0.8575410644787336"}}},"time":{"created":"2026-11-07T18:03:54.974Z","modified":"2026-11-07T18:05:10.990Z","0.0.0-stage":"2026-11-07T18:03:54.974Z","0.1.0":"2026-11-07T18:05:10.843Z"},"description":"MCP server and CLI for Google Search Console, Bing Webmaster Tools, IndexNow, Core Web Vitals, Google Analytics 4, with ready-made SEO reports. Hosted at gscmagic.com.","maintainers":[{"name":"samurai6655","email":"blanialukasz@gmail.com"}],"readme":"# gsc-magic-mcp\n\nMCP server (stdio) that gives AI agents access to Google Search Console, Bing Webmaster Tools, IndexNow and Core Web Vitals, plus ready-made SEO reports. Works with Claude Code, Claude Desktop, Cursor and any MCP client.\n\nWhat an agent can do with it:\n\n- **Google Search Console**: list/add/delete properties, query search analytics (all dimensions, filters, auto-pagination, CSV export), manage sitemaps, run URL Inspection (single and batch), optionally call the Indexing API.\n- **Bing Webmaster Tools**: site and sitemap management, query/page/traffic/crawl stats, crawl issues, inbound links, keyword research, URL submission, block/unblock, crawl settings, Fetch as Bingbot.\n- **IndexNow**: generate a key and push URL changes to Bing, Yandex, Seznam, Naver and others.\n- **Core Web Vitals**: real-user data from the Chrome UX Report (origin, URL, history) and PageSpeed Insights audits.\n- **Reports**: quick wins, traffic drops/gainers, keyword cannibalization, CTR outliers, index health from your sitemap, Google vs Bing comparison.\n\n> **Prefer no setup?** A hosted version with one-click Google login (no Google Cloud project, works as a connector in Claude and ChatGPT) is available at https://gscmagic.com. This package is the local, bring-your-own-keys edition.\n\n## Safety\n\nThe server starts in **`readonly` mode**: tools that change anything (marked W below) are not even registered. Set `GSC_MAGIC_MODE=readwrite` to enable them. Write tools are annotated as destructive, so clients that honour tool annotations can ask before running write tools. Sources without credentials are skipped (the server logs what was skipped on stderr and still starts).\n\n## Quick start\n\nRequires **Node 22+**. No install step:\n\n```bash\nnpx -y gsc-magic-mcp setup    # guided: sources, domain, keys + Google sign-in, mode, connect to your AI agents\nnpx -y gsc-magic-mcp doctor   # check everything\n```\n\nOr install it globally (`npm i -g gsc-magic-mcp`) and use the short `gsc-magic` command shown in the examples below. MCP clients start the server with `npx -y gsc-magic-mcp` (see Client configuration).\n\n`setup` ends by registering the server in the AI clients it finds (Claude Code, Claude Desktop, Cursor, Codex, Hermes, OpenClaw). Run `gsc-magic connect` any time to add more, `gsc-magic connect --print` to see the config without changing anything, `gsc-magic disconnect` to remove it. API keys stay in `~/.config/gsc-magic/.env`; client configs never contain secrets.\n\n### On a server (VPS)\n\nEverything works headless. `gsc-magic auth` detects a server/SSH session: open the printed link on any computer, approve, then paste the address from the browser's address bar back into the terminal (or use the printed `ssh -L` tunnel). Already signed in on your laptop? `gsc-magic auth export` there, `gsc-magic auth import` on the server. For always-on servers a service account (`GOOGLE_APPLICATION_CREDENTIALS`) avoids the 7-day token expiry of test-mode consent screens.\n\nAgent on your laptop, data on the VPS: `gsc-magic connect claude-code --remote you@your-vps` registers `ssh -T you@your-vps gsc-magic serve` (needs key-based SSH and gsc-magic installed on the server).\n\n## Google setup (OAuth, recommended for personal use)\n\n1. In [Google Cloud Console](https://console.cloud.google.com/) create or pick a project and enable the **Google Search Console API** and the **Site Verification API** (needed for `gsc-magic domain add/verify`), plus the Indexing API if you want `gsc_request_indexing`.\n2. Configure the **OAuth consent screen**: user type External, add yourself as a test user.\n3. Create an **OAuth client ID** of type *Desktop app* and download the JSON.\n4. Save it as `~/.config/gsc-magic/client_secret.json` (or point `GSC_MAGIC_OAUTH_CLIENT` at it).\n5. Run `npx gsc-magic-mcp auth`  and approve in the browser. The refresh token is stored in `~/.config/gsc-magic/token.json`.\n\nThe Indexing API scope is added at auth time, so after changing `GSC_MAGIC_ENABLE_INDEXING_API` you must re-run `npx gsc-magic-mcp auth`.\n\n**Important:** while the consent screen is in the \"Testing\" publishing status, Google refresh tokens expire after 7 days and you must re-run `auth` weekly. Set the consent screen to **\"In production\"** (unverified is fine for personal use) to avoid that.\n\n## Google setup (service account)\n\nCreate a service account, download its JSON key, add the service account e-mail as a user in each Search Console property (Settings, Users and permissions), and set `GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json`. It takes precedence over OAuth.\n\n**Warning:** `GOOGLE_APPLICATION_CREDENTIALS` is a common global Application Default Credentials variable. If it is set in your shell or MCP client environment for unrelated work, it takes precedence over OAuth here and can cause 403 errors because that service account has no access to your Search Console properties. Unset it (or override it in the MCP server `env`) if you want to use OAuth.\n\n## Bing\n\nBing Webmaster Tools, Settings, API access, generate an API key, then set `BING_API_KEY`.\n\n## IndexNow\n\nCall the `indexnow_generate_key` tool, host the returned file at `https://<your-host>/<key>.txt`, set `INDEXNOW_KEY` and restart the server. Without the key, `indexnow_submit` is not registered.\n\n## Core Web Vitals (CrUX and PageSpeed Insights)\n\nEnable the **Chrome UX Report API** and the **PageSpeed Insights API** in Google Cloud, create an API key and set `GOOGLE_API_KEY`.\n\n## Command line (CLI)\n\nThe same binary is a full CLI. Two names: `gsc-magic-mcp` and the short `gsc-magic`. With no arguments and a terminal it prints the logo and help; with piped stdin (how MCP clients start it) it runs the MCP server, so existing client configs keep working. `gsc-magic serve` forces server mode. An argument the CLI does not recognise — a stray `--stdio` left in an MCP client's configuration, for example — is an error on stderr with exit code 2, so a client cannot mistake the help screen for a started server.\n\n```bash\ngsc-magic setup                      # API keys, default mode, Google login (interactive)\ngsc-magic connect [clients] [--print] [--remote user@host] [--yes]   # register in AI clients\ngsc-magic disconnect [clients]       # remove it again\ngsc-magic auth export | auth import [value]   # move a Google sign-in between machines\ngsc-magic doctor [--live]            # what is configured, what works; --live calls the APIs once (read-only)\ngsc-magic tools [filter]             # all tools: ready or why not (ga_* show as disabled until enabled)\ngsc-magic gsc_list_sites\nGSC_MAGIC_TOOLSETS=gsc,ga gsc-magic ga_run_report --property 123456789 --dimensions date --metrics sessions --start-date 28daysAgo --end-date today\ngsc-magic run gsc_query_analytics --site example.com --range last_28_days --dimensions query,page --limit 20\ngsc-magic report_quick_wins --site example.com --csv quick-wins.csv\ngsc-magic run gsc_inspect_url --help # options of one tool\n```\n\n- Any tool can be run: `gsc-magic <tool> [--option value]` (or `gsc-magic run <tool> …`). Options are generated from the tool schemas; `--start-date`, `--start_date` and `--startDate` are the same option. Lists are comma separated (`--dimensions query,page`); objects and lists of objects take JSON (`--filters '[{\"dimension\":\"country\",\"expression\":\"POL\"}]'`). `--args '<json>'` supplies a base argument object.\n- Output is a table; `--json` prints raw JSON; `--csv file.csv` also writes the rows to a file. An existing file is never truncated: `--csv` refuses to overwrite it and you pass `--force` to write over it (the previous file is kept as `file.csv.bak`).\n- **Write tools** need `--mode readwrite` (or `GSC_MAGIC_MODE=readwrite`) and ask `Run it? [y/N]` first. Pass `--yes` to skip the question in scripts; without a terminal and without `--yes` they refuse to run.\n- `--no-logo` hides the logo; colors are off when `NO_COLOR` is set or output is piped.\n- Flags a command does not accept are an error (exit code 2) rather than silently ignored; `--help`, `--version`, `--no-logo` and `--mode` are the only ones accepted everywhere.\n- Settings come from the environment, then from `~/.config/gsc-magic/.env` (written by `gsc-magic setup`).\n\n### Your domains and settings from the terminal\n\n```bash\ngsc-magic setup                        # guided: domain, keys, mode, Google login, add the domain\ngsc-magic domain add example.com --mode readwrite\ngsc-magic domain add example.com --mode readwrite --use   # and make it the default domain\ngsc-magic domain verify example.com --mode readwrite\ngsc-magic domain list                  # Google + Bing status of every domain, ★ marks the default\ngsc-magic domain use example.com       # default domain: --site is optional from now on\ngsc-magic domain remove example.com --mode readwrite --only bing   # leave Search Console alone\ngsc-magic report_quick_wins            # uses the default domain\ngsc-magic config                       # all settings and where each value comes from (same as: config show)\ngsc-magic config show                  # explicit alias of `config list`\ngsc-magic config get site              # one setting; exit 1 with a message when it is not set\ngsc-magic config set mode readwrite    # also: site, bing-key, google-key, indexnow-key, toolsets, indexing-api, max-output\n```\n\n- `domain add` adds the domain to Search Console (as a domain property, `sc-domain:`) and to Bing, then prints what you have to do to prove ownership: the **DNS TXT record** for Google (token from the Site Verification API) and the **CNAME / meta tag / XML file** for Bing (codes from Bing's own API). Add the record at your DNS provider, wait a few minutes and run `domain verify`.\n- `domain add`, `verify` and `remove` change data, so they follow the usual rule: `--mode readwrite` (or `GSC_MAGIC_MODE=readwrite`) plus a confirmation (`--yes` skips it). Inside `gsc-magic setup` you confirm interactively instead. `domain remove <domain> --only google|bing` limits the removal to one service (without `--only` it is removed from both; a value-less `--only` is an error, never a widening). `domain add --use` sets the new domain as the default right away.\n- Google verification needs the **Site Verification API** enabled in Google Cloud and a token that includes the `siteverification` scope. If you signed in before this feature existed, run `gsc-magic auth` once more.\n- With a default domain set, `--site` (Search Console) and `--site-url` / `--bing-site-url` (Bing) are filled in for you. A bare domain such as `--site-url example.com` is resolved to the exact URL Bing has on file (for example `https://www.example.com/`).\n- `setup` accepts the downloaded OAuth client JSON by drag and drop (the path is cleaned up and the file is stored for you); it prints the exact Google Cloud pages to open.\n\n## Client configuration\n\n`gsc-magic connect` does all of the below for you; the manual steps are here for reference.\n\nClaude Code (read-only, no credentials, 1 tool):\n\n```bash\nclaude mcp add gsc-magic -s user -- npx -y gsc-magic-mcp\n```\n\nClaude Code with Bing and CrUX/PSI keys (after `auth` for Google):\n\n```bash\nclaude mcp add gsc-magic -s user \\\n  -e BING_API_KEY=your-bing-key \\\n  -e GOOGLE_API_KEY=your-google-api-key \\\n  -- npx -y gsc-magic-mcp\n```\n\nAdd `-e GSC_MAGIC_MODE=readwrite` to enable write tools. Verify with `claude mcp list`.\n\nClaude Desktop / Cursor:\n\n```json\n{\n  \"mcpServers\": {\n    \"gsc-magic\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"gsc-magic-mcp\"],\n      \"env\": { \"BING_API_KEY\": \"...\", \"GOOGLE_API_KEY\": \"...\" }\n    }\n  }\n}\n```\n\n### Keys without `env` support (env file)\n\nSome clients cannot pass environment variables to MCP servers, or only pass a filtered set. The server therefore also reads `~/.config/gsc-magic/.env` (override the path with `GSC_MAGIC_ENV_FILE`). Real environment variables win over the file.\n\n```bash\nmkdir -p ~/.config/gsc-magic\nprintf 'BING_API_KEY=your-bing-key\\nGOOGLE_API_KEY=your-google-api-key\\nINDEXNOW_KEY=your-indexnow-key\\n' > ~/.config/gsc-magic/.env\nchmod 600 ~/.config/gsc-magic/.env\n```\n\n### Codex (`~/.codex/config.toml`)\n\nCodex defaults to a 10 s startup timeout and a 60 s tool timeout; `psi_run_audit` can take up to 120 s, so raise both.\n\n```toml\n[mcp_servers.gsc-magic]\ncommand = \"npx\"\nargs = [\"-y\", \"gsc-magic-mcp\"]\nstartup_timeout_sec = 30\ntool_timeout_sec = 180\n\n[mcp_servers.gsc-magic.env]\nBING_API_KEY = \"...\"\nGOOGLE_API_KEY = \"...\"\n```\n\nOr: `codex mcp add gsc-magic --env BING_API_KEY=... -- npx -y gsc-magic-mcp`. Check with `codex mcp list`.\n\n### Hermes Agent (`~/.hermes/config.yaml`)\n\nHermes passes only the variables you list under `env` (plus a safe baseline), not your whole shell environment.\n\n```yaml\nmcp_servers:\n  gsc_magic:\n    command: \"npx\"\n    args: [\"-y\", \"gsc-magic-mcp\"]\n    env:\n      BING_API_KEY: \"...\"\n      GOOGLE_API_KEY: \"...\"\n    timeout: 180\n    connect_timeout: 30\n```\n\nTools show up as `mcp_gsc_magic_<tool>`. Reload with `/reload-mcp`, test with `hermes mcp test gsc_magic`.\n\n### OpenClaw\n\n```bash\nopenclaw mcp add gsc-magic --command npx --arg -y --arg gsc-magic-mcp\nopenclaw mcp doctor gsc-magic --probe\n```\n\nThe OpenClaw docs do not describe an `env` setting for stdio servers, so put the keys in `~/.config/gsc-magic/.env` (see above).\n\n### Other clients (Gemini CLI, etc.)\n\nAny stdio MCP client works: command `npx`, args `[\"-y\", \"gsc-magic-mcp\"]`. Tool schemas are deliberately plain JSON Schema (no `format`, `anyOf`, `$ref` or `additionalProperties`) so strict function-calling validators accept them. Tool output is cut at `GSC_MAGIC_MAX_OUTPUT_CHARS` (default 80000 characters) because clients cap tool output size.\n\n## Environment variables\n\n| Var | Default | Meaning |\n|---|---|---|\n| `GSC_MAGIC_SITE` | none | default domain for CLI commands (set with `gsc-magic domain use`) |\n| `GSC_MAGIC_MODE` | `readonly` | `readonly` or `readwrite` |\n| `GSC_MAGIC_TOOLSETS` | `gsc,bing,indexnow,cwv,reports` | comma list of toolsets; add `ga` to enable Google Analytics 4 (opt-in) |\n| `GOOGLE_APPLICATION_CREDENTIALS` | none | service-account JSON path (takes precedence over OAuth) |\n| `GSC_MAGIC_OAUTH_CLIENT` | `~/.config/gsc-magic/client_secret.json` | OAuth desktop client JSON |\n| `GSC_MAGIC_TOKEN_PATH` | `~/.config/gsc-magic/token.json` | stored OAuth refresh token |\n| `GSC_MAGIC_ENABLE_INDEXING_API` | `false` | registers `gsc_request_indexing` (also requires readwrite) |\n| `GSC_MAGIC_ENV_FILE` | `~/.config/gsc-magic/.env` | env file with keys (real env wins) |\n| `GSC_MAGIC_MAX_OUTPUT_CHARS` | `80000` | tool output is cut after this many characters |\n| `BING_API_KEY` | none | Bing Webmaster API key |\n| `INDEXNOW_KEY` | none | IndexNow key; if unset, `indexnow_submit` is not registered |\n| `GOOGLE_API_KEY` | none | API key for CrUX and PageSpeed Insights |\n| `GSC_MAGIC_OUTPUT_DIR` | `~/.config/gsc-magic/exports` | where CSV exports go |\n\n## Tools\n\nR = read-only, W = write (only registered with `GSC_MAGIC_MODE=readwrite`). 64 tools by default; 70 total when every toolset (including the opt-in `ga`) is enabled.\n\nSix tools accept `chart: true` and then return a PNG chart (1200x630, rendered on the server) as an MCP `image` content block next to the usual JSON, so Claude.ai, ChatGPT or Cursor can show the trend inline: `gsc_query_analytics`, `report_traffic_drops`, `report_quick_wins`, `cwv_history`, `ga_run_report`, `bing_rank_traffic_stats`. A failed render never fails the tool (you just get the JSON). In the CLI the PNG is written to the exports directory.\n\n| Tool | R/W | What it does |\n|---|---|---|\n| `gsc_list_sites` | R | List all Google Search Console properties this account can access, with permission level. |\n| `gsc_get_site` | R | Get one property and the account's permission level on it. |\n| `gsc_add_site` | W | Add a property to Search Console. It still has to be verified in the Search Console UI. |\n| `gsc_delete_site` | W | Remove a property from this account's Search Console. |\n| `gsc_query_analytics` | R | Query Google Search performance data grouped by dimensions (query, page, country, device, searchAppearance, date, hour) with filters. JSON output is capped at 25,000 rows; format=csv paginates up to 100,000 rows, writes them to a file and returns the path. The hour dimension requires data_state=hourly_all (set automatically when unset). Pass `chart: true` for a PNG chart (line over dates, otherwise top rows by clicks). |\n| `gsc_list_sitemaps` | R | List sitemaps submitted for a property, with status, errors, warnings and indexed counts. |\n| `gsc_get_sitemap` | R | Get details of one submitted sitemap. |\n| `gsc_submit_sitemap` | W | Submit (or resubmit) a sitemap to Google Search Console. |\n| `gsc_delete_sitemap` | W | Remove a sitemap from Search Console. |\n| `gsc_inspect_url` | R | URL Inspection API: is the URL indexed, coverage state, canonicals, last crawl, robots, mobile usability and rich results. Quota: 2000/day, 600/min per property. |\n| `gsc_inspect_urls_batch` | R | Inspect up to 500 URLs sequentially (throttled to stay under 600/min). Returns a compact status per URL and stops cleanly when the daily quota is hit. |\n| `gsc_request_indexing` | W | Notify Google that a URL was updated or deleted via the Indexing API. Google officially supports this only for pages with JobPosting or BroadcastEvent structured data; other use is at your own risk. Default quota 200/day. |\n| `bing_list_sites` | R | List all sites in Bing Webmaster Tools for this API key, with verification status. Lists are capped by `limit` (default 100). |\n| `bing_get_site_roles` | R | Users with access to a site. Lists are capped by `limit` (default 100). |\n| `bing_query_stats` | R | Clicks, impressions and avg positions for top search queries (weekly rows, ~6 months). Lists are capped by `limit` (default 100). |\n| `bing_page_stats` | R | Clicks, impressions and avg positions for top pages (weekly rows, ~6 months). The page URL is in the Query field. Lists are capped by `limit` (default 100). |\n| `bing_page_query_stats` | R | Search queries that led to one page. Lists are capped by `limit` (default 100). |\n| `bing_query_page_stats` | R | Pages shown for one search query. Lists are capped by `limit` (default 100). |\n| `bing_query_page_detail_stats` | R | Detailed stats for one query on one page. Lists are capped by `limit` (default 100). |\n| `bing_query_traffic_stats` | R | Traffic history for one query. Lists are capped by `limit` (default 100). |\n| `bing_rank_traffic_stats` | R | Daily clicks and impressions for the whole site. Lists are capped by `limit` (default 100). Pass `chart: true` for a PNG line chart of clicks and impressions by day. |\n| `bing_crawl_stats` | R | Daily crawled pages, crawl errors, in-index counts, blocked by robots.txt, etc. Lists are capped by `limit` (default 100). |\n| `bing_crawl_issues` | R | URLs with crawl issues (4xx/5xx, DNS, timeouts, malware...). Lists are capped by `limit` (default 100). |\n| `bing_url_info` | R | Index details for a single URL: HTTP status, last crawled, discovery date, size, anchors. Lists are capped by `limit` (default 100). |\n| `bing_url_traffic` | R | Clicks and impressions for a single URL. Lists are capped by `limit` (default 100). |\n| `bing_list_sitemaps` | R | Sitemaps/feeds submitted to Bing with status and URL counts. Lists are capped by `limit` (default 100). |\n| `bing_sitemap_details` | R | Child sitemaps of a sitemap index. Lists are capped by `limit` (default 100). |\n| `bing_link_counts` | R | Your pages that have inbound links, with link counts. Paged. Lists are capped by `limit` (default 100). |\n| `bing_url_links` | R | External pages linking to a URL on your site. Paged. Lists are capped by `limit` (default 100). |\n| `bing_keyword` | R | Bing search impressions for a keyword in a period (keyword research; not limited to your site). Lists are capped by `limit` (default 100). |\n| `bing_keyword_stats` | R | Historical weekly impressions for a keyword (keyword research). Lists are capped by `limit` (default 100). |\n| `bing_related_keywords` | R | Related keywords with impressions for a period (keyword research). Lists are capped by `limit` (default 100). |\n| `bing_url_submission_quota` | R | Remaining daily and monthly URL submission quota. Lists are capped by `limit` (default 100). |\n| `bing_list_blocked_urls` | R | URLs/directories blocked from Bing results. Lists are capped by `limit` (default 100). |\n| `bing_crawl_settings` | R | Crawl rate per hour and crawl boost setting. Lists are capped by `limit` (default 100). |\n| `bing_list_query_params` | R | Query parameters Bing ignores for URL normalization. Lists are capped by `limit` (default 100). |\n| `bing_fetched_urls` | R | URLs previously fetched with Fetch as Bingbot. Lists are capped by `limit` (default 100). |\n| `bing_fetched_url_details` | R | Result of a Fetch as Bingbot request (status, headers, content). Lists are capped by `limit` (default 100). |\n| `bing_add_site` | W | Add a site to Bing Webmaster Tools (verify it afterwards). |\n| `bing_verify_site` | W | Attempt verification of a site (meta tag, XML file or DNS must already be in place). |\n| `bing_remove_site` | W | Remove a site from Bing Webmaster Tools. |\n| `bing_submit_urls` | W | Submit up to 500 URLs for crawling/indexing. Checks remaining daily quota first. |\n| `bing_submit_sitemap` | W | Submit a sitemap/feed to Bing. |\n| `bing_remove_sitemap` | W | Remove a submitted sitemap/feed. |\n| `bing_block_url` | W | Block a page or directory from Bing results. |\n| `bing_unblock_url` | W | Remove a page/directory block. |\n| `bing_save_crawl_settings` | W | Set hourly crawl rate (24 values, 1-10, index 0 = midnight UTC) and crawl boost. |\n| `bing_add_query_param` | W | Tell Bing to ignore a query parameter. |\n| `bing_remove_query_param` | W | Stop ignoring a query parameter. |\n| `bing_fetch_url` | W | Ask Bingbot to fetch a URL now; read the result later with bing_fetched_url_details. |\n| `indexnow_generate_key` | R | Generate a new IndexNow key and tell you which file to host on the site. Then set INDEXNOW_KEY and restart the server. |\n| `indexnow_submit` | W | Instantly notify Bing, Yandex, Seznam, Naver and other IndexNow engines about new/changed/deleted URLs (one host per call, up to 10,000 URLs). |\n| `cwv_get_origin` | R | Real-user Core Web Vitals (LCP, INP, CLS, FCP, TTFB) for a whole origin from the Chrome UX Report, last 28 days, p75 + good/NI/poor shares. |\n| `cwv_get_url` | R | Real-user Core Web Vitals for a single URL from the Chrome UX Report (needs enough Chrome traffic). |\n| `cwv_history` | R | Weekly Core Web Vitals history (up to ~6 months) for an origin or URL. Give exactly one of origin or url. Pass `chart: true` for a PNG chart with one panel per metric. |\n| `psi_run_audit` | R | Run Lighthouse via PageSpeed Insights for a URL: category scores, lab metrics, field data and top opportunities. Takes 10-30 s. |\n| `report_quick_wins` | R | Query+page pairs ranking at positions 4-20 with many impressions: the cheapest traffic to gain by improving existing pages. Sorted by potential extra clicks. Pass `chart: true` for a PNG bar chart of potential extra clicks. |\n| `report_traffic_drops` | R | Compare the period with the same-length period right before it. Returns biggest click losers and gainers by page or query. Pass `chart: true` for a PNG bar chart of the biggest losers and gainers. |\n| `report_cannibalization` | R | Queries where 2+ of your pages each get a meaningful share of impressions, splitting ranking signals. |\n| `report_brand_split` | R | Branded vs non-branded queries (clicks, impressions, click share, top queries of each). Pass `brand_terms`. |\n| `report_ctr_outliers` | R | Pages whose CTR is under half of your site's median CTR at the same position: candidates for better titles/meta descriptions. |\n| `report_index_health` | R | Read URLs from a sitemap (or all sitemaps submitted in GSC), inspect up to max_urls with the URL Inspection API, and group by coverage state. Uses inspection quota (2000/day). |\n| `report_google_vs_bing` | R | Clicks and impressions per page from Google and Bing side by side. Bing data is weekly and covers ~6 months, so ranges are approximate at week edges. |\n\n### Google Analytics 4 (opt-in, read-only)\n\nOff by default in local (stdio) mode. Enable with `GSC_MAGIC_TOOLSETS=gsc,bing,indexnow,cwv,reports,ga` (or add just `ga`). The toolset is read-only (it never changes your GA4 setup). In the Google Cloud project, enable the **Google Analytics Admin API** and **Google Analytics Data API**. Locally, after enabling, sign in again (`gsc-magic auth`) to grant the new read-only permission (`analytics.readonly`).\n\nWith a service account (`GOOGLE_APPLICATION_CREDENTIALS`) there is no sign-in step: add the service account's e-mail as a user on the GA4 property instead, otherwise every call returns 403.\n\nThey work from the CLI too: `gsc-magic ga_list_properties`, `gsc-magic ga_run_report ...`. `gsc-magic tools ga` lists them and shows them as disabled until the toolset is enabled.\n\n| Tool | What it does |\n|---|---|\n| `ga_list_properties` | List the GA accounts and GA4 properties you can access (start here for property ids). |\n| `ga_list_data_streams` | Data streams of a property, including the Measurement ID (`G-XXXXXXX`). |\n| `ga_get_metadata` | Dimensions and metrics (api names) available for a property, including custom ones. |\n| `ga_run_report` | Run a GA4 report: dimensions, metrics, date range, structured filters, ordering, paging. |\n| `ga_run_realtime_report` | Realtime report (last ~30 minutes). |\n| `ga_list_key_events` | Key events (formerly conversions) configured on a property. |\n\n## Prompts (ready-made workflows)\n\nThe server also exposes MCP prompts: one-click SEO workflows your client lists in its prompt menu (Claude.ai: the \"+\" menu; Claude Code: `/`). Each one tells the agent which tools to call and what to deliver, and answers in your language. All arguments are optional: without `site` the agent asks which property to use; `period` is one of `last_7_days`, `last_28_days`, `last_3_months`, `last_6_months`, `last_12_months`, `last_16_months`.\n\n| Prompt | Arguments | What you get |\n|---|---|---|\n| `weekly_seo_report` | site, period (default 7 days) | Trend vs previous period with charts, what moved, quick wins; Bing, GA4 and Core Web Vitals when connected. |\n| `find_quick_wins` | site, period | Top 10 opportunities with rewritten titles and meta descriptions. |\n| `diagnose_traffic_drop` | site, period, since (YYYY-MM-DD) | When and where clicks fell, the likely cause with evidence, a recovery plan. |\n| `indexing_audit` | site | Not-indexed sitemap URLs grouped by reason, with a fix per group. |\n| `content_refresh_plan` | site, period | Pages to update, merge or redirect (content decay + cannibalization). |\n| `core_web_vitals_check` | site | Mobile and desktop CWV verdict, trend and top fixes (needs `GOOGLE_API_KEY`). |\n\nA prompt is listed only when every tool it needs is available (toolsets, keys, plan), and it mentions optional tools (Bing, GA4, CWV) only when you have them. Each prompt tells the agent not to call write tools without your explicit confirmation. Prompts use no quota: only the tool calls they lead to count.\n\n## Limitations and caveats\n\n- The Google APIs expose no data for the Page indexing report, the Core Web Vitals report, the Links report or Manual actions. Use `gsc_inspect_url` / `report_index_health` for indexing status and `cwv_*` for CrUX data.\n- The Indexing API is officially supported by Google only for JobPosting and BroadcastEvent pages.\n- URL Inspection quota is 2000 requests per day per property (600 per minute).\n- Bing query/page stats are weekly rows covering roughly six months.\n- `report_*` tools pull up to 25,000 rows from Search Console. Very large sites get truncated results (the zero-click tail is cut first).\n- `bing_block_url` and `bing_unblock_url` send integer enum values (Page=0, Directory=1; CacheOnly=0, FullRemoval=1) because Bing's WCF JSON endpoint reads enums as integers, but they are still **untested against the live Bing API**.\n- Bing read tools return at most `limit` rows when the result is a list (default 100, max 5000); the summary reports the total and whether it was truncated.\n- The tools were developed against mocked HTTP. Run `npm run test:live` with your own credentials (read-only calls) to verify against the real APIs.\n\n## License\n\nMIT. Hosted version and support: https://gscmagic.com\n","readmeFilename":"README.md","homepage":"https://gscmagic.com","keywords":["mcp","mcp-server","model-context-protocol","google-search-console","search-console","bing-webmaster-tools","indexnow","core-web-vitals","google-analytics","ga4","seo","seo-tools","claude","chatgpt","cursor"],"author":{"url":"https://gscmagic.com","name":"Lumi Zone","email":"contact@gscmagic.com"},"bugs":{"url":"https://gscmagic.com/integrations","email":"support@gscmagic.com"},"license":"MIT"}