Skip to content
Back to search

seo-monster

SEOMonster: a local, user-credential-driven MCP server for SEO workflows over Google Search Console, GA4, PageSpeed Insights, and Cloudflare. Read-first, open source.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/avansaber/seo-monster with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/avansaber/seo-monster'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/avansaber--seo-monster/badge.svg)](/listings/avansaber--seo-monster)

HTML

<a href="/listings/avansaber--seo-monster"><img src="/api/listings/avansaber--seo-monster/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> [!TIP] > Fastest path: the **one-click install** buttons above. Or add it to any MCP client by hand:

{
  "mcpServers": {
    "seomonster": { "command": "uvx", "args": ["seo-monster"] }
  }
}

Run the one-time Google sign-in once — `uvx --from seo-monster seo-monster auth` — then ask your assistant to call **`system_status`** to confirm what's connected. Full per-client setup and credentials are in [Install](#install) and [Auth](#auth).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 987 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/avansaber/seo-monster/v0.11.2/assets/wordmark-dark.svg">
  4. <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/avansaber/seo-monster/v0.11.2/assets/wordmark-light.svg">
  5. <img alt="SEOMonster" src="https://raw.githubusercontent.com/avansaber/seo-monster/v0.11.2/assets/wordmark-light.svg" width="440">
  6. </picture>
  7. <h3>Don't learn another SEO dashboard. Just ask.</h3>
  8. <p>The open-source SEO analyst that lives inside the AI assistant you already use —<br>working from <b>your own</b> Search Console, Analytics, and PageSpeed data, on your machine.</p>
  9. <p>
  10. <a href="https://pypi.org/project/seo-monster/"><img src="https://img.shields.io/pypi/v/seo-monster?color=2BD9A8&label=pypi" alt="PyPI version"></a>
  11. <a href="https://pypi.org/project/seo-monster/"><img src="https://img.shields.io/pypi/pyversions/seo-monster" alt="Python versions"></a>
  12. <a href="https://pypi.org/project/seo-monster/"><img src="https://img.shields.io/pypi/dm/seo-monster?color=2BD9A8" alt="Downloads"></a>
  13. <a href="https://github.com/avansaber/seo-monster/actions/workflows/ci.yml"><img src="https://github.com/avansaber/seo-monster/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
  14. <img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT">
  15. <a href="https://github.com/avansaber/seo-monster/stargazers"><img src="https://img.shields.io/github/stars/avansaber/seo-monster?style=flat&color=2BD9A8" alt="GitHub stars"></a>
  16. </p>
  17. <p>
  18. <a href="https://cursor.com/en/install-mcp?name=seomonster&amp;config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJzZW8tbW9uc3RlciJdfQ=="><img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add to Cursor" height="32"></a>
  19. &nbsp;
  20. <a href="https://insiders.vscode.dev/redirect/mcp/install?name=seomonster&amp;config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22seo-monster%22%5D%7D"><img src="https://img.shields.io/badge/VS_Code-Install_server-0098FF?style=flat&logo=visualstudiocode&logoColor=white" alt="Install in VS Code" height="32"></a>
  21. &nbsp;
  22. <a href="https://www.avansaber.com/seomonster/"><img src="https://img.shields.io/badge/Website-avansaber.com%2Fseomonster-555" alt="Website" height="32"></a>
  23. </p>
  24. </div>
  25. ---
  26. You don't open a new tool — you just ask, in plain English, inside **Claude** (or Cursor / Cline / Codex):
  27. > **You** &nbsp; *"What should I write about next?"*
  28. >
  29. > **🦖 SEOMonster** &nbsp; Pulls your Search Console and surfaces three topics you're *almost* ranking for — positions 8–20 with real demand — ranked by opportunity. Say the word and it drafts the brief.
  30. | You ask … | … SEOMonster does |
  31. | :-- | :-- |
  32. | *"What should I write about next?"* | Surfaces near-ranking topics from **your own** Search Console demand |
  33. | *"Is this page ready to publish?"* | Runs the technical-SEO + structured-data checks before you ship |
  34. | *"Get this indexed."* | Nudges Google (Indexing API) and Bing / Yandex (IndexNow) |
  35. | *"Did my change actually move rankings?"* | Before/after attribution vs a matched control group — with a confidence interval, not a guess |
  36. | *"Is ChatGPT recommending us, or our competitors?"* | Tracks your brand's **share of voice** across the AI answer engines |
  37. **70 tools** across Search Console, GA4, PageSpeed, Cloudflare, AI-citation tracking, keyword discovery, and technical SEO — every one returning the same JSON result envelope, every one driven by your own credentials. No new dashboard to learn; you chat with the assistant you already use.
  38. > [!NOTE]
  39. > Published on PyPI as **`seo-monster`** (so the command is `uvx seo-monster`). The import package is `seo_mcp`; `seo-mcp` is a dev/local alias. The package ships **zero secrets** — every credential is resolved at runtime from your own environment or config file.
  40. - **Your data, your machine.** User-credential-driven; nothing is sent to any third party.
  41. - **Read-first, safe by default.** Reads always work; the two routine writes (sitemap submit, indexing request) are on by default; the Cloudflare write tools (cache purge, redirects, settings, managed robots.txt) are gated behind `SEO_MCP_ALLOW_DESTRUCTIVE`, and the riskier ones also need a per-call `confirm` token.
  42. - **Lean.** Standard library + the `mcp` SDK + the Google client libraries; PageSpeed and Cloudflare ride on `urllib`, no extra HTTP dependency.
  43. ## Local evidence workbench
  44. [SEOmonster Workbench](https://github.com/avansaber/seo-monster/blob/v0.11.2/companion/README.md) is a separately installed local companion for preserving source evidence, inspecting recommendation calculations, drafting action plans and comparing later observations. Its CLI stores project records in SQLite and supports portable exports, backup/restore and deterministic replay. The optional MCP interface exposes 17 tools for one configured project. Plans and recorded approvals remain separate from execution; the workbench has no external executor.
  45. Start with the [offline fixture workflow](https://github.com/avansaber/seo-monster/blob/v0.11.2/companion/README.md#install-and-run-locally). The CLI needs no provider credentials or paid data. SDK 2 capture requires SEOmonster 0.10.0 or later, the first engine release on MCP SDK 2. The Workbench itself installs from source; it is not published on PyPI.
  46. ## Quickstart
  47. > [!TIP]
  48. > Fastest path: the **one-click install** buttons above. Or add it to any MCP client by hand:
  49. ```json
  50. {
  51. "mcpServers": {
  52. "seomonster": { "command": "uvx", "args": ["seo-monster"] }
  53. }
  54. }
  55. ```
  56. Run the one-time Google sign-in once — `uvx --from seo-monster seo-monster auth` — then ask your assistant to call **`system_status`** to confirm what's connected. Full per-client setup and credentials are in [Install](#install) and [Auth](#auth).
  57. ## How it works
  58. ### Provider requests and local records
  59. Selected tools contact Google Search Console, Indexing, GA4 Data/Admin, Google
  60. Ads, PageSpeed Insights, CrUX, Cloudflare or IndexNow. Optional research uses
  61. DataForSEO, Open PageRank, Perplexity, OpenAI, Anthropic or Gemini. Technical
  62. checks fetch the requested websites and related robots, sitemap, redirect or
  63. verification URLs. Providers receive the arguments and credentials needed for
  64. the selected request; optional paid calls can incur provider charges. These
  65. calls do not add maintainer telemetry.
  66. SerpBase is an optional paid SERP source. Set `SEO_MCP_SERP_PROVIDER=serpbase`
  67. and `SERPBASE_API_KEY`, or use `[serp] provider` and `[serpbase] api_key` in
  68. the config file. A key alone does not select it. Set
  69. `SEO_MCP_SERP_PROVIDER=dataforseo` to select DataForSEO explicitly; it is also
  70. the default when no provider is selected. Each process allows one SerpBase
  71. request before restart; this is not a shared or durable budget. The
  72. provider receives the query, language, country and device and may retain query
  73. logs. Its [privacy policy](https://serpbase.dev/privacy) does not offer customer-configurable
  74. zero retention, a per-request logging opt-out or self-service query-log deletion.
  75. Review its current terms, privacy policy and credit pricing before use.
  76. SerpBase supports desktop and other locales; this integration currently requests
  77. US English and the mobile layout. The provider client
  78. connects directly and does not use environment proxies. Check provider terms
  79. before storing or exporting its results as Workbench evidence.
  80. The Google AI Overview leg requires one prompt and one sample; SERP adjacency
  81. requires one seed. The default AI sample count exceeds this limit, so specify
  82. one sample for the SerpBase leg. Missing provider modules are unavailable.
  83. Responses without the documented query and page metadata, or with a mismatched
  84. query, are rejected even if the provider reports a charge.
  85. Website checks accept publicly routable targets only. Private, loopback and
  86. local staging targets are refused, including redirects and linked pages. Networks
  87. that require the well-known NAT64 prefix `64:ff9b::/96` are not supported by
  88. these checks. Website fetches use direct connections and refuse HTTP, HTTPS,
  89. all-protocol or SOCKS proxies reported by Python's standard proxy discovery.
  90. Proxy auto-configuration and other system policies may not be detected. A
  91. configured proxy is refused even when a bypass list includes the target.
  92. SEO analysis results can include complete supplied or discovered page URLs,
  93. including paths and query strings. Avoid secrets in URLs shared with these tools.
  94. The engine does not keep a query/result history. The separately installed local
  95. Workbench stores user-owned evidence and decision records in SQLite and creates
  96. exports only when requested. Your MCP host controls its own transcripts and
  97. logs. See [Privacy](https://github.com/avansaber/seo-monster/blob/v0.11.2/PRIVACY.md) for destinations and persistence scopes.
  98. ```mermaid
  99. flowchart LR
  100. U["You — plain English"] --> H["Claude · Cursor · Cline · Codex"]
  101. H -- "MCP · stdio" --> S["SEOMonster<br/>70 tools"]
  102. S --> GSC["Search Console · GA4"]
  103. S --> PSI["PageSpeed · CrUX"]
  104. S --> CF["Cloudflare · IndexNow"]
  105. S --> AI["AI engines · SERP<br/>(optional)"]
  106. S -. "your creds · your machine" .-> U
  107. ```
  108. SEOMonster is a stdio **MCP server**: your AI host launches it, it calls Google / Cloudflare / the AI engines with *your* credentials, and returns a consistent JSON envelope the assistant reads back to you in plain language.
  109. ## Requirements
  110. For the **`.mcpb` bundle path** (Claude Desktop): just Claude Desktop on macOS
  111. or Windows. The bundle declares Python 3.11+ as a runtime; Claude Desktop
  112. materializes the environment for you. No prior `uv` install needed.
  113. For the **`uvx` path** (Cursor, Cline, Codex, advanced Claude Desktop): Python
  114. 3.11 or newer plus [`uv`](https://docs.astral.sh/uv/) (which provides `uvx`).
  115. Find the absolute path to `uvx` with `which uvx`; GUI hosts do not read your
  116. shell profile, so MCP configs need the full path.
  117. ## Tools
  118. 70 tools, grouped by service. All return the same result envelope (see
  119. [Result envelope](#result-envelope)). Call `system_status` first if unsure what
  120. is configured. The server also publishes thirteen named [workflow prompts](#workflow-prompts).
  121. **Cross-service**
  122. - `system_status` - which services are configured/reachable, the Google auth
  123. method and scopes, whether destructive mode is on, the full tool catalog,
  124. and the list of registered prompts.
  125. <details>
  126. <summary><b>📂 Browse all 70 tools</b> — grouped by service (GSC · GA4 · AI/GEO · keyword discovery · content · PageSpeed/CrUX · Cloudflare · IndexNow · technical · schema). Click to expand.</summary>
  127. <br>
  128. <a name="gsc"></a>
  129. **Google Search Console (18)**
  130. *Workhorses*
  131. - `gsc_list_properties` - properties the credentials can see, with permission
  132. level and a derived `writable` flag (true for `siteOwner` / `siteFullUser`).
  133. - `gsc_search_analytics` - the workhorse: clicks/impressions/CTR/position by
  134. dimensions, date range, filters, and `data_state`.
  135. - `gsc_top_queries` / `gsc_top_pages` - convenience top-N wrappers.
  136. - `gsc_compare_periods` - current vs prior window with per-key deltas.
  137. v0.2.0 added `sort_by`, `sort_dir`, `min_delta_clicks` / `_impressions` /
  138. `_position`, `anomalies_only` + `sigma_threshold`, and `top` for one-call
  139. movers / losers / outliers reporting.
  140. - `gsc_inspect_url` - URL Inspection (index verdict, coverage, canonicals).
  141. - `gsc_batch_inspect_urls` - inspect up to 25 URLs, per-URL failures collected.
  142. - `gsc_list_sitemaps` - registered sitemaps and their status.
  143. - `gsc_submit_sitemap` - submit a sitemap (write, un-gated; needs the writable
  144. scope). Accepts either `sitemap_url` (friendly) or `feedpath` (raw API field).
  145. - `gsc_request_indexing` - request (re)crawl via the Indexing API (write,
  146. un-gated). Accepts singular `url` or `urls`.
  147. *Query intelligence (v0.2.0)*
  148. - `gsc_query_opportunities` - queries already ranking top N with below-target
  149. CTR. Title and meta optimization candidates.
  150. - `gsc_query_gaps` - queries that draw impressions but barely any clicks.
  151. Content opportunity signal.
  152. - `gsc_new_queries` - queries appearing in the current window with no prior
  153. impressions. Emerging topics.
  154. - `gsc_top_pages_by_query` - which pages rank for a specific query. The
  155. cannibalization audit input.
  156. *Multi-property + lifecycle (v0.5.0)*
  157. - `gsc_portfolio_summary(days, include?, exclude?)` - multi-property fleet
  158. view. Per-property one-row summary (clicks, impressions, CTR, position)
  159. for the last N days, plus a portfolio-level rollup. Honors optional
  160. `include` / `exclude` filters. The single fastest answer to "how is the
  161. whole portfolio doing?" across agency or multi-brand setups.
  162. - `gsc_trending_pages(days, limit)` - pages whose impressions grew most over
  163. the last N days vs the prior N days. Wrapper on `gsc_compare_periods` with
  164. `dimensions=["page"], sort_by="delta_impressions", sort_dir="desc"`.
  165. - `gsc_decaying_pages(days, limit)` - same wrapper, ascending sort. Pages
  166. to rescue.
  167. - `gsc_coverage_audit(urls, site_url?)` - heuristic coverage audit. The GSC
  168. Index Coverage report is not exposed in the API; this tool takes a user-
  169. supplied URL list (typically pulled from a sitemap) and bulk-inspects
  170. each, then rolls up verdicts (PASS / PARTIAL / FAIL) and coverage_state
  171. frequencies.
  172. <a name="content"></a>
  173. **Content intelligence (4)**
  174. - `content_opportunities(site_url?, days?, count?, impressions_min?)` - ranks
  175. data-grounded content topics from your own Search Console data: fuses
  176. CTR-vs-expected gap (curve self-calibrated from your own per-position CTR),
  177. striking-distance position, demand, and momentum into a transparent
  178. opportunity score; flags cannibalization. If a GA4 property is configured, it
  179. also weights each topic by the organic conversions its top page already drives
  180. (up to +50%), so topics that convert rank higher; `filters_applied.ga4_value_status`
  181. reports whether that ran and why (`applied` / `no_ga4_property` /
  182. `ga4_unreachable` / `no_conversions`). Prioritizes demand you already have;
  183. does not do cold-start keyword research or write the content. Pairs with the
  184. content workflow prompts below. (GA4 weighting v0.7.3) v0.9.0 adds an additive
  185. per-candidate `winnability` block (banded: striking-distance + topical-
  186. proximity, GSC-personalization tier; existing fields unchanged).
  187. - `content_brief_data(target_query, competitor_urls?, topic?, site_url?, days?)` -
  188. data-wired backing for a content brief: fetches the competitor pages (or your
  189. own GSC-ranking pages as a fallback) and returns the heading union, median
  190. word-count floor, schema types, and entity coverage, plus the 2026 GEO writing
  191. directives and validation rules. The host writes the prose; SEOMonster brings
  192. rules + evidence. Backs the `content_brief` prompt. (v0.9.0)
  193. - `topic_cluster_map(cluster_path | pillar_url, site_url?, days?, impressions_min?)`
  194. - maps a content cluster from your own GSC data and surfaces missing subtopics.
  195. Classifies each cluster query into defend / optimize / create / monitor by
  196. demand and best position; the create quadrant is your missing-subtopic list.
  197. Flags cannibalization. GSC-only; honest about the ~47% query anonymization. (v0.9.0)
  198. - `rank_change_attribution(url | urls, change_date, query?, site_url?, pre_days?, post_days?, gap_days?, control_scope?)`
  199. - estimates whether an on-site change moved a page's clicks via
  200. difference-in-differences against a matched control group (never a naked
  201. before/after). Returns an estimated lift with a 95% CI, a three-state verdict
  202. (likely_positive / likely_negative / inconclusive), and a confounders block
  203. that auto-detects the 2025 GSC data-regime breaks (impression bug, num=100) and
  204. downgrades position reliability. Observational, not causal -- a server-side
  205. split test is the only true causal test. GSC-only. (v0.9.0)
  206. <a name="ai"></a>
  207. **AI / GEO citation (3, v0.9.0)** - whether the AI answer surfaces reach and cite you.
  208. - `ai_citation_readiness(url)` - is a page structured to be extracted/cited by
  209. LLM answer engines? Leads with a render-blindness check (GPTBot / ClaudeBot /
  210. PerplexityBot fetch but do not run JS, so a client-rendered SPA is invisible to
  211. them), then scores evidence-backed signals (statistics, quotations, cited
  212. sources, no keyword-stuffing). schema.org / FAQ / llms.txt are reported as
  213. informational only -- the 2026 evidence does not support them as AI-citation
  214. drivers, so they are not scored. Free, HTTP-only.
  215. - `ai_referral_overview(property_id?, site_url?, days?)` - first-party AI traffic:
  216. GA4 referral sessions from AI apps (the native `ai-assistant` channel plus a
  217. configurable source-host regex) and AI-crawler robots coverage (GPTBot,
  218. ClaudeBot, PerplexityBot, ...). Surfaces the ~70% dark-traffic undercount and
  219. keeps AI-Overview clicks (counted as Organic) separate. Free.
  220. - `ai_citation_track(prompts, brand, brand_domains?, competitors?, engines?, samples?)`
  221. - sampled brand mention + citation share-of-voice across AI engines
  222. (Perplexity / OpenAI / Anthropic / Gemini APIs + Google AI Overviews via
  223. DataForSEO) for a managed prompt set, vs competitors. N samples/prompt (default
  224. 7) with a 95% CI, share-of-voice, and run-to-run volatility -- NOT an "AI rank"
  225. (single runs are statistically meaningless). Discloses that developer-API output
  226. differs from the logged-in consumer UI and that AIO has no API. Paid +
  227. non-deterministic. Needs at least one engine key and/or DataForSEO.
  228. <a name="discovery"></a>
  229. **Keyword discovery (3, v0.9.0)** - find terms you don't already rank for.
  230. - `gsc_keyword_expand(candidates, site_url?, days?, impressions_min?)` - you
  231. (the host) brainstorm candidate terms from your winning queries; this grounds
  232. each against your own Search Console data (footprint covered / thin / none) with
  233. a sibling-strength confidence band. "none" = no VISIBLE footprint (GSC hides
  234. ~75% of impressions), so net-new terms are scored hypotheses. Free.
  235. - `serp_adjacency_expand(seeds, include_paa?)` - expand seed terms into adjacent
  236. terms. FREE core: Google Autocomplete (no key). Optional People-Also-Ask +
  237. related searches via DataForSEO. Returns per-seed suggestions plus the
  238. aggregated net-new terms; degrades gracefully without a key.
  239. - `keyword_universe(target_domain?, competitors?, keywords?, limit?)` - optional,
  240. paid. Core value: the competitor keyword GAP (DataForSEO Domain Intersection;
  241. no Google equivalent). Optional search volume / difficulty / intent via a
  242. provider chain (DataForSEO, else Google Ads volume-only). External volume is a
  243. degraded directional signal -- a tiebreaker, never a gate.
  244. <a name="ga4"></a>
  245. **Google Analytics 4 (7)**
  246. - `ga4_run_report` - the workhorse: arbitrary dimensions/metrics/date range,
  247. optional dimension filter and ordering.
  248. - `ga4_top_landing_pages` - top landing pages, organic-only by default.
  249. - `ga4_traffic_by_channel` - sessions/engagement/conversions by channel group.
  250. - `ga4_organic_search_overview` - organic totals plus a day-by-day trend.
  251. - `ga4_setup_audit(property_id?)` - read-only SEO-measurement-readiness audit:
  252. web data stream, key events, data retention, content-group dimensions, and
  253. (v0.7.4) enhanced measurement, internal site search, and Google Signals.
  254. Severity-graded with a benign exception per finding. Uses the GA4 Admin API
  255. over REST (analytics.readonly; no extra dependency). (v0.7.0)
  256. - `ga4_site_search(days?, limit?)` - internal site-search query report (a
  257. direct content-gap signal); honest envelope when no real search terms. (v0.7.1)
  258. - `ga4_landing_page_conversions(days?, organic_only?, limit?)` - organic
  259. landing pages ranked by conversions. (v0.7.1)
  260. <a name="psi"></a>
  261. **PageSpeed Insights (2)**
  262. - `psi_analyze` - Lighthouse scores, lab Core Web Vitals, and field (CrUX) Core
  263. Web Vitals for a URL. Defaults to the mobile strategy. Field data carries a
  264. `field_data_note`: Google is deprecating PSI field data, so use `crux_snapshot`
  265. / `crux_history` for durable field metrics.
  266. - `psi_opportunities(url, strategy?)` - the actionable Lighthouse "opportunity"
  267. audits (with estimated savings) plus the SEO-category audits, severity-graded.
  268. Lab data only. An on-page-basics checklist, not a ranking predictor. (v0.7.1)
  269. <a name="cf"></a>
  270. **Cloudflare (13)**
  271. - `cf_list_zones` - zones the token can see.
  272. - `cf_zone_info` - status, plan, name servers for a zone.
  273. - `cf_list_dns` - DNS records (read-only); useful for verifying canonical host
  274. and TXT verification records during migrations.
  275. - `cf_web_analytics` - read-only edge Web Analytics (RUM), to compare against
  276. GA4. Cloudflare returns `host: null` for some sites; pass the `site_tag` to
  277. look those up explicitly.
  278. - `cf_purge_cache` - purge specific URLs (gated).
  279. - `cf_purge_cache_all` - purge an entire zone (gated + confirm token).
  280. - `cf_settings_audit(zone?)` - read-only audit of SEO-relevant Cloudflare zone
  281. settings (SSL mode, Always-Use-HTTPS, HSTS, Automatic HTTPS Rewrites, Brotli,
  282. cache TTL). Severity-graded with a "verify, not fail" discipline because CF
  283. cannot see the origin; HSTS is never a hard failure. Needs Zone Settings Read
  284. on the token. Each finding carries a machine-readable `fix` hint (the exact
  285. `cf_settings_update` setting + recommended value) to chain audit -> fix. (v0.7.1)
  286. - `cf_settings_update(settings, zone?, confirm?, acknowledge_hsts_risk?, dry_run?)`
  287. - write the SEO/crawl/security settings the audit grades (SSL mode, Always-Use-
  288. HTTPS, Automatic HTTPS Rewrites, Brotli, browser cache TTL, HSTS), closing the
  289. audit -> remediate loop. Gated. ssl_mode or any HSTS-raise needs `confirm=<zone>`
  290. (HSTS-raise also needs `acknowledge_hsts_risk=true`); validates locally, supports
  291. `dry_run`, and re-runs the audit so you see the finding clear. Needs Zone
  292. Settings:Edit (vs the audit's Read). (v0.7.10)
  293. - `cf_list_redirects(zone?)` - list a zone's single (dynamic) redirect rules
  294. plus the account's Bulk Redirect lists (read-only). Call before any redirect
  295. write so nothing is clobbered. (v0.7.8; bulk lists added v0.7.9)
  296. - `cf_create_redirect(source, target, status_code?, ...)` - create one edge
  297. redirect (e.g. a 301 for a renamed URL). Gated. Pre-flights the target (no
  298. redirecting to a dead URL), refuses loops/duplicates, supports `dry_run`. (v0.7.8)
  299. - `cf_delete_redirect(rule_id, zone?)` - remove a single-redirect rule by id
  300. (rollback for cf_create_redirect). Gated. (v0.7.8)
  301. - `cf_bulk_redirect_upsert(items, list_name, confirm, ...)` - create/append many
  302. redirects at once via an account-level Bulk Redirect List (for migrations).
  303. Gated + a confirm token equal to `list_name`. Validates every item locally
  304. first and rejects the whole batch on any bad item (never half-applies);
  305. supports `dry_run`. (v0.7.9)
  306. - `cf_managed_robots(action, zone?, ...)` - get / configure / disable
  307. Cloudflare's managed robots.txt and Content-Signals policy (these ride on the
  308. zone's Bot Management config). `action="get"` reads the current state
  309. (read-only, un-gated). `action="configure"` sets the managed robots.txt
  310. (`managed_robots`), the Content-Signals variant (`cf_robots_variant`:
  311. off / policy_only), and the AI-bot blocking levers (`ai_bots_protection`,
  312. `content_bots_protection`, `crawler_protection`). `action="disable"` turns the
  313. managed robots.txt and the policy back off. **Managed robots.txt and the
  314. Content-Signals policy are mutually exclusive in Cloudflare**, so the valid
  315. combinations are `managed_robots=true` + `cf_robots_variant="off"` (managed
  316. robots.txt) OR `managed_robots=false` + `cf_robots_variant="policy_only"` (the
  317. policy); the tool rejects the invalid combo locally with `INVALID_INPUT`. A
  318. custom Content-Signal line (e.g. from `robots_ai_posture`) is not a managed
  319. option - put that in your origin robots.txt. Writes are gated, need
  320. `confirm=<zone>`, and support `dry_run`; reads are safe (GET -> overlay -> PUT,
  321. so nothing else in the config is clobbered). Every response carries a caveat
  322. separating the stated-preference signals (Content-Signals, honored only by
  323. adopting crawlers and ignored by Googlebot) from the levers that actually
  324. enforce at the edge. Needs Bot Management:Edit for writes (Read for get).
  325. (v0.8.2)
  326. <a name="indexnow"></a>
  327. **IndexNow (2, v0.2.0)**
  328. - `indexnow_submit(url)` - submit a single URL to Bing, Yandex, Naver, Seznam,
  329. Yep. Complements (does not replace) `gsc_request_indexing`, which only talks
  330. to Google. Requires `SEO_MCP_INDEXNOW_KEY` plus a verification file at
  331. `https://<your-host>/<key>.txt` (see [IndexNow setup](#indexnow) for the full
  332. key + file format + same-host rules).
  333. - `indexnow_bulk_submit(urls)` - up to 10,000 URLs sharing one host in a
  334. single POST. Mixed-host batches are rejected client-side with
  335. `INVALID_INPUT` before any network call. The `SEO_MCP_INDEXNOW_KEY_LOCATION`
  336. env var overrides the default verification-file URL when your CDN rewrites
  337. `/key.txt` paths.
  338. <a name="technical"></a>
  339. **Technical SEO (8, v0.3.0)** - no credentials needed; built-in HTTP client.
  340. - `inspect_meta(url)` - on-page surface in one call: title, meta description,
  341. meta robots, canonical, Open Graph + Twitter Card tags, hreflang, H1 count.
  342. - `check_canonical(url)` - canonical-link audit: self-referential / cross-host
  343. / protocol-mismatched / trailing-slash drift / canonical target reachable.
  344. - `mixed_content_check(url)` - parses an HTTPS page and flags any `http://`
  345. references (img / script / iframe / form action / srcset). No-op for `http://`.
  346. - `redirect_chain_audit(url, max_redirects=10)` - walks the chain hop by hop.
  347. Flags long chains, protocol downgrades, loops, non-2xx terminus.
  348. - `robots_txt_validate(site_url, probes?)` - parses robots.txt (per-group
  349. rules + sitemaps + Content-Signals), optionally verdicts (user_agent, url)
  350. probes using RFC 9309 longest-match (matches what Google + Bing actually do,
  351. not stdlib's first-match). Also detects a **stale edge-cached** robots.txt
  352. (cache-bust comparison; re-parses from the fresh content) and a **Cloudflare
  353. Managed robots.txt / Content-Signals** policy overriding your origin -
  354. catching false-clean robots on migrated/CF-fronted sites. (v0.8.0)
  355. - `sitemap_validate(sitemap_url)` - validates a sitemap or sitemap-index XML,
  356. counts entries, flags oversize + cross-host + missing lastmod. `.gz`
  357. transparent.
  358. - `sitemap_health(sitemap_url, sample_size=25)` - sample-HEAD audit. Status
  359. histogram + first non-2xx examples.
  360. - `robots_ai_posture(goal?, sitemap_url?)` - deterministic, offline advisor for
  361. the Content-Signals levers (`search` / `ai-input` / `ai-train`). Takes a
  362. business goal (`content_authority` default / `maximize_visibility` /
  363. `protect_ip`), recommends a posture with a plain-language rationale, lays out
  364. the trade-off alternatives, and emits a ready-to-apply artifact: the
  365. `Content-Signal:` directive line plus a full suggested robots.txt. No network,
  366. no writes. Every response carries the mandatory caveat that Content-Signal is
  367. honored only by adopting crawlers, is ignored by Googlebot, and is not a
  368. ranking factor. (v0.8.1)
  369. <a name="crux"></a>
  370. **Chrome UX Report (2)**
  371. - `crux_history(url? | origin?, form_factor?, metrics?)` - 25 weeks of p75
  372. Core Web Vitals via the CrUX History API. Reuses `PSI_API_KEY`; works
  373. anonymously at a tighter rate limit when no key is configured.
  374. - `crux_snapshot(url? | origin?, form_factor?)` - the current p75 Core Web
  375. Vitals (point-in-time, vs the history). Each metric reports a category
  376. (GOOD / NEEDS_IMPROVEMENT / POOR); the rolled-up rating is `overall_category`.
  377. Time metrics use `p75_ms`; the unitless CLS uses `p75`. Small origins return
  378. a `no_data` envelope. (v0.7.1)
  379. **Structured data + cross-site + on-page (7)** - no new credentials (the v0.9 SERP auto-fetch is optional).
  380. - `inspect_schema(url)` - extract every JSON-LD block from a page; report
  381. the schema.org @type counts and a sample entity per type.
  382. - `validate_schema(url, types?)` - verdict each JSON-LD entity against the
  383. Google Rich Results required-field set. Covers Article, NewsArticle,
  384. BlogPosting, Product, FAQPage, BreadcrumbList, Organization, LocalBusiness,
  385. Event, Review, Recipe. Per-entity verdict plus missing_required and
  386. missing_recommended lists.
  387. - `hreflang_consistency_check(urls)` - cross-page hreflang audit on a
  388. user-supplied URL set. Flags missing reciprocity, broken hreflang
  389. targets, duplicate hreflang on one page, missing self-link, missing
  390. x-default when there are 3+ language variants.
  391. - `internal_link_graph(start_url, max_depth=2, max_pages=50)` - small
  392. BFS crawl within the same host. Per-page in-degree + out-degree,
  393. orphan pages, broken internal links, depth distribution. Hard caps
  394. (max_depth <= 4, max_pages <= 200) so a misuse never melts the host.
  395. - `lighthouse_budget(url, budget)` - wraps `psi_analyze` and verdicts
  396. the results against a budget dict, e.g.
  397. `{performance: 80, LCP_ms: 2500, CLS: 0.1}`. Per-metric pass/fail and
  398. an overall verdict. Useful as a CI / pre-deploy gate inside an LLM
  399. session. Reuses `PSI_API_KEY`.
  400. - `internal_link_recommend(start_url, site_url?, days?, position_min?, position_max?, relevance_floor?, limit?)`
  401. - recommends specific source->target internal links from high-in-degree pages
  402. to GSC striking-distance pages (default position 8-20 with real impressions),
  403. with anchor text. Ranks sources by lexical relevance + internal authority, skips
  404. pages that already link the target, balances anchor text, and never suggests
  405. nofollow. Built on `internal_link_graph` + GSC. Free. (v0.9.0)
  406. - `onpage_serp_gap(target_url, query?, competitor_urls?, max_competitors?)` - the
  407. headings, entities, and schema the top SERP results have that a target page
  408. lacks, turned into on-page actions. FREE with caller-supplied `competitor_urls`;
  409. optional DataForSEO SERP auto-fetch by `query`, which also returns winnability
  410. signals (`serp_composition` AI-Overview / UGC zero-click risk) and, with Open
  411. PageRank, competitor domain authority. Surfaces information gain, not just
  412. parity. Boilerplate/nav headings are filtered out (pattern-class chrome filter). (v0.9.0; F6 fix v0.9.1, F1 generalized v0.9.2)
  413. Every tool's `tools/list` entry carries the MCP standard annotations
  414. (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so MCP
  415. hosts can decide what to auto-approve and what to confirm.
  416. </details>
  417. ## Workflow prompts
  418. The server publishes thirteen named MCP prompts (via `prompts/list` /
  419. `prompts/get`) that chain the granular tools into common SEO workflows. Hosts
  420. that surface prompts (Claude Desktop's slash menu, Cursor's command palette,
  421. Cline's prompt picker) advertise them automatically.
  422. | Prompt | Arguments | Chains |
  423. |---|---|---|
  424. | `post_deploy_verify` | `urls`, `zone?`, `skip_psi?` | `cf_purge_cache` -> `gsc_request_indexing` -> `indexnow_bulk_submit` -> `psi_analyze` |
  425. | `weekly_review` | `days?`, `site_url?` | `gsc_compare_periods` (gainers + losers via sort_dir) -> `gsc_query_opportunities` -> `gsc_query_gaps` -> `ga4_organic_search_overview` |
  426. | `content_audit` | `site_url?`, `days?`, `top_n_queries?` | `gsc_top_queries` -> per-query `gsc_top_pages_by_query` -> cannibalization recommendation |
  427. | `migration_check` | `urls`, `site_url?` | `gsc_batch_inspect_urls` -> `gsc_list_sitemaps` -> canonical-agreement table -> remediation list |
  428. | `technical_seo_audit` | `url` | `inspect_meta` -> `check_canonical` -> `redirect_chain_audit` -> `mixed_content_check` -> `robots_txt_validate` -> `sitemap_health` -> severity-ranked triage list |
  429. | `structured_data_audit` | `urls` | per-URL `inspect_schema` -> `validate_schema` -> (if 2+ URLs) `hreflang_consistency_check` -> per-URL + cross-URL report |
  430. | `pre_deploy_check` | `urls` | `robots_txt_validate` -> per-URL `inspect_meta` -> `check_canonical` -> `validate_schema` -> `redirect_chain_audit` -> `mixed_content_check` -> deploy-gate verdict (block on critical issues, approve otherwise) |
  431. | `content_brief` (v0.7.1) | `topic`, `target_query`, `site_url?` | `gsc_top_pages_by_query` -> `inspect_meta` / `inspect_schema` on top rankers -> brief with required sections + validation rules |
  432. | `content_outline` (v0.7.1) | `brief` | outline with rules: >=5 H2, >=70% target-query coverage, H1 has the primary keyword |
  433. | `content_article` (v0.7.1) | `outline`, `brief` | article with rules: word count within +/-15%, per-section minimum, internal links, inline JSON-LD hint, no em-dashes |
  434. | `content_workflow` (v0.7.1) | `site_url?`, `days?` | `content_opportunities` -> brief -> outline -> article -> `pre_deploy_check` -> `gsc_request_indexing` + `indexnow_submit` -> scheduled `content_performance` |
  435. | `content_performance` (v0.7.1) | `url`, `target_queries?`, `site_url?` | `gsc_compare_periods` + `gsc_search_analytics` before / after the publish window |
  436. | `seo_setup_audit` (v0.7.1) | `site_url?`, `property_id?` | `ga4_setup_audit` -> `cf_settings_audit` -> `psi_opportunities` -> `robots_txt_validate` -> consolidated stack-config report |
  437. Why prompts and not megatools: composability. A failed step inside a megatool
  438. poisons the megatool's envelope and the host loses the ability to retry just
  439. the failing leg. Prompts hand the host a recipe; each step's envelope arrives
  440. intact at the LLM.
  441. ## Install
  442. SEOMonster ships **two install paths**, both fully local:
  443. - **`.mcpb` bundle** for Claude Desktop. One-click install, GUI form for
  444. credentials, secret-typed inputs stored in the OS keychain. Recommended for
  445. most users.
  446. - **`uvx`** for Cursor, Cline, Codex, and Claude Desktop power users who prefer
  447. to hand-edit MCP config files.
  448. Both paths run the same Python package (`seo_mcp`) and expose the same
  449. 70 tools. The difference is only how the host launches the server
  450. and how it collects credentials.
  451. ### Claude Desktop (recommended): `.mcpb` bundle
  452. Three short steps. The OAuth consent is **run once from a terminal** (the GUI
  453. flow inside Claude Desktop's MCP subprocess times out before a real user can
  454. finish; see [Why pre-flight auth?](#why-pre-flight-auth) below).
  455. **1. Install the bundle.** Download
  456. [the versioned `.mcpb` asset](https://github.com/avansaber/seo-monster/releases/latest)
  457. from GitHub releases (or, when listed, from the [Claude
  458. Directory](https://claude.ai/directory)) and double-click it. Claude Desktop
  459. verifies the bundle, runs `uv` to materialize the Python environment, and
  460. shows a configuration form:
  461. | Field | Type | Required | Notes |
  462. |--------------------------------|----------------|----------|-----------------------------------------------------------------------|
  463. | Google OAuth Client Secrets | file picker | yes | Desktop-app client-secrets JSON from Google Cloud Console. |
  464. | Google OAuth Token Cache Path | string | yes | Defaults to `~/.config/seo-monster/token.json`. Written on consent. |
  465. | GSC Default Property | string | no | e.g. `sc-domain:example.com` or `https://www.example.com/`. |
  466. | GA4 Default Property ID | string | no | `properties/123456789` or bare `123456789`. |
  467. | PageSpeed Insights API Key | string, secret | no | Stored in the OS keychain. **Strongly recommended** ([why?](#pagespeed-insights)). |
  468. | Cloudflare API Token | string, secret | no | Stored in the OS keychain. Required only for the Cloudflare tools. |
  469. | Cloudflare Default Zone | string | no | e.g. `example.com`. |
  470. | IndexNow Key | string, secret | no | Required only for IndexNow tools. Any 8-128 hex string you generate. |
  471. | IndexNow Key File URL | string | no | Override the default verification location (`https://<host>/<key>.txt`). |
  472. Fill the fields, click **Save**, then **toggle the extension on**. Quit Claude
  473. Desktop completely (⌘Q on macOS) and reopen.
  474. **2. Run the one-time OAuth consent from a terminal.** Before using any
  475. Google-backed tool, run:
  476. ```sh
  477. uvx seo-monster auth
  478. ```
  479. A browser opens. Approve the requested scopes. The command writes
  480. `token.json` to the path you configured (default `~/.config/seo-monster/token.json`)
  481. with `0600` permissions, then exits. This step is the recommended pattern; it
  482. sidesteps the timeout that Claude Desktop imposes on every tool call.
  483. **3. Start a new chat in Claude Desktop and use the tools.** Click the 🔧
  484. tools icon in the input box; you should see 70 SEOMonster tools. Try
  485. `system_status` first to verify everything is configured.
  486. #### Why pre-flight auth?
  487. The OAuth installed-app flow opens a local browser and waits for the user to
  488. finish the consent screen. Inside Claude Desktop, MCP servers are launched as
  489. subprocesses whose tool calls have a ~30-60 second timeout. Real users do not
  490. complete browser consent that fast, so the originating call times out, and
  491. since every Google tool retries the flow until a token exists, every call
  492. times out in turn. Running `uvx seo-monster auth` once from a terminal puts
  493. the token on disk; from that point on, Claude Desktop's MCP server just reads
  494. the cached token and silently refreshes it as needed.
  495. ### `uvx` for Cursor, Cline, Codex (and Claude Desktop power users)
  496. `uvx` runs the published PyPI package `seo-monster` in an ephemeral
  497. environment. Add the snippet for your host below, using the **absolute path**
  498. to `uvx` (find it with `which uvx`; GUI hosts do not read your shell profile).
  499. #### Cursor (`~/.cursor/mcp.json` or project `.cursor/mcp.json`)
  500. ```json
  501. {
  502. "mcpServers": {
  503. "seomonster": {
  504. "command": "/Users/me/.local/bin/uvx",
  505. "args": ["seo-monster"],
  506. "env": {
  507. "SEO_MCP_GOOGLE_OAUTH_CLIENT": "/Users/me/.config/seo-monster/client_secret.json",
  508. "SEO_MCP_GOOGLE_TOKEN": "/Users/me/.config/seo-monster/token.json",
  509. "SEO_MCP_GA4_PROPERTY_ID": "properties/123456789",
  510. "PSI_API_KEY": "AIza...",
  511. "CF_API_TOKEN": "..."
  512. }
  513. }
  514. }
  515. }
  516. ```
  517. #### Cline (`cline_mcp_settings.json`)
  518. ```json
  519. {
  520. "mcpServers": {
  521. "seomonster": {
  522. "command": "/Users/me/.local/bin/uvx",
  523. "args": ["seo-monster"],
  524. "env": {
  525. "SEO_MCP_GOOGLE_OAUTH_CLIENT": "/Users/me/.config/seo-monster/client_secret.json",
  526. "SEO_MCP_GOOGLE_TOKEN": "/Users/me/.config/seo-monster/token.json"
  527. },
  528. "alwaysAllow": ["system_status", "gsc_search_analytics", "ga4_run_report", "psi_analyze"]
  529. }
  530. }
  531. }
  532. ```
  533. `alwaysAllow` lists read tools so Cline does not prompt on each call. Leave the
  534. cache-purge tools off so they always prompt.
  535. #### Codex (`~/.codex/config.toml`)
  536. ```toml
  537. [mcp_servers.seomonster]
  538. command = "/Users/me/.local/bin/uvx"
  539. args = ["seo-monster"]
  540. [mcp_servers.seomonster.env]
  541. SEO_MCP_GOOGLE_OAUTH_CLIENT = "/Users/me/.config/seo-monster/client_secret.json"
  542. SEO_MCP_GOOGLE_TOKEN = "/Users/me/.config/seo-monster/token.json"
  543. SEO_MCP_GA4_PROPERTY_ID = "properties/123456789"
  544. ```
  545. #### Claude Desktop, direct `uvx` (advanced)
  546. If you prefer to hand-edit `claude_desktop_config.json` instead of using the
  547. `.mcpb` bundle, the same snippet shape as Cursor above works.
  548. <a name="auth"></a>
  549. ## Auth
  550. The four services authenticate independently. Configure only the ones you use;
  551. a tool for an unconfigured service returns a clear `AUTH_MISSING` error rather
  552. than failing the server.
  553. ### Quick setup (recommended): `seo-monster setup`
  554. Run `seo-monster setup` once from a terminal. It interactively collects your
  555. Cloudflare token, PageSpeed Insights key, IndexNow key, and the default GSC and
  556. GA4 properties, validates what it can against the live APIs, and writes them to
  557. `~/.config/seo-mcp/config.toml` with `0600` permissions. Your MCP host config
  558. then needs no secrets in it:
  559. ```json
  560. { "command": "uvx", "args": ["seo-monster"] }
  561. ```
  562. Two things `setup` does not do, by design:
  563. - **Google OAuth** still uses the separate one-time browser step. After `setup`,
  564. run `seo-monster auth` to complete Google consent (see the next section).
  565. - It never overrides environment variables. Anything set in your host's `env`
  566. block still wins over the config file, so CI and Docker keep using env vars.
  567. `setup` is re-runnable: existing values are shown as defaults and kept when you
  568. leave a field blank. The sections below document the per-service env vars, which
  569. are what `setup` writes for you and what CI pipelines can set directly.
  570. ### Google (Search Console + Analytics 4) - OAuth, recommended
  571. This is the lower-friction path: no Cloud service account, no per-property email
  572. grants.
  573. 1. In the [Google Cloud Console](https://console.cloud.google.com/), create (or
  574. pick) a project and **enable the APIs** you will use:
  575. - Search Console API
  576. - Indexing API (for `gsc_request_indexing`)
  577. - Google Analytics Data API (for the GA4 tools)
  578. - PageSpeed Insights API (only if you want a PSI key; see below)
  579. 2. Create an OAuth client of type **Desktop app** and download the client-secrets
  580. JSON.
  581. 3. Point the server at it and at a writable token path:
  582. - `SEO_MCP_GOOGLE_OAUTH_CLIENT` = path to the client-secrets JSON
  583. - `SEO_MCP_GOOGLE_TOKEN` = a writable path where the token will be cached
  584. 4. **One-time:** run `uvx seo-monster auth` from a terminal. A browser opens;
  585. approve the scopes. The command writes `token.json` (`0600`) and exits.
  586. 5. Subsequent runs (server-side) refresh the token silently. **The server
  587. never opens a browser**; if the cached token is missing, tools return
  588. `AUTH_MISSING` pointing back at the `auth` command.
  589. The signed-in Google account must have access to the Search Console properties
  590. and GA4 properties you query.
  591. **Token-cache hardening.** The cached token is refresh-capable and equivalent
  592. to a long-lived credential for the requested scopes. The server writes it with
  593. `0600` and its parent directory with `0700`. Keep `SEO_MCP_GOOGLE_TOKEN` under
  594. a directory you control (e.g. `~/.config/seo-monster/`) and do not put it on a
  595. shared filesystem.
  596. ### Google - service account (advanced, headless)
  597. For fully headless or server deployments where a browser is not available:
  598. 1. Create a service account and download its JSON key.
  599. 2. Set `SEO_MCP_GOOGLE_CREDENTIALS` (or the standard
  600. `GOOGLE_APPLICATION_CREDENTIALS`) to the key path.
  601. 3. Grant the service-account email access on each property:
  602. - Search Console: add it as a user on the property.
  603. - GA4: add it as a Viewer on the property.
  604. If both OAuth and a service account are configured, OAuth is used.
  605. > **Coverage note.** The OAuth installed-app path is exercised in our
  606. > validation pass and in production-style smoke tests. The service-account
  607. > path is documented but not independently validated against a live Cloud
  608. > project. If you hit issues on the SA path, please open an issue.
  609. ### Scopes (minimal vs full)
  610. The default consent requests the scopes needed for every tool, including the two
  611. writes:
  612. | Capability | Scope |
  613. |-------------------------------------|--------------------------------|
  614. | GSC read | `webmasters` (covers readonly) |
  615. | GSC sitemap submit | `webmasters` |
  616. | GSC indexing request | `indexing` |
  617. | GA4 reporting | `analytics.readonly` |
  618. If you only want reads, you can consent to a narrower set
  619. (`webmasters.readonly` + `analytics.readonly`) and simply not call
  620. `gsc_submit_sitemap` / `gsc_request_indexing`; calling a write tool without its
  621. scope returns `SCOPE_INSUFFICIENT` with remediation, never a crash.
  622. ### PageSpeed Insights
  623. PSI works without a key in principle, but in practice the **anonymous quota is
  624. shared across every caller without a key and is frequently exhausted**: a
  625. single `psi_analyze` call against the anonymous endpoint often returns
  626. `RATE_LIMITED`. **Treat the anonymous mode as a fallback, not the steady
  627. state.**
  628. To get reliable PSI access:
  629. 1. In Cloud Console, enable the **PageSpeed Insights API**.
  630. 2. Create an **API key** (Credentials > Create credentials > API key). It
  631. takes a minute. The key is free.
  632. 3. Set `PSI_API_KEY` (or use the field in the `.mcpb` configuration form).
  633. The PSI API only accepts the key as a URL query parameter (not a header), so
  634. treat PSI keys as low-sensitivity. Scope the key to the PageSpeed Insights
  635. API only and attach no other GCP roles.
  636. ### Cloudflare
  637. Create an API token at
  638. [dash.cloudflare.com/profile/api-tokens](https://dash.cloudflare.com/profile/api-tokens)
  639. and set `CF_API_TOKEN` (and optionally `CF_ZONE` for a default zone). Grant only
  640. the permissions you need:
  641. | Permission | Needed for |
  642. |-------------------------|-------------------------------------|
  643. | Zone: `Zone:Read` | `cf_list_zones`, `cf_zone_info` |
  644. | Zone: `DNS:Read` | `cf_list_dns` |
  645. | Account: `Account Analytics:Read` | `cf_web_analytics` |
  646. | Zone: `Cache Purge:Purge` | `cf_purge_cache`, `cf_purge_cache_all` (only if you enable destructive mode) |
  647. | Zone: `Single Redirect:Edit` | `cf_create_redirect`, `cf_delete_redirect` (only if you enable destructive mode); `cf_list_redirects` reads with it |
  648. | Zone: `Zone Settings:Edit` | `cf_settings_update` (only if you enable destructive mode); `cf_settings_audit` only needs Zone Settings Read |
  649. | Account: `Account Rulesets:Edit` + `Account Filter Lists:Edit` | `cf_bulk_redirect_upsert` (only if you enable destructive mode) |
  650. ### IndexNow
  651. IndexNow notifies Bing, Yandex, Naver, Seznam, and Yep when a URL is created
  652. or updated. Google does not participate, so the IndexNow tools complement
  653. rather than replace `gsc_request_indexing`.
  654. #### One-time setup
  655. 1. **Generate a key.** Any 8-128 character string of letters, digits, or
  656. hyphens (`a-z`, `A-Z`, `0-9`, `-`) per the IndexNow spec. Common patterns:
  657. a 32-char lowercase hex string (e.g. `python -c "import secrets;
  658. print(secrets.token_hex(16))"`) or any random alphanumeric of similar
  659. length. Treat it like an API key; do not commit it.
  660. 2. **Configure SEOMonster** by setting `SEO_MCP_INDEXNOW_KEY` to that string
  661. (or use the `.mcpb` configuration form; the field is marked sensitive and
  662. lands in the OS keychain).
  663. 3. **Host the verification file** at `https://<your-host>/<key>.txt`. The
  664. file body MUST be **exactly** the key string with no trailing newline, no
  665. BOM, no extra whitespace, no HTML wrapper. The Content-Type should be
  666. `text/plain`. Confirm with `curl -i https://<your-host>/<key>.txt` before
  667. moving on; the response body must be byte-identical to the key.
  668. 4. **(Optional)** Set `SEO_MCP_INDEXNOW_KEY_LOCATION` if the verification
  669. file lives at a non-standard URL (some CDNs rewrite `/key.txt` paths).
  670. The default location is `https://<host>/<key>.txt` derived from the URLs
  671. you submit, so you usually do not need this.
  672. #### Same-host constraint
  673. Every URL submitted in one `indexnow_submit` or `indexnow_bulk_submit` call
  674. must share the same host as the verification file. Mixed-host batches are
  675. rejected by IndexNow with HTTP 422; `indexnow_bulk_submit` enforces this
  676. client-side and returns `INVALID_INPUT` before any network call when it
  677. detects mixed hosts.
  678. If you have multiple hosts, host a verification file per host and either
  679. make separate calls per host or override `SEO_MCP_INDEXNOW_KEY_LOCATION`
  680. per call (the tool does not currently expose per-call override; set
  681. distinct env values per session).
  682. #### Common errors
  683. | Symptom | Likely cause |
  684. |---|---|
  685. | `AUTH_INVALID` from `indexnow_submit` | Engines could not fetch `https://<host>/<key>.txt`. Confirm the file returns HTTP 200 with the exact key as the body |
  686. | `INVALID_INPUT` from `indexnow_bulk_submit` mentioning mixed hosts | URL list spans multiple hosts; split into per-host batches |
  687. | `RATE_LIMITED` | Hit IndexNow's per-host rate cap. Wait before retrying |
  688. ### Verify your setup
  689. After configuring, call `system_status` to see what is detected. Call it with
  690. `{"probe": true}` to make one cheap live request per configured service and
  691. confirm the credentials actually work (GSC lists properties, GA4 runs a 1-row
  692. report against the default property, Cloudflare lists one zone, PSI pings the
  693. endpoint). With `probe` off (the default) it does a config-only check and makes
  694. no network calls.
  695. <a name="destructive-mode"></a>
  696. ## Destructive mode
  697. Cache purges affect every visitor, so they are off by default. Set
  698. `SEO_MCP_ALLOW_DESTRUCTIVE=true` to enable `cf_purge_cache` and
  699. `cf_purge_cache_all`. While off, those tools return `DESTRUCTIVE_DISABLED` and
  700. make no network call.
  701. `cf_purge_cache_all` (purge the whole zone) carries an extra safeguard: it
  702. requires a `confirm` argument equal to the resolved zone hostname. A missing or
  703. mismatched `confirm` returns `CONFIRM_REQUIRED` and issues no purge.
  704. The two GSC writes (`gsc_submit_sitemap`, `gsc_request_indexing`) are **not**
  705. gated; they are routine, low-blast-radius SEO tasks.
  706. <a name="configuration"></a>
  707. ## Configuration
  708. Resolution is environment-first, with a TOML file fallback. Environment always
  709. wins. The config file is normally written for you by `seo-monster setup` (with
  710. `0600` permissions); you can also write it by hand or set the env vars below.
  711. | Env var | Service | Purpose |
  712. |----------------------------------|---------|--------------------------------------------------|
  713. | `SEO_MCP_GOOGLE_OAUTH_CLIENT` | Google | OAuth client-secrets JSON path (recommended). |
  714. | `SEO_MCP_GOOGLE_TOKEN` | Google | Writable cached-token path (OAuth). |
  715. | `SEO_MCP_GOOGLE_CREDENTIALS` | Google | Service-account key path (alternative). |
  716. | `GOOGLE_APPLICATION_CREDENTIALS` | Google | Standard service-account fallback. |
  717. | `SEO_MCP_GSC_DEFAULT_SITE` | GSC | Default property, e.g. `sc-domain:example.com`. |
  718. | `SEO_MCP_GA4_PROPERTY_ID` | GA4 | Default property, e.g. `properties/123456789`. |
  719. | `SEO_MCP_DATA_STATE` | GSC | `all` (default) or `final`. |
  720. | `PSI_API_KEY` | PSI | PageSpeed Insights API key (optional). |
  721. | `CF_API_TOKEN` | CF | Cloudflare API token. |
  722. | `CF_ZONE` | CF | Default zone hostname. |
  723. | `SEO_MCP_INDEXNOW_KEY` | IndexNow| Shared key for the IndexNow tools (sensitive). |
  724. | `SEO_MCP_INDEXNOW_KEY_LOCATION` | IndexNow| Override default key-file URL (optional). |
  725. | `SEO_MCP_ALLOW_DESTRUCTIVE` | all | `true` enables cache-purge tools. Default off. |
  726. | `SEO_MCP_CONFIG` | all | Path to the TOML config file. |
  727. | `DATAFORSEO_LOGIN` / `DATAFORSEO_PASSWORD` | DataForSEO | Optional (v0.9): SERP/PAA, keyword volume/difficulty/intent, competitor gap, Google AIO. |
  728. | `SEO_MCP_SERP_PROVIDER` and `SERPBASE_API_KEY` | SerpBase | Optional paid SERP source when explicitly selected as `serpbase`. |
  729. | `OPENPAGERANK_API_KEY` | Open PageRank | Optional (v0.9): free competitor domain authority. |
  730. | `PERPLEXITY_API_KEY` / `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` | AI engines | Optional (v0.9): engines for `ai_citation_track` (any subset). |
  731. | `GOOGLE_ADS_DEVELOPER_TOKEN` / `GOOGLE_ADS_CUSTOMER_ID` | Google Ads | Optional (v0.9): volume alt to DataForSEO (needs adwords-scope consent). |
  732. Config file fallback at `~/.config/seo-mcp/config.toml` (or `SEO_MCP_CONFIG`):
  733. ```toml
  734. [google]
  735. oauth_client = "/Users/me/.config/seo-mcp/client_secret.json"
  736. token = "/Users/me/.config/seo-mcp/token.json"
  737. # credentials = "/Users/me/.config/seo-mcp/sa.json" # service-account alternative
  738. [gsc]
  739. default_site = "sc-domain:example.com"
  740. data_state = "all"
  741. [ga4]
  742. property_id = "properties/123456789"
  743. [psi]
  744. api_key = "AIza..."
  745. [cloudflare]
  746. api_token = "..."
  747. zone = "example.com"
  748. [server]
  749. allow_destructive = false
  750. # Optional v0.9 providers (discovery + AI/GEO). The free GSC/GA4/HTTP core
  751. # works without any of these; each tool degrades gracefully when unset.
  752. [dataforseo]
  753. # login = "..."
  754. # password = "..."
  755. [openpagerank]
  756. # api_key = "..."
  757. [ai_engines]
  758. # perplexity = "..."
  759. # openai = "..."
  760. # anthropic = "..."
  761. # gemini = "..."
  762. [google_ads]
  763. # developer_token = "..." # volume alt to DataForSEO; needs adwords-scope OAuth
  764. # customer_id = "..."
  765. ```
  766. <a name="errors"></a>
  767. ## Result envelope
  768. Every tool returns the same shape. On success:
  769. ```json
  770. { "ok": true, "data": { /* tool-specific */ }, "error": null }
  771. ```
  772. On failure:
  773. ```json
  774. {
  775. "ok": false,
  776. "data": null,
  777. "error": {
  778. "code": "AUTH_MISSING",
  779. "service": "gsc",
  780. "message": "No Google credentials found for Search Console.",
  781. "remediation": "Configure OAuth ... or a service-account key. See README > Auth.",
  782. "docs_url": "https://www.avansaber.com/seomonster/docs/#auth",
  783. "details": null
  784. }
  785. }
  786. ```
  787. Error codes:
  788. | Code | Meaning |
  789. |------------------------|---------------------------------------------------------------|
  790. | `AUTH_MISSING` | No credential configured for the service. |
  791. | `AUTH_INVALID` | Credential present but rejected (401/403, bad key, expired). |
  792. | `SCOPE_INSUFFICIENT` | Token lacks the scope this tool needs. |
  793. | `DESTRUCTIVE_DISABLED` | A cache-purge tool was called with destructive mode off. |
  794. | `CONFIRM_REQUIRED` | `cf_purge_cache_all` called without a matching `confirm`. |
  795. | `NOT_FOUND` | Site / property / zone / record not found or not visible. |
  796. | `INVALID_INPUT` | Argument failed validation (bad date, missing required arg). |
  797. | `RATE_LIMITED` | Upstream 429. |
  798. | `SERVICE_DISABLED` | A Google Cloud API is not enabled; `details` has the activation URL. |
  799. | `UPSTREAM_ERROR` | Any other non-2xx from an upstream API. |
  800. ## Development
  801. ```sh
  802. git clone https://github.com/avansaber/seo-monster
  803. cd seo-monster
  804. uv sync --locked --extra dev
  805. uv run --no-sync pytest # offline test suite
  806. uv run --no-sync seo-monster # run the server over stdio
  807. uv run --no-sync seo-monster auth # one-time OAuth consent
  808. ```
  809. The package exposes two console-script aliases: `seo-monster` (canonical,
  810. matches the PyPI distribution) and `seo-mcp` (a v0.1.x dev alias kept for
  811. back-compat). Both invoke the same entry point. As of v0.2.0, invoking the
  812. server via `seo-mcp` emits a one-line stderr deprecation notice; nothing on
  813. stdout, so the MCP protocol channel is unaffected. Production configs should
  814. use `seo-monster`; the alias will be removed in a future major release.
  815. Tests are fully offline: they mock at the client layer, so no network and no
  816. credentials are needed to run them.
  817. > **SDK 2 source builds.** This checkout requires Python 3.11 or later and MCP Python SDK 2.3 or later within major version 2. The MCP handshake reports the engine package version; the protocol server name remains `seo-mcp`. After updating a source installation, sync its dependencies and restart the MCP host. Published packages and existing installations retain the version they installed until upgraded.
  818. ## Changelog
  819. Release-by-release notes, including the validation checks each version's
  820. external testing pass should cover, live in [CHANGELOG.md](https://github.com/avansaber/seo-monster/blob/v0.11.2/CHANGELOG.md).
  821. ## Privacy
  822. SEOMonster runs entirely on your machine and talks only to the upstream APIs
  823. you configure. The maintainers do not see any of your data, credentials,
  824. queries, or tool calls. See [PRIVACY.md](https://github.com/avansaber/seo-monster/blob/v0.11.2/PRIVACY.md) for the full statement.
  825. ## License
  826. MIT. See [LICENSE](https://github.com/avansaber/seo-monster/blob/v0.11.2/LICENSE).
  827. <!-- mcp-name: io.github.avansaber/seo-monster -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.