Docs

Install SEOmonster in your AI assistant.

The fastest path: one command, one OAuth flow, one first prompt. Pick your AI host below.

Install

One-command install in your AI assistant.

Authenticate

Google OAuth for Search Console and GA4. Other surfaces use API keys.

First prompt

Run weekly_review against your real Search Console property.

Tool reference

Environment variables, error codes, and the full 70-tool reference.

Workflow prompts

13 workflow prompts: what each one chains and when to use it.

Troubleshooting

The failures people actually hit, and the fix for each.

Install in your AI host.

SEOmonster ships as a Python package on PyPI and a one-click bundle for Claude Desktop. About three minutes to install in any supported host.

Claude Desktop

Download the .mcpb bundle from the GitHub Releases page and double-click to install.

open https://github.com/avansaber/seo-monster/releases/latest

One-click install. No terminal needed for the install step itself. You will still need to complete OAuth from a terminal for Google-backed tools.

Claude Code

Add SEOmonster as an MCP server in one command.

claude mcp add seo-monster -- uvx seo-monster

Restart Claude Code. SEOmonster appears in the MCP-tools palette.

Cursor

Add the entry to ~/.cursor/mcp.json.

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

Restart Cursor. Look for "seo-monster" in the MCP indicator.

Cline / Codex

Same stdio config pattern. Drop the JSON into the host's MCP config file.

See your host's MCP documentation for the exact config path.

SEOmonster is host-agnostic at the protocol level.

Authenticate.

Each data surface uses its own auth. Run only the auth you need.

Google Search Console + GA4 (OAuth)

From a terminal:

uvx seo-monster auth

Token caches at ~/.config/seo-monster/token.json with mode 0600.

PageSpeed Insights + Chrome UX

Get a free API key from Google Cloud Console, set the env var:

export PSI_API_KEY="your-key"

CrUX history works without a key in anonymous mode at lower rate.

Cloudflare

Create a token in Cloudflare dashboard with the scopes you need:

export CF_API_TOKEN="your-token"

IndexNow

Pick any 32-character hex string, set it, host the verification file:

export SEO_MCP_INDEXNOW_KEY="your-32-char-hex"

AI engines + external keyword data (optional)

AI citation tracking (ChatGPT, Perplexity, Gemini, Google AI Overviews) and the competitor keyword gap use optional provider keys: an AI engine key, plus DataForSEO and Open PageRank for SERP and authority data. Add only what you have; the core SEO tools never require them. Exact variable names are in the reference below.

Prefer a guided setup? uvx seo-monster setup writes the config file for you. Then ask your assistant to run system_status with probe set to true: it makes one cheap live request per configured service and tells you which credentials actually work.

Run your first prompt.

In your AI assistant, ask:

Run my weekly SEO review for the last 14 days
on sc-domain:example.com

The host calls the weekly_review prompt. The server chains four tools and returns a 200-word summary in your chat. Total time: about 6 seconds.

Or, with no auth at all, ask:

Run inspect_meta on https://www.anthropic.com

Returns title, meta description, OG tags, canonical. The technical-SEO and structured-data tools work this way, no credentials required.

Troubleshooting.

The problems people actually report, with the fix for each. Start with system_status and probe set to true: most setup problems show up there first.

The server fails to start, or your assistant reports a closed connection

Upgrade to v0.9.3 or later. Releases before it allowed the MCP SDK 2.0 released on 28 July 2026, which removed the registration API the server used, so fresh installs through uvx, pip or the one-click editor buttons broke before the handshake. v0.9.3 pins the SDK below 2. Claude Desktop .mcpb installs were not affected, because the bundle ships a lock file.

A Google tool asks you to authenticate again after upgrading to v0.9.3

Run uvx seo-monster auth again. v0.9.3 fixed the OAuth scope check so it now reads the scopes actually granted in your token file. A token that never had a needed scope is now caught up front instead of failing later.

SERVICE_DISABLED from a Google tool

The matching API is not enabled in your Google Cloud project. Open the activation link included in the error details, enable the API, wait a minute, and retry.

DESTRUCTIVE_DISABLED or CONFIRM_REQUIRED from a Cloudflare tool

Working as designed. Set SEO_MCP_ALLOW_DESTRUCTIVE=true to allow the Cloudflare write tools, and for a whole-zone purge pass the zone hostname as confirm. Sitemap submission and indexing requests are never gated.

AUTH_INVALID from indexnow_submit

The engines could not fetch https://your-host/your-key.txt. The file must return HTTP 200 as text/plain, and its body must be exactly the key, with no trailing newline. Check it with curl before submitting again.

INVALID_INPUT from indexnow_bulk_submit mentioning mixed hosts

Every URL in one call must share the host of the verification file. Split the list into one batch per host.

Reference.

Configuration is environment first, with a TOML file as fallback; the environment always wins. Every tool returns the same envelope, so a failure always carries one of the error codes below.

Environment variables

Variable	Service	What it does
`SEO_MCP_GOOGLE_OAUTH_CLIENT`	Google	OAuth client-secrets JSON path (recommended).
`SEO_MCP_GOOGLE_TOKEN`	Google	Writable cached-token path for OAuth.
`SEO_MCP_GOOGLE_CREDENTIALS`	Google	Service-account key path (alternative to OAuth).
`SEO_MCP_GSC_DEFAULT_SITE`	Search Console	Default property, for example sc-domain:example.com.
`SEO_MCP_DATA_STATE`	Search Console	all (default, includes fresh data) or final.
`PSI_API_KEY`	PageSpeed	PageSpeed Insights API key (optional).
`CF_API_TOKEN`	Cloudflare	Cloudflare API token.
`CF_ZONE`	Cloudflare	Default zone hostname.
`SEO_MCP_INDEXNOW_KEY`	IndexNow	Shared key for the IndexNow tools (sensitive).
`SEO_MCP_ALLOW_DESTRUCTIVE`	All	true enables the Cloudflare write tools. Off by default.
`SEO_MCP_CONFIG`	All	Path to the TOML config file. Environment always wins over it.
`DATAFORSEO_LOGIN, DATAFORSEO_PASSWORD`	Optional	SERP, People Also Ask, keyword volume and the competitor gap.
`OPENPAGERANK_API_KEY`	Optional	Free competitor domain authority.
`PERPLEXITY_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY`	Optional	Engines for ai_citation_track. Any subset works.

Error codes

Code	Meaning
`AUTH_MISSING`	No credential is configured for that service.
`AUTH_INVALID`	A credential is present but was rejected (401 or 403, a bad key, or an expired token).
`SCOPE_INSUFFICIENT`	The token lacks the scope this tool needs.
`DESTRUCTIVE_DISABLED`	A Cloudflare write tool was called with destructive mode off. Nothing was sent.
`CONFIRM_REQUIRED`	A whole-zone action was called without the zone name as confirmation. Nothing was sent.
`NOT_FOUND`	The site, property, zone or record is missing or not visible to your credentials.
`INVALID_INPUT`	An argument failed validation, such as a bad date or a missing required value.
`RATE_LIMITED`	The upstream API returned 429. Wait before retrying.
`SERVICE_DISABLED`	A Google Cloud API is not enabled. The error details carry the activation link.
`UPSTREAM_ERROR`	Any other non-2xx response from an upstream API.

Per-tool parameters and annotations for all 70 tools live in the README on GitHub.

README on GitHub ↗

Per-tool parameters, annotations, result envelopes.

CHANGELOG ↗

Every release back to v0.1.0.

PRIVACY.md ↗

Data flow for the server itself.

GitHub Issues ↗

Bug reports, feature requests, support.

SEOmonster v0.9.3 is MIT licensed open-source software, built and run by AvanSaber.

github.com/avansaber/seo-monster SEOmonster privacy SEOmonster terms