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.

For the uvx route, install Python 3.11 or later and uv first. Check that uvx --version works in a terminal. A desktop app may need the full executable path because it does not use your shell's startup configuration.

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.

Setup reference

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.

Setup reference

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.

Setup reference

Cline

Add a stdio server in the MCP settings used by Cline.

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

Use the absolute path to uvx if the editor cannot find it. Start with tool approvals enabled, then call system_status to check the connection.

Setup reference

Codex

Add SEOmonster with the Codex CLI, then inspect the configured server.

codex mcp add seomonster -- uvx seo-monster
codex mcp list

For a GUI host that cannot find uvx, use its absolute executable path in the stdio configuration. In a new session, call system_status before choosing a Google report. Google sign-in is the separate SEOmonster auth step below.

Setup reference

Authenticate.

Complete Google sign-in once in a terminal, then point the assistant at the same token path. Never paste a token or API key into chat. A successful MCP connection and access to the intended Google property are separate checks.

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 samples use configured Perplexity, OpenAI, Anthropic or Gemini APIs; Google AI Overviews uses its separate research-provider path. Keep those samples distinct from consumer-app tests. Optional keyword and authority research uses DataForSEO and Open PageRank. Configure only the services you need; 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 can use the weekly_review prompt to organise the reports. Ask it to state the property, exact inclusive dates and whether the Search Console data is final. Review the evidence before choosing any change.

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