SEO_MCP_GOOGLE_OAUTH_CLIENT — Path to your Desktop-app OAuth client-secrets JSON, downloaded from Google Cloud Console. Required for Search Console, Indexing, and GA4 tools.
SEO_MCP_GOOGLE_TOKEN — Writable path where the cached OAuth token is stored. On first use, a browser opens for one-time consent and the token is written here. Default: ${HOME}/.config/seo-monster/token.json
SEO_MCP_GSC_DEFAULT_SITE — Default Search Console property, e.g. 'sc-domain:example.com' or 'https://www.example.com/'.
SEO_MCP_GA4_PROPERTY_ID — Default GA4 property, e.g. 'properties/123456789' or bare '123456789'.
PSI_API_KEY — Google API key shared by PageSpeed Insights and Chrome UX Report History tools. Optional; both work anonymously at a tighter rate limit when unset.
CF_API_TOKEN — Cloudflare API token. Optional; needed only for the Cloudflare tools. Scopes: Zone:Read, DNS:Read, Account Analytics:Read, and (only when destructive mode is on) Cache Purge:Purge, Single Redirect:Edit, Zone Settings:Edit, and (for bulk redirects) Account Rulesets:Edit + Account Filter Lists:Edit.
CF_ZONE — Default Cloudflare zone hostname, e.g. 'example.com'.
SEO_MCP_INDEXNOW_KEY — IndexNow shared key (any 8-128 hex string you generate). Required only for the IndexNow tools. Host the key file at https://<your-host>/<key>.txt for engine verification.
SEO_MCP_INDEXNOW_KEY_LOCATION — Override the default IndexNow key-file URL (https://<host>/<key>.txt). Set only if you host the key file at a non-standard path.
SEO_MCP_ALLOW_DESTRUCTIVE — Set to 'true' to enable the Cloudflare cache-purge tools. Default false: all destructive tools refuse to run.
SEO_MCP_SERP_PROVIDER — Optional SERP provider selection. Set to serpbase to use SerpBase; DataForSEO remains the default when unset.
SERPBASE_API_KEY — API key for the optional SerpBase provider. A key alone does not select the provider.
DATAFORSEO_LOGIN — DataForSEO Basic-auth login. Optional (v0.9). Unlocks SERP/PAA/related, keyword volume+difficulty+intent, competitor keyword-gap, and Google AI Overview citations for keyword_universe / serp_adjacency_expand / onpage_serp_gap auto-fetch / ai_citation_track.
OPENPAGERANK_API_KEY — Open PageRank (DomCop) free API key. Optional (v0.9). Free competitor domain-authority proxy for onpage_serp_gap.
PERPLEXITY_API_KEY — Perplexity Sonar API key. Optional (v0.9). One of the AI answer-engines for ai_citation_track.
OPENAI_API_KEY — OpenAI API key (Responses web_search). Optional (v0.9). One of the AI answer-engines for ai_citation_track.
ANTHROPIC_API_KEY — Anthropic API key (web_search tool). Optional (v0.9). One of the AI answer-engines for ai_citation_track.
GEMINI_API_KEY — Google Gemini API key (Search grounding). Optional (v0.9). One of the AI answer-engines for ai_citation_track.
GOOGLE_ADS_DEVELOPER_TOKEN — Google Ads API developer token. Optional (v0.9). Volume-only alternative to DataForSEO for keyword_universe; live use also needs an adwords-scope OAuth re-consent.
GOOGLE_ADS_CUSTOMER_ID — Google Ads customer id (digits). Optional (v0.9). Required alongside GOOGLE_ADS_DEVELOPER_TOKEN.
Claude Code no tiene enlace de instalación para un comando local. Copia el comando de abajo y ejecútalo en una terminal.
You don't open a new tool — you just ask, in plain English, inside Claude (or Cursor / Cline / Codex):
You"What should I write about next?"
🦖 SEOMonster 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.
Local-first SEO MCP: track AI citations, Search Console, GA4, PageSpeed, Cloudflare, IndexNow, CrUX.
Ejecutar en PlugMCP
Host a copy with our keys and logs.
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
Surfaces near-ranking topics from your own Search Console demand
"Is this page ready to publish?"
Runs the technical-SEO + structured-data checks before you ship
"Get this indexed."
Nudges Google (Indexing API) and Bing / Yandex (IndexNow)
"Did my change actually move rankings?"
Before/after attribution vs a matched control group — with a confidence interval, not a guess
"Is ChatGPT recommending us, or our competitors?"
Tracks your brand's share of voice across the AI answer engines
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.
[!NOTE]
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.
Your data, your machine. User-credential-driven; nothing is sent to any third party.
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.
Lean. Standard library + the mcp SDK + the Google client libraries; PageSpeed and Cloudflare ride on urllib, no extra HTTP dependency.
Quickstart
[!TIP]
Fastest path: the one-click install buttons above. Or add it to any MCP client by hand:
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 and Auth.
How it works
flowchart LR
U["You — plain English"] --> H["Claude · Cursor · Cline · Codex"]
H -- "MCP · stdio" --> S["SEOMonster<br/>70 tools"]
S --> GSC["Search Console · GA4"]
S --> PSI["PageSpeed · CrUX"]
S --> CF["Cloudflare · IndexNow"]
S --> AI["AI engines · SERP<br/>(optional)"]
S -. "your creds · your machine" .-> U
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.
Requirements
For the .mcpb bundle path (Claude Desktop): just Claude Desktop on macOS
or Windows. The bundle declares Python 3.11+ as a runtime; Claude Desktop
materializes the environment for you. No prior uv install needed.
For the uvx path (Cursor, Cline, Codex, advanced Claude Desktop): Python
3.11 or newer plus uv (which provides uvx).
Find the absolute path to uvx with which uvx; GUI hosts do not read your
shell profile, so MCP configs need the full path.
Tools
70 tools, grouped by service. All return the same result envelope (see
Result envelope). Call system_status first if unsure what
is configured. The server also publishes thirteen named workflow prompts.
Cross-service
system_status - which services are configured/reachable, the Google auth
method and scopes, whether destructive mode is on, the full tool catalog,
and the list of registered prompts.
Google Search Console (18)
Workhorses
gsc_list_properties - properties the credentials can see, with permission
level and a derived writable flag (true for siteOwner / siteFullUser).
gsc_search_analytics - the workhorse: clicks/impressions/CTR/position by
dimensions, date range, filters, and data_state.
gsc_batch_inspect_urls - inspect up to 25 URLs, per-URL failures collected.
gsc_list_sitemaps - registered sitemaps and their status.
gsc_submit_sitemap - submit a sitemap (write, un-gated; needs the writable
scope). Accepts either sitemap_url (friendly) or feedpath (raw API field).
gsc_request_indexing - request (re)crawl via the Indexing API (write,
un-gated). Accepts singular url or urls.
Query intelligence (v0.2.0)
gsc_query_opportunities - queries already ranking top N with below-target
CTR. Title and meta optimization candidates.
gsc_query_gaps - queries that draw impressions but barely any clicks.
Content opportunity signal.
gsc_new_queries - queries appearing in the current window with no prior
impressions. Emerging topics.
gsc_top_pages_by_query - which pages rank for a specific query. The
cannibalization audit input.
Multi-property + lifecycle (v0.5.0)
gsc_portfolio_summary(days, include?, exclude?) - multi-property fleet
view. Per-property one-row summary (clicks, impressions, CTR, position)
for the last N days, plus a portfolio-level rollup. Honors optional
include / exclude filters. The single fastest answer to "how is the
whole portfolio doing?" across agency or multi-brand setups.
gsc_trending_pages(days, limit) - pages whose impressions grew most over
the last N days vs the prior N days. Wrapper on gsc_compare_periods with
dimensions=["page"], sort_by="delta_impressions", sort_dir="desc".
gsc_decaying_pages(days, limit) - same wrapper, ascending sort. Pages
to rescue.
gsc_coverage_audit(urls, site_url?) - heuristic coverage audit. The GSC
Index Coverage report is not exposed in the API; this tool takes a user-
supplied URL list (typically pulled from a sitemap) and bulk-inspects
each, then rolls up verdicts (PASS / PARTIAL / FAIL) and coverage_state
frequencies.
Content intelligence (4)
content_opportunities(site_url?, days?, count?, impressions_min?) - ranks
data-grounded content topics from your own Search Console data: fuses
CTR-vs-expected gap (curve self-calibrated from your own per-position CTR),
striking-distance position, demand, and momentum into a transparent
opportunity score; flags cannibalization. If a GA4 property is configured, it
also weights each topic by the organic conversions its top page already drives
(up to +50%), so topics that convert rank higher; filters_applied.ga4_value_status
reports whether that ran and why (applied / no_ga4_property /
ga4_unreachable / no_conversions). Prioritizes demand you already have;
does not do cold-start keyword research or write the content. Pairs with the
content workflow prompts below. (GA4 weighting v0.7.3) v0.9.0 adds an additive
per-candidate winnability block (banded: striking-distance + topical-
proximity, GSC-personalization tier; existing fields unchanged).
content_brief_data(target_query, competitor_urls?, topic?, site_url?, days?) -
data-wired backing for a content brief: fetches the competitor pages (or your
own GSC-ranking pages as a fallback) and returns the heading union, median
word-count floor, schema types, and entity coverage, plus the 2026 GEO writing
directives and validation rules. The host writes the prose; SEOMonster brings
rules + evidence. Backs the content_brief prompt. (v0.9.0)
maps a content cluster from your own GSC data and surfaces missing subtopics.
Classifies each cluster query into defend / optimize / create / monitor by
demand and best position; the create quadrant is your missing-subtopic list.
Flags cannibalization. GSC-only; honest about the ~47% query anonymization. (v0.9.0)
estimates whether an on-site change moved a page's clicks via
difference-in-differences against a matched control group (never a naked
before/after). Returns an estimated lift with a 95% CI, a three-state verdict
(likely_positive / likely_negative / inconclusive), and a confounders block
that auto-detects the 2025 GSC data-regime breaks (impression bug, num=100) and
downgrades position reliability. Observational, not causal -- a server-side
split test is the only true causal test. GSC-only. (v0.9.0)
AI / GEO citation (3, v0.9.0) - whether the AI answer surfaces reach and cite you.
ai_citation_readiness(url) - is a page structured to be extracted/cited by
LLM answer engines? Leads with a render-blindness check (GPTBot / ClaudeBot /
PerplexityBot fetch but do not run JS, so a client-rendered SPA is invisible to
them), then scores evidence-backed signals (statistics, quotations, cited
sources, no keyword-stuffing). schema.org / FAQ / llms.txt are reported as
informational only -- the 2026 evidence does not support them as AI-citation
drivers, so they are not scored. Free, HTTP-only.
ai_referral_overview(property_id?, site_url?, days?) - first-party AI traffic:
GA4 referral sessions from AI apps (the native ai-assistant channel plus a
configurable source-host regex) and AI-crawler robots coverage (GPTBot,
ClaudeBot, PerplexityBot, ...). Surfaces the ~70% dark-traffic undercount and
keeps AI-Overview clicks (counted as Organic) separate. Free.
sampled brand mention + citation share-of-voice across AI engines
(Perplexity / OpenAI / Anthropic / Gemini APIs + Google AI Overviews via
DataForSEO) for a managed prompt set, vs competitors. N samples/prompt (default
with a 95% CI, share-of-voice, and run-to-run volatility -- NOT an "AI rank"
(single runs are statistically meaningless). Discloses that developer-API output
differs from the logged-in consumer UI and that AIO has no API. Paid +
non-deterministic. Needs at least one engine key and/or DataForSEO.
gsc_keyword_expand(candidates, site_url?, days?, impressions_min?) - you
(the host) brainstorm candidate terms from your winning queries; this grounds
each against your own Search Console data (footprint covered / thin / none) with
a sibling-strength confidence band. "none" = no VISIBLE footprint (GSC hides
~75% of impressions), so net-new terms are scored hypotheses. Free.
serp_adjacency_expand(seeds, include_paa?) - expand seed terms into adjacent
terms. FREE core: Google Autocomplete (no key). Optional People-Also-Ask +
related searches via DataForSEO. Returns per-seed suggestions plus the
aggregated net-new terms; degrades gracefully without a key.
keyword_universe(target_domain?, competitors?, keywords?, limit?) - optional,
paid. Core value: the competitor keyword GAP (DataForSEO Domain Intersection;
no Google equivalent). Optional search volume / difficulty / intent via a
provider chain (DataForSEO, else Google Ads volume-only). External volume is a
degraded directional signal -- a tiebreaker, never a gate.
Google Analytics 4 (7)
ga4_run_report - the workhorse: arbitrary dimensions/metrics/date range,
optional dimension filter and ordering.
ga4_top_landing_pages - top landing pages, organic-only by default.
ga4_traffic_by_channel - sessions/engagement/conversions by channel group.
ga4_organic_search_overview - organic totals plus a day-by-day trend.
ga4_setup_audit(property_id?) - read-only SEO-measurement-readiness audit:
web data stream, key events, data retention, content-group dimensions, and
(v0.7.4) enhanced measurement, internal site search, and Google Signals.
Severity-graded with a benign exception per finding. Uses the GA4 Admin API
over REST (analytics.readonly; no extra dependency). (v0.7.0)
ga4_site_search(days?, limit?) - internal site-search query report (a
direct content-gap signal); honest envelope when no real search terms. (v0.7.1)
psi_analyze - Lighthouse scores, lab Core Web Vitals, and field (CrUX) Core
Web Vitals for a URL. Defaults to the mobile strategy. Field data carries a
field_data_note: Google is deprecating PSI field data, so use crux_snapshot
/ crux_history for durable field metrics.
psi_opportunities(url, strategy?) - the actionable Lighthouse "opportunity"
audits (with estimated savings) plus the SEO-category audits, severity-graded.
Lab data only. An on-page-basics checklist, not a ranking predictor. (v0.7.1)
Cloudflare (13)
cf_list_zones - zones the token can see.
cf_zone_info - status, plan, name servers for a zone.
cf_list_dns - DNS records (read-only); useful for verifying canonical host
and TXT verification records during migrations.
cf_web_analytics - read-only edge Web Analytics (RUM), to compare against
GA4. Cloudflare returns host: null for some sites; pass the site_tag to
look those up explicitly.
cf_purge_cache - purge specific URLs (gated).
cf_purge_cache_all - purge an entire zone (gated + confirm token).
cf_settings_audit(zone?) - read-only audit of SEO-relevant Cloudflare zone
settings (SSL mode, Always-Use-HTTPS, HSTS, Automatic HTTPS Rewrites, Brotli,
cache TTL). Severity-graded with a "verify, not fail" discipline because CF
cannot see the origin; HSTS is never a hard failure. Needs Zone Settings Read
on the token. Each finding carries a machine-readable fix hint (the exact
cf_settings_update setting + recommended value) to chain audit -> fix. (v0.7.1)
write the SEO/crawl/security settings the audit grades (SSL mode, Always-Use-
HTTPS, Automatic HTTPS Rewrites, Brotli, browser cache TTL, HSTS), closing the
audit -> remediate loop. Gated. ssl_mode or any HSTS-raise needs confirm=<zone>
(HSTS-raise also needs acknowledge_hsts_risk=true); validates locally, supports
dry_run, and re-runs the audit so you see the finding clear. Needs Zone
Settings:Edit (vs the audit's Read). (v0.7.10)
cf_list_redirects(zone?) - list a zone's single (dynamic) redirect rules
plus the account's Bulk Redirect lists (read-only). Call before any redirect
write so nothing is clobbered. (v0.7.8; bulk lists added v0.7.9)
cf_create_redirect(source, target, status_code?, ...) - create one edge
redirect (e.g. a 301 for a renamed URL). Gated. Pre-flights the target (no
redirecting to a dead URL), refuses loops/duplicates, supports dry_run. (v0.7.8)
cf_delete_redirect(rule_id, zone?) - remove a single-redirect rule by id
(rollback for cf_create_redirect). Gated. (v0.7.8)
cf_bulk_redirect_upsert(items, list_name, confirm, ...) - create/append many
redirects at once via an account-level Bulk Redirect List (for migrations).
Gated + a confirm token equal to list_name. Validates every item locally
first and rejects the whole batch on any bad item (never half-applies);
supports dry_run. (v0.7.9)
cf_managed_robots(action, zone?, ...) - get / configure / disable
Cloudflare's managed robots.txt and Content-Signals policy (these ride on the
zone's Bot Management config). action="get" reads the current state
(read-only, un-gated). action="configure" sets the managed robots.txt
(managed_robots), the Content-Signals variant (cf_robots_variant:
off / policy_only), and the AI-bot blocking levers (ai_bots_protection,
content_bots_protection, crawler_protection). action="disable" turns the
managed robots.txt and the policy back off. Managed robots.txt and the
Content-Signals policy are mutually exclusive in Cloudflare, so the valid
combinations are managed_robots=true + cf_robots_variant="off" (managed
robots.txt) OR managed_robots=false + cf_robots_variant="policy_only" (the
policy); the tool rejects the invalid combo locally with INVALID_INPUT. A
custom Content-Signal line (e.g. from robots_ai_posture) is not a managed
option - put that in your origin robots.txt. Writes are gated, need
confirm=<zone>, and support dry_run; reads are safe (GET -> overlay -> PUT,
so nothing else in the config is clobbered). Every response carries a caveat
separating the stated-preference signals (Content-Signals, honored only by
adopting crawlers and ignored by Googlebot) from the levers that actually
enforce at the edge. Needs Bot Management:Edit for writes (Read for get).
(v0.8.2)
IndexNow (2, v0.2.0)
indexnow_submit(url) - submit a single URL to Bing, Yandex, Naver, Seznam,
Yep. Complements (does not replace) gsc_request_indexing, which only talks
to Google. Requires SEO_MCP_INDEXNOW_KEY plus a verification file at
https://<your-host>/<key>.txt (see IndexNow setup for the full
key + file format + same-host rules).
indexnow_bulk_submit(urls) - up to 10,000 URLs sharing one host in a
single POST. Mixed-host batches are rejected client-side with
INVALID_INPUT before any network call. The SEO_MCP_INDEXNOW_KEY_LOCATION
env var overrides the default verification-file URL when your CDN rewrites
/key.txt paths.
Technical SEO (8, v0.3.0) - no credentials needed; built-in HTTP client.
inspect_meta(url) - on-page surface in one call: title, meta description,
meta robots, canonical, Open Graph + Twitter Card tags, hreflang, H1 count.
mixed_content_check(url) - parses an HTTPS page and flags any http://
references (img / script / iframe / form action / srcset). No-op for http://.
redirect_chain_audit(url, max_redirects=10) - walks the chain hop by hop.
Flags long chains, protocol downgrades, loops, non-2xx terminus.
robots_txt_validate(site_url, probes?) - parses robots.txt (per-group
rules + sitemaps + Content-Signals), optionally verdicts (user_agent, url)
probes using RFC 9309 longest-match (matches what Google + Bing actually do,
not stdlib's first-match). Also detects a stale edge-cached robots.txt
(cache-bust comparison; re-parses from the fresh content) and a Cloudflare
Managed robots.txt / Content-Signals policy overriding your origin -
catching false-clean robots on migrated/CF-fronted sites. (v0.8.0)
sitemap_validate(sitemap_url) - validates a sitemap or sitemap-index XML,
counts entries, flags oversize + cross-host + missing lastmod. .gz
transparent.
sitemap_health(sitemap_url, sample_size=25) - sample-HEAD audit. Status
histogram + first non-2xx examples.
robots_ai_posture(goal?, sitemap_url?) - deterministic, offline advisor for
the Content-Signals levers (search / ai-input / ai-train). Takes a
business goal (content_authority default / maximize_visibility /
protect_ip), recommends a posture with a plain-language rationale, lays out
the trade-off alternatives, and emits a ready-to-apply artifact: the
Content-Signal: directive line plus a full suggested robots.txt. No network,
no writes. Every response carries the mandatory caveat that Content-Signal is
honored only by adopting crawlers, is ignored by Googlebot, and is not a
ranking factor. (v0.8.1)
Chrome UX Report (2)
crux_history(url? | origin?, form_factor?, metrics?) - 25 weeks of p75
Core Web Vitals via the CrUX History API. Reuses PSI_API_KEY; works
anonymously at a tighter rate limit when no key is configured.
crux_snapshot(url? | origin?, form_factor?) - the current p75 Core Web
Vitals (point-in-time, vs the history). Each metric reports a category
(GOOD / NEEDS_IMPROVEMENT / POOR); the rolled-up rating is overall_category.
Time metrics use p75_ms; the unitless CLS uses p75. Small origins return
a no_data envelope. (v0.7.1)
Structured data + cross-site + on-page (7) - no new credentials (the v0.9 SERP auto-fetch is optional).
inspect_schema(url) - extract every JSON-LD block from a page; report
the schema.org @type counts and a sample entity per type.
validate_schema(url, types?) - verdict each JSON-LD entity against the
Google Rich Results required-field set. Covers Article, NewsArticle,
BlogPosting, Product, FAQPage, BreadcrumbList, Organization, LocalBusiness,
Event, Review, Recipe. Per-entity verdict plus missing_required and
missing_recommended lists.
hreflang_consistency_check(urls) - cross-page hreflang audit on a
user-supplied URL set. Flags missing reciprocity, broken hreflang
targets, duplicate hreflang on one page, missing self-link, missing
x-default when there are 3+ language variants.
internal_link_graph(start_url, max_depth=2, max_pages=50) - small
BFS crawl within the same host. Per-page in-degree + out-degree,
orphan pages, broken internal links, depth distribution. Hard caps
(max_depth <= 4, max_pages <= 200) so a misuse never melts the host.
lighthouse_budget(url, budget) - wraps psi_analyze and verdicts
the results against a budget dict, e.g.
{performance: 80, LCP_ms: 2500, CLS: 0.1}. Per-metric pass/fail and
an overall verdict. Useful as a CI / pre-deploy gate inside an LLM
session. Reuses PSI_API_KEY.
recommends specific source->target internal links from high-in-degree pages
to GSC striking-distance pages (default position 8-20 with real impressions),
with anchor text. Ranks sources by lexical relevance + internal authority, skips
pages that already link the target, balances anchor text, and never suggests
nofollow. Built on internal_link_graph + GSC. Free. (v0.9.0)
onpage_serp_gap(target_url, query?, competitor_urls?, max_competitors?) - the
headings, entities, and schema the top SERP results have that a target page
lacks, turned into on-page actions. FREE with caller-supplied competitor_urls;
optional DataForSEO SERP auto-fetch by query, which also returns winnability
signals (serp_composition AI-Overview / UGC zero-click risk) and, with Open
PageRank, competitor domain authority. Surfaces information gain, not just
parity. Boilerplate/nav headings are filtered out (pattern-class chrome filter). (v0.9.0; F6 fix v0.9.1, F1 generalized v0.9.2)
Every tool's tools/list entry carries the MCP standard annotations
(readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so MCP
hosts can decide what to auto-approve and what to confirm.
Workflow prompts
The server publishes thirteen named MCP prompts (via prompts/list /
prompts/get) that chain the granular tools into common SEO workflows. Hosts
that surface prompts (Claude Desktop's slash menu, Cursor's command palette,
Cline's prompt picker) advertise them automatically.
Why prompts and not megatools: composability. A failed step inside a megatool
poisons the megatool's envelope and the host loses the ability to retry just
the failing leg. Prompts hand the host a recipe; each step's envelope arrives
intact at the LLM.
Install
SEOMonster ships two install paths, both fully local:
.mcpb bundle for Claude Desktop. One-click install, GUI form for
credentials, secret-typed inputs stored in the OS keychain. Recommended for
most users.
uvx for Cursor, Cline, Codex, and Claude Desktop power users who prefer
to hand-edit MCP config files.
Both paths run the same Python package (seo_mcp) and expose the same
52-tool surface. The difference is only how the host launches the server
and how it collects credentials.
Claude Desktop (recommended): .mcpb bundle
Three short steps. The OAuth consent is run once from a terminal (the GUI
flow inside Claude Desktop's MCP subprocess times out before a real user can
finish; see Why pre-flight auth? below).
1. Install the bundle. Download
seo-monster-0.2.0.mcpb
from GitHub releases (or, when listed, from the Claude
Directory) and double-click it. Claude Desktop
verifies the bundle, runs uv to materialize the Python environment, and
shows a configuration form:
Field
Type
Required
Notes
Google OAuth Client Secrets
file picker
yes
Desktop-app client-secrets JSON from Google Cloud Console.
Google OAuth Token Cache Path
string
yes
Defaults to ~/.config/seo-monster/token.json. Written on consent.
GSC Default Property
string
no
e.g. sc-domain:example.com or https://www.example.com/.
GA4 Default Property ID
string
no
properties/123456789 or bare 123456789.
PageSpeed Insights API Key
string, secret
no
Stored in the OS keychain. Strongly recommended (why?).
Cloudflare API Token
string, secret
no
Stored in the OS keychain. Required only for the Cloudflare tools.
Cloudflare Default Zone
string
no
e.g. example.com.
IndexNow Key
string, secret
no
Required only for IndexNow tools. Any 8-128 hex string you generate.
IndexNow Key File URL
string
no
Override the default verification location (https://<host>/<key>.txt).
Fill the fields, click Save, then toggle the extension on. Quit Claude
Desktop completely (⌘Q on macOS) and reopen.
2. Run the one-time OAuth consent from a terminal. Before using any
Google-backed tool, run:
uvx seo-monster auth
A browser opens. Approve the requested scopes. The command writes
token.json to the path you configured (default ~/.config/seo-monster/token.json)
with 0600 permissions, then exits. This step is the recommended pattern; it
sidesteps the timeout that Claude Desktop imposes on every tool call.
3. Start a new chat in Claude Desktop and use the tools. Click the 🔧
tools icon in the input box; you should see 52 SEOMonster tools. Try
system_status first to verify everything is configured.
Why pre-flight auth?
The OAuth installed-app flow opens a local browser and waits for the user to
finish the consent screen. Inside Claude Desktop, MCP servers are launched as
subprocesses whose tool calls have a ~30-60 second timeout. Real users do not
complete browser consent that fast, so the originating call times out, and
since every Google tool retries the flow until a token exists, every call
times out in turn. Running uvx seo-monster auth once from a terminal puts
the token on disk; from that point on, Claude Desktop's MCP server just reads
the cached token and silently refreshes it as needed.
uvx for Cursor, Cline, Codex (and Claude Desktop power users)
uvx runs the published PyPI package seo-monster in an ephemeral
environment. Add the snippet for your host below, using the absolute path
to uvx (find it with which uvx; GUI hosts do not read your shell profile).
Cursor (~/.cursor/mcp.json or project .cursor/mcp.json)
If you prefer to hand-edit claude_desktop_config.json instead of using the
.mcpb bundle, the same snippet shape as Cursor above works.
Auth
The four services authenticate independently. Configure only the ones you use;
a tool for an unconfigured service returns a clear AUTH_MISSING error rather
than failing the server.
Quick setup (recommended): seo-monster setup
Run seo-monster setup once from a terminal. It interactively collects your
Cloudflare token, PageSpeed Insights key, IndexNow key, and the default GSC and
GA4 properties, validates what it can against the live APIs, and writes them to
~/.config/seo-mcp/config.toml with 0600 permissions. Your MCP host config
then needs no secrets in it:
{ "command": "uvx", "args": ["seo-monster"] }
Two things setup does not do, by design:
Google OAuth still uses the separate one-time browser step. After setup,
run seo-monster auth to complete Google consent (see the next section).
It never overrides environment variables. Anything set in your host's env
block still wins over the config file, so CI and Docker keep using env vars.
setup is re-runnable: existing values are shown as defaults and kept when you
leave a field blank. The sections below document the per-service env vars, which
are what setup writes for you and what CI pipelines can set directly.
Google (Search Console + Analytics 4) - OAuth, recommended
This is the lower-friction path: no Cloud service account, no per-property email
grants.
In the Google Cloud Console, create (or
pick) a project and enable the APIs you will use:
Search Console API
Indexing API (for gsc_request_indexing)
Google Analytics Data API (for the GA4 tools)
PageSpeed Insights API (only if you want a PSI key; see below)
Create an OAuth client of type Desktop app and download the client-secrets
JSON.
Point the server at it and at a writable token path:
SEO_MCP_GOOGLE_OAUTH_CLIENT = path to the client-secrets JSON
SEO_MCP_GOOGLE_TOKEN = a writable path where the token will be cached
One-time: run uvx seo-monster auth from a terminal. A browser opens;
approve the scopes. The command writes token.json (0600) and exits.
Subsequent runs (server-side) refresh the token silently. The server
never opens a browser; if the cached token is missing, tools return
AUTH_MISSING pointing back at the auth command.
The signed-in Google account must have access to the Search Console properties
and GA4 properties you query.
Token-cache hardening. The cached token is refresh-capable and equivalent
to a long-lived credential for the requested scopes. The server writes it with
0600 and its parent directory with 0700. Keep SEO_MCP_GOOGLE_TOKEN under
a directory you control (e.g. ~/.config/seo-monster/) and do not put it on a
shared filesystem.
Google - service account (advanced, headless)
For fully headless or server deployments where a browser is not available:
Create a service account and download its JSON key.
Set SEO_MCP_GOOGLE_CREDENTIALS (or the standard
GOOGLE_APPLICATION_CREDENTIALS) to the key path.
Grant the service-account email access on each property:
Search Console: add it as a user on the property.
GA4: add it as a Viewer on the property.
If both OAuth and a service account are configured, OAuth is used.
Coverage note. The OAuth installed-app path is exercised in our
validation pass and in production-style smoke tests. The service-account
path is documented but not independently validated against a live Cloud
project. If you hit issues on the SA path, please open an issue.
Scopes (minimal vs full)
The default consent requests the scopes needed for every tool, including the two
writes:
Capability
Scope
GSC read
webmasters (covers readonly)
GSC sitemap submit
webmasters
GSC indexing request
indexing
GA4 reporting
analytics.readonly
If you only want reads, you can consent to a narrower set
(webmasters.readonly + analytics.readonly) and simply not call
gsc_submit_sitemap / gsc_request_indexing; calling a write tool without its
scope returns SCOPE_INSUFFICIENT with remediation, never a crash.
PageSpeed Insights
PSI works without a key in principle, but in practice the anonymous quota is
shared across every caller without a key and is frequently exhausted: a
single psi_analyze call against the anonymous endpoint often returns
RATE_LIMITED. Treat the anonymous mode as a fallback, not the steady
state.
To get reliable PSI access:
In Cloud Console, enable the PageSpeed Insights API.
Create an API key (Credentials > Create credentials > API key). It
takes a minute. The key is free.
Set PSI_API_KEY (or use the field in the .mcpb configuration form).
The PSI API only accepts the key as a URL query parameter (not a header), so
treat PSI keys as low-sensitivity. Scope the key to the PageSpeed Insights
API only and attach no other GCP roles.
Cloudflare
Create an API token at
dash.cloudflare.com/profile/api-tokens
and set CF_API_TOKEN (and optionally CF_ZONE for a default zone). Grant only
the permissions you need:
Permission
Needed for
Zone: Zone:Read
cf_list_zones, cf_zone_info
Zone: DNS:Read
cf_list_dns
Account: Account Analytics:Read
cf_web_analytics
Zone: Cache Purge:Purge
cf_purge_cache, cf_purge_cache_all (only if you enable destructive mode)
Zone: Single Redirect:Edit
cf_create_redirect, cf_delete_redirect (only if you enable destructive mode); cf_list_redirects reads with it
Zone: Zone Settings:Edit
cf_settings_update (only if you enable destructive mode); cf_settings_audit only needs Zone Settings Read
cf_bulk_redirect_upsert (only if you enable destructive mode)
IndexNow
IndexNow notifies Bing, Yandex, Naver, Seznam, and Yep when a URL is created
or updated. Google does not participate, so the IndexNow tools complement
rather than replace gsc_request_indexing.
One-time setup
Generate a key. Any 8-128 character string of letters, digits, or
hyphens (a-z, A-Z, 0-9, -) per the IndexNow spec. Common patterns:
a 32-char lowercase hex string (e.g. python -c "import secrets; print(secrets.token_hex(16))") or any random alphanumeric of similar
length. Treat it like an API key; do not commit it.
Configure SEOMonster by setting SEO_MCP_INDEXNOW_KEY to that string
(or use the .mcpb configuration form; the field is marked sensitive and
lands in the OS keychain).
Host the verification file at https://<your-host>/<key>.txt. The
file body MUST be exactly the key string with no trailing newline, no
BOM, no extra whitespace, no HTML wrapper. The Content-Type should be
text/plain. Confirm with curl -i https://<your-host>/<key>.txt before
moving on; the response body must be byte-identical to the key.
(Optional) Set SEO_MCP_INDEXNOW_KEY_LOCATION if the verification
file lives at a non-standard URL (some CDNs rewrite /key.txt paths).
The default location is https://<host>/<key>.txt derived from the URLs
you submit, so you usually do not need this.
Same-host constraint
Every URL submitted in one indexnow_submit or indexnow_bulk_submit call
must share the same host as the verification file. Mixed-host batches are
rejected by IndexNow with HTTP 422; indexnow_bulk_submit enforces this
client-side and returns INVALID_INPUT before any network call when it
detects mixed hosts.
If you have multiple hosts, host a verification file per host and either
make separate calls per host or override SEO_MCP_INDEXNOW_KEY_LOCATION
per call (the tool does not currently expose per-call override; set
distinct env values per session).
Common errors
Symptom
Likely cause
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
INVALID_INPUT from indexnow_bulk_submit mentioning mixed hosts
URL list spans multiple hosts; split into per-host batches
RATE_LIMITED
Hit IndexNow's per-host rate cap. Wait before retrying
Verify your setup
After configuring, call system_status to see what is detected. Call it with
{"probe": true} to make one cheap live request per configured service and
confirm the credentials actually work (GSC lists properties, GA4 runs a 1-row
report against the default property, Cloudflare lists one zone, PSI pings the
endpoint). With probe off (the default) it does a config-only check and makes
no network calls.
Destructive mode
Cache purges affect every visitor, so they are off by default. Set
SEO_MCP_ALLOW_DESTRUCTIVE=true to enable cf_purge_cache and
cf_purge_cache_all. While off, those tools return DESTRUCTIVE_DISABLED and
make no network call.
cf_purge_cache_all (purge the whole zone) carries an extra safeguard: it
requires a confirm argument equal to the resolved zone hostname. A missing or
mismatched confirm returns CONFIRM_REQUIRED and issues no purge.
The two GSC writes (gsc_submit_sitemap, gsc_request_indexing) are not
gated; they are routine, low-blast-radius SEO tasks.
Configuration
Resolution is environment-first, with a TOML file fallback. Environment always
wins. The config file is normally written for you by seo-monster setup (with
0600 permissions); you can also write it by hand or set the env vars below.
Env var
Service
Purpose
SEO_MCP_GOOGLE_OAUTH_CLIENT
Google
OAuth client-secrets JSON path (recommended).
SEO_MCP_GOOGLE_TOKEN
Google
Writable cached-token path (OAuth).
SEO_MCP_GOOGLE_CREDENTIALS
Google
Service-account key path (alternative).
GOOGLE_APPLICATION_CREDENTIALS
Google
Standard service-account fallback.
SEO_MCP_GSC_DEFAULT_SITE
GSC
Default property, e.g. sc-domain:example.com.
SEO_MCP_GA4_PROPERTY_ID
GA4
Default property, e.g. properties/123456789.
SEO_MCP_DATA_STATE
GSC
all (default) or final.
PSI_API_KEY
PSI
PageSpeed Insights API key (optional).
CF_API_TOKEN
CF
Cloudflare API token.
CF_ZONE
CF
Default zone hostname.
SEO_MCP_INDEXNOW_KEY
IndexNow
Shared key for the IndexNow tools (sensitive).
SEO_MCP_INDEXNOW_KEY_LOCATION
IndexNow
Override default key-file URL (optional).
SEO_MCP_ALLOW_DESTRUCTIVE
all
true enables cache-purge tools. Default off.
SEO_MCP_CONFIG
all
Path to the TOML config file.
DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD
DataForSEO
Optional (v0.9): SERP/PAA, keyword volume/difficulty/intent, competitor gap, Google AIO.
A Google Cloud API is not enabled; details has the activation URL.
UPSTREAM_ERROR
Any other non-2xx from an upstream API.
Development
git clone https://github.com/avansaber/seo-monster
cd seo-monster
uv venv && uv pip install -e ".[dev]"
uv run pytest # offline test suite
uv run seo-monster # run the server over stdio
uv run seo-monster auth # one-time OAuth consent (or `uv run seo-mcp auth`)
The package exposes two console-script aliases: seo-monster (canonical,
matches the PyPI distribution) and seo-mcp (a v0.1.x dev alias kept for
back-compat). Both invoke the same entry point. As of v0.2.0, invoking the
server via seo-mcp emits a one-line stderr deprecation notice; nothing on
stdout, so the MCP protocol channel is unaffected. Production configs should
use seo-monster; the alias will be removed in a future major release.
Tests are fully offline: they mock at the client layer, so no network and no
credentials are needed to run them.
Server identity note. Some MCP host UIs display the server name as
seo-mcp and the version as the mcp SDK version (e.g. 1.27.1). The
server-name string is the value we passed to Server("seo-mcp") and is kept
stable for back-compat; the version readout is a quirk of the SDK
(create_initialization_options() does not propagate the package version).
The package's real version is in pyproject.toml and seo_mcp.__version__.
Changelog
Release-by-release notes, including the validation checks each version's
external testing pass should cover, live in CHANGELOG.md.
Privacy
SEOMonster runs entirely on your machine and talks only to the upstream APIs
you configure. The maintainers do not see any of your data, credentials,
queries, or tool calls. See PRIVACY.md for the full statement.
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Seo Monster?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Seo Monster necesita una clave de API?
El publicador indica estas variables de entorno: SEO_MCP_GOOGLE_OAUTH_CLIENT, SEO_MCP_GOOGLE_TOKEN, SEO_MCP_GSC_DEFAULT_SITE, SEO_MCP_GA4_PROPERTY_ID, PSI_API_KEY, CF_API_TOKEN, CF_ZONE, SEO_MCP_INDEXNOW_KEY, SEO_MCP_INDEXNOW_KEY_LOCATION, SEO_MCP_ALLOW_DESTRUCTIVE, SEO_MCP_SERP_PROVIDER, SERPBASE_API_KEY, DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD, OPENPAGERANK_API_KEY, PERPLEXITY_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_ADS_CUSTOMER_ID.
¿Qué transporte usa Seo Monster?
Seo Monster se ejecuta localmente por stdio.
¿Cuándo se comprobó Seo Monster por última vez?
Última comprobación: 2026-11-17. Local-first SEO MCP: track AI citations, Search Console, GA4, PageSpeed, Cloudflare, IndexNow, CrUX.