RoamSEO

Hosted SEO MCP server: keyword research, site audits, backlinks, rank tracking and AI-answer visibility for Claude, ChatGPT and Cursor. OAuth sign-in, from 10 USD/month.

Hosted MCP Server

npx add-mcp 'https://app.roamseo.com/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

MCP is how an AI client talks to RoamSEO. Through the RoamSEO MCP server, a compatible client gains tools for keyword research, SERP inspection, domain research, a backlink overview, competitive search intelligence and local business research. It can also work with saved keywords, rank tracking and the shared project context, and read Google Search Console performance and URL inspection data.

Quick start

In ChatGPT and Claude you add RoamSEO as a custom connector with the server URL below. The buttons open the step-by-step guides:

Every other client connects to the hosted server at this address:

https://app.roamseo.com/mcp

On first use you are redirected to sign in to RoamSEO and approve access. From then on the client may call RoamSEO tools within the project context and account scopes you agreed to. Machines with no browser, such as CI runners, should connect with an API key.

Useful links:

  • Agent setup in RoamSEO always has the latest setup screen and an endpoint you can copy.
  • Agent setup in these docs covers setup prompts, plugin commands and updating skills.
  • The free SEO tools work without an account, if you want to try things first.

Choose your client

ClientHow to connect
ChatGPT on the web or desktopChatGPT guide: a custom MCP server
Claude on the web, desktop or mobile, Claude Code, Claude CoworkClaude guide: a custom connector, or the plugin
Codex in the ChatGPT desktop app or the CLICodex guide: the plugin, or MCP only
CursorBelow
HermesAgent setup: Hermes
Any other MCP clientAdd the server URL above and approve the login, or connect with an API key

Cursor

  1. In Cursor, go to Settings -> Tools & Integrations -> MCP Tools.
  2. Choose New MCP Server, which opens the file mcp.json.
  3. Paste this entry:
{
  "mcpServers": {
    "roamseo": {
      "url": "https://app.roamseo.com/mcp"
    }
  }
}
  1. A RoamSEO login prompt follows. Approve it.

Connect with an API key

OAuth needs a browser. Where that is awkward (CI, headless servers, certain clients), authenticate with an API key instead. A key is personal. Whatever an agent does with it is done as you, inside the workspace that was active at the moment the key was created.

To get one, go to Settings -> API keys in the RoamSEO app and create a key. Copy it immediately, because the app displays it only once.

Claude Code:

claude mcp add --transport http --scope user roamseo https://app.roamseo.com/mcp --header "Authorization: Bearer oseo_YOUR_KEY"

Cursor. Extend the server entry in mcp.json with a headers block:

{
  "mcpServers": {
    "roamseo": {
      "url": "https://app.roamseo.com/mcp",
      "headers": {
        "Authorization": "Bearer oseo_YOUR_KEY"
      }
    }
  }
}

Codex CLI. Store the key in an environment variable, then point Codex at that variable:

export ROAMSEO_API_KEY=oseo_YOUR_KEY
codex mcp add roamseo --url https://app.roamseo.com/mcp --bearer-token-env-var ROAMSEO_API_KEY

Anything else. If the client lets you set HTTP headers, send either Authorization: Bearer oseo_YOUR_KEY or x-api-key: oseo_YOUR_KEY.

Workspaces and revoking access

Both OAuth connections and API keys belong to one workspace: the one active when you approved the connection or generated the key.

You want toDo this
Use an agent in a second workspaceConnect once more and select that workspace on the authorization page.
Make a key for a second workspaceSwitch to that workspace in the app first, then create the key.
Cut off an agentIn Settings, find Connected agents and press Disconnect.
Cancel a keyIn the same Settings page, find API keys and press Revoke key.

After being disconnected, an agent must go through sign-in again before RoamSEO accepts its calls.

Troubleshooting

SymptomFix
The client won't connectCompare the server URL character by character with https://app.roamseo.com/mcp.
Authorization failsRemove the RoamSEO server from the client, add it back and go through the login again.
The agent says it has no projectHave it list RoamSEO projects first, then pass the project ID it gets back in the calls that follow.

Errors tied to one client are covered in that client's own guide: ChatGPT, Claude and Codex.

Available tools

The full list of what an agent can do, with a note on which tools spend credits, is on the RoamSEO MCP tools page.

What to do after setup

MCP only supplies data. To tell your agent what to do with that data, set up RoamSEO Agent Skills next. Each skill is a separate SKILL.md file describing one SEO job.

A broad request like "do SEO" gives poor results. Pick a single, narrow workflow to begin with:

If you want toUse
Record goals, positioning, competitors and key pages for all skills to reuseSEO project setup
Get guidance because you're new to SEO or unsure where to beginSEO coach
Collect questions and cited sources before deciding what to trackAI Prompt Research
Learn why competitors show up in AI answers and what to changeAI Visibility Audit
Find keyword opportunitieskeyword research
Survey a market before picking competitors or pagescompetitive landscape
Examine a single competitorcompetitor analysis
Group keywords into pageskeyword clustering
Build an outreach list for a linkable assetlink prospecting

Supported engines, research coverage and costs for AI features are explained in the AI Visibility guide.