Set up Role SEO MCP

Use user scope to make Role SEO available across projects, or local scope for the current repository.

claude mcp add --transport http --scope user role-seo https://app.role-seo.com/mcp

Once the server is added, approve the Role SEO login when prompted.

1. Open Customise, then Connectors.
2. Hit Add (or +), and pick Add custom connector.
3. Paste https://app.role-seo.com/mcp.
4. Approve the Role SEO login when it prompts you.

Custom connectors are on the Free, Pro, Max, Team and Enterprise plans. Free plans get one custom connector.

1. Open Cursor Settings, then Tools & Integrations, then MCP Tools.
2. Hit New MCP Server. Cursor opens mcp.json.
3. Add the block below.
4. Approve the Role SEO login when it prompts you.

{
  "mcpServers": {
    "role-seo": {
      "url": "https://app.role-seo.com/mcp"
    }
  }
}

Run this in your terminal:

codex mcp add role-seo --url https://app.role-seo.com/mcp

Approve the login when it prompts you.

1. Open Settings, then Integrations & MCP.
2. Hit Add your own.
3. Paste https://app.role-seo.com/mcp.
4. Approve the Role SEO login when it prompts you.

Use an API key for headless environments, CI, or any client where OAuth is a pain. API keys are personal. Anything an agent does with your key acts as you inside your workspace.

In the Role SEO app, open Settings → API keys, create a key, and copy it while it's showing. It won't be shown again.

For Claude Code:

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

For Cursor, add headers to the server entry in mcp.json:

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

For Codex CLI:

export ROLE_SEO_API_KEY=oseo_YOUR_KEY
codex mcp add role-seo --url https://app.role-seo.com/mcp --bearer-token-env-var ROLE_SEO_API_KEY

Any other client that supports custom HTTP headers can send Authorization: Bearer oseo_YOUR_KEY or x-api-key: oseo_YOUR_KEY.

Role SEO MCP exposes tools for SEO research workflows:

• Research keywords with volume, difficulty and CPC.
• Pull live Google organic SERP results for keywords.
• Find exact keyword, page, rank, volume, CPC, intent and traffic rows for a domain or page.
• Compare SERP competitors across a supplied keyword set.
• Search local businesses near a coordinate, filtering by rating, review count or claimed status.
• Pull one Maps or Local Finder SERP, and read Google Business Q&A when needed.
• Audit a Google Business Profile: categories, rating, hours, photos and claim status.
• Gather Google reviews (including reviews from other sites) and Google Business posts.
• Look up valid Google Business category slugs.
• Check Google Maps rank at each point of a grid around a business.
• Hydrate keywords with search volume, difficulty, intent, CPC and trends.
• List saved keywords from a Role SEO project.
• Save useful keywords back to Role SEO.
• Read rank tracker configs and the latest keyword positions.
• Summarise a domain's organic footprint.
• Find keywords a domain already ranks for.
• Check backlink and referring-domain overview data.
• Read first-party Google Search Console performance (clicks, impressions, CTR, position).
• Inspect index status, crawl and canonical for specific URLs (up to 10 per call).
• Read and update a project's shared context, free of credits.

Ask your agent a focused SEO question rather than “do SEO” in general. A few starters:

• “Set up my project context: my business, my goal, my main competitors, and my three most important pages.”
• “Which keywords am I ranking between 8 and 15 for that could push to page one with a light on-page tweak?”
• “Show me the top ten organic pages for competitor.com and the keywords that earn each one.”
• “Cluster these fifty keywords into topical groups I can turn into pages.”
• “Find backlink opportunities for our new pillar page.”

• If your client can't connect, check the server URL is exactly https://app.role-seo.com/mcp.
• If Codex reports Authorization server response missing required issuer, 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.
• If authorisation fails, disconnect the Role SEO server in your client, add it back, and run the login flow again.
• If your agent can't find a project, ask it to list Role SEO projects first and use the returned project ID in later tool calls.