RoamSEO

Use RoamSEO with Codex

Add RoamSEO MCP and Agent Skills to Codex in the ChatGPT desktop app or the Codex CLI.

The RoamSEO plugin bundles RoamSEO MCP and all twelve SEO Agent Skills into one install. This is the preferred way to set up RoamSEO in Codex, in the ChatGPT desktop app or the CLI.

Desktop app

In the ChatGPT desktop app, open Codex and start a new chat. Paste the agent setup prompt so Codex can configure RoamSEO and guide you through sign-in.

If RoamSEO appears in your Plugins directory, install it, approve the RoamSEO sign-in, and start a new Codex chat. If the listing is missing, use the setup prompt or the CLI steps below.

Ask: “Use RoamSEO to check my connection and list my projects.” The check uses no RoamSEO credits. A tool call followed by your projects, or an empty list, confirms that this chat is connected.

Check OpenAI's plan support for access to your Codex client. Installing in Codex does not connect a regular chat on chatgpt.com. For that, use the ChatGPT guide.

MCP only in the desktop app

The plugin includes MCP and the SEO skills. For MCP alone:

  1. Open Codex, then Settings → MCP servers → Add server.
  2. Name it roamseo, choose Streamable HTTP, and enter https://app.roamseo.com/mcp.
  3. Save and select Restart when prompted.
  4. Select Authenticate for RoamSEO and approve sign-in when prompted. Skip this step for a local server configured without authentication.
  5. Start a new Codex chat and ask: “Use RoamSEO to check my connection and list my projects.”

This local connection is separate from ChatGPT web. See OpenAI's MCP documentation.

Install in the CLI

Run these commands in your terminal:

codex plugin marketplace add roamseo/roamseo-plugins
codex plugin add roamseo@roamseo
codex mcp login roamseo

codex mcp login opens a browser to approve the RoamSEO connection. If it reports that roamseo isn't found, restart Codex first — bundled MCP servers only register after a restart, not immediately after install — then run codex mcp login roamseo again.

Codex connects RoamSEO MCP at https://app.roamseo.com/mcp and enables twelve skills:

  • SEO Project Setup
  • SEO Coach
  • SEO Audit
  • AI Visibility Audit
  • AI Prompt Research
  • Keyword Research
  • Keyword Clustering
  • Competitive Landscape
  • Competitor Analysis
  • Local SEO
  • Link Prospecting
  • SEO Report

MCP only in the CLI

Use this if you want RoamSEO's tools without the skills. Run this in your terminal:

codex mcp add roamseo --url https://app.roamseo.com/mcp

Approve the login when prompted. To use an API key instead of signing in, see Connect with an API key.

Run a skill

Type $ in Codex to see available skills, or ask Codex to run one by name, for example "run seo-project-setup" or "run seo-audit on example.com".

Update

codex plugin marketplace upgrade roamseo

Reload or restart Codex if the updated skills are not available. If your CLI rejects a command, check codex plugin --help for the commands supported by your version. See OpenAI's marketplace documentation. For plugins installed through a desktop directory, use that directory's controls.

For other installation methods, see Agent setup and skill updates.

Remove

codex plugin remove roamseo@roamseo

Troubleshooting

If the RoamSEO MCP server doesn't appear after restart, run /mcp in the Codex TUI to check its status, then run codex mcp login roamseo again.

If it still doesn't authenticate, log out first and retry:

codex mcp logout roamseo
codex mcp login roamseo

If a codex plugin command reports "unrecognized subcommand," run codex plugin --help to see the subcommands your installed version actually supports — they've changed across versions (for example, add/remove, not install/uninstall).

If Codex reports Authorization server response missing required issuer: expected https://app.roamseo.com, upgrade Codex CLI or the Codex desktop app to 0.147.0 or later. Codex 0.143 through 0.146 drop the issuer from the OAuth callback. You can also connect with an API key instead of OAuth.

Other clients

For ChatGPT web, use the ChatGPT setup guide. For Claude, see Use RoamSEO with Claude. For Cursor or an API key setup, see Set up RoamSEO MCP and Set up RoamSEO Agent Skills.