SEO MCP server for Claude, Codex, and Cursor

The SEO MCP server runs as a local process on your computer and gives Claude Code, Claude Desktop, Codex, or Cursor the same structured reports as the CLI. The installer points your client at the installed CLI and sends tool calls over standard input and output. It does not fetch the package from npm when the client starts.

MCP supplies the tools. The packaged SEO skills supply the report-specific instructions that help an agent choose the right tool, read the evidence, and verify a change. Install both for the best agent results.

There is no hosted SEO MCP endpoint in this release. Google tokens, project profiles, caches, and saved crawls remain in the local SEO config directory.

Set up the CLI before connecting an agent

Install the CLI, run the human setup, and confirm the main report works:

npm i -g seo
seo start
seo report

This separates Google or property-selection problems from MCP configuration problems. Node 22 or newer must remain available when your client starts the server.

Connect a client without hand-editing its config

With seo installed globally, run:

seo mcp install

The interactive flow detects supported clients and lets you choose one or more. It preserves unrelated settings, creates a timestamped backup before it changes a JSON config, and refuses to replace an existing seo server that it does not manage.

For scripts or a specific client, pass an explicit flag:

seo mcp install --codex --json
seo mcp install --claude-code --json
seo mcp install --claude-desktop --json
seo mcp install --cursor --json

--json never prompts. Use --all only when you really want every detected client updated.

Connect Codex

seo mcp install --codex
codex mcp get seo

The installer uses the native Codex command to update its TOML config. Codex CLI, the desktop app, and its IDE extension share that MCP configuration on the same host. OpenAI documents this behavior in the Codex MCP guide.

Connect Claude Code

seo mcp install --claude-code
claude mcp get seo

Anthropic’s Claude Code MCP documentation covers scopes, server management, and the /mcp status view.

Connect Claude Desktop

seo mcp install --claude-desktop

Close and reopen Claude Desktop after installation. Claude Desktop and Claude Code use different configuration files, so installing one does not configure the other.

Local developer-defined MCP servers can be restricted by organization policy. Anthropic’s Claude Desktop local MCP guide covers the current desktop controls and troubleshooting steps.

Connect Cursor

seo mcp install --cursor

Restart Cursor, open its MCP settings, and check that the seo server is enabled. The installer edits Cursor’s user MCP config and leaves other servers alone.

Cursor changes its settings UI more often than anyone enjoys. The generated config is the durable part. If the server is missing from the UI, run the test below and inspect the path printed by the installer.

Check that the server can start

seo mcp serve --test

Test mode constructs the server, prints a success message, and exits. A normal seo mcp serve waits for an MCP client on stdin and stdout, so running it in a terminal will appear to sit there doing nothing. That is expected.

If the client cannot start it, check:

node --version
seo mcp serve --test
seo doctor
seo auth status

A missing Node runtime, broken global install, expired Google login, and wrong project are separate failures. Check them in that order.

Keep tool selection fast with three MCP tools

The server keeps discovery small:

1. seo_list_reports finds report ids, optionally by category.
2. seo_describe_report returns one report’s JSON Schema.
3. seo_run_report runs that report with validated parameters.

Ask the agent to choose the smallest report that answers the question. It should describe the selected report before passing parameters and inspect the result’s status, warnings, limits, and skipped sections before recommending work.

The agent workflow guide shows how to keep those calls bounded. Focused skills add the SEO context that tells an agent why a report matters and how to act on its result.

Remove the managed server entry

seo mcp install --uninstall --codex
seo mcp install --uninstall --claude-code
seo mcp install --uninstall --claude-desktop
seo mcp install --uninstall --cursor

Uninstall removes only the managed seo entry. It refuses to remove a custom server with the same name.