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
| Client | How to connect |
|---|---|
| ChatGPT on the web or desktop | ChatGPT guide: a custom MCP server |
| Claude on the web, desktop or mobile, Claude Code, Claude Cowork | Claude guide: a custom connector, or the plugin |
| Codex in the ChatGPT desktop app or the CLI | Codex guide: the plugin, or MCP only |
| Cursor | Below |
| Hermes | Agent setup: Hermes |
| Any other MCP client | Add the server URL above and approve the login, or connect with an API key |
Cursor
- In Cursor, go to Settings -> Tools & Integrations -> MCP Tools.
- Choose New MCP Server, which opens the file
mcp.json. - Paste this entry:
{
"mcpServers": {
"roamseo": {
"url": "https://app.roamseo.com/mcp"
}
}
}
- 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 to | Do this |
|---|---|
| Use an agent in a second workspace | Connect once more and select that workspace on the authorization page. |
| Make a key for a second workspace | Switch to that workspace in the app first, then create the key. |
| Cut off an agent | In Settings, find Connected agents and press Disconnect. |
| Cancel a key | In 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
| Symptom | Fix |
|---|---|
| The client won't connect | Compare the server URL character by character with https://app.roamseo.com/mcp. |
| Authorization fails | Remove the RoamSEO server from the client, add it back and go through the login again. |
| The agent says it has no project | Have 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 to | Use |
|---|---|
| Record goals, positioning, competitors and key pages for all skills to reuse | SEO project setup |
| Get guidance because you're new to SEO or unsure where to begin | SEO coach |
| Collect questions and cited sources before deciding what to track | AI Prompt Research |
| Learn why competitors show up in AI answers and what to change | AI Visibility Audit |
| Find keyword opportunities | keyword research |
| Survey a market before picking competitors or pages | competitive landscape |
| Examine a single competitor | competitor analysis |
| Group keywords into pages | keyword clustering |
| Build an outreach list for a linkable asset | link prospecting |
Supported engines, research coverage and costs for AI features are explained in the AI Visibility guide.