Connect your AI agent to OpenSEO

OpenSEO has an MCP server, so AI agents such as ChatGPT, Claude, Cursor, Codex and Gemini can use everything in the app: research keywords, check rankings, read your Search Console data, run audits. Skills add ready-made SEO workflows on top. Setup takes a couple of minutes.

ChatGPT and Claude: sign in with OpenSEO

ChatGPT and Claude (on the web and in the desktop app) connect through a custom connector and sign in with your OpenSEO account. No API key needed.

1. Add a connector

   ChatGPT: Settings, Apps & Connectors, Advanced settings, turn on Developer mode, then Create. Claude: Settings, Connectors, Add custom connector.

2. Point it at OpenSEO

   Name it OpenSEO, set the server URL to https://seo-api.seeserver.ir/mcp, and choose OAuth as the authentication. Leave the client ID and secret empty: the connector registers itself.

3. Sign in and allow

   A window opens on OpenSEO. Sign in if you need to, check what the connector will be able to do, and click Allow. You are sent back and the tools appear.

Connected apps are listed in Settings in OpenSEO, where you can disconnect them at once. Access lasts an hour at a time and renews itself; the connector never sees your password or keys. Developer mode and custom connectors depend on your ChatGPT or Claude plan.

Other agents: a setup prompt

1. Create an API key

   In the app, open Settings and create an API key under API keys. It starts with oseo_ and is shown once. Treat it like a password.

2. Put it in an environment variable

   # macOS and Linux: add to ~/.zshrc or ~/.bashrc
   export OPENSEO_API_KEY="oseo_..."
   
   # Windows (PowerShell), saved for new terminals
   setx OPENSEO_API_KEY "oseo_..."

   The prompt below never asks for the key in chat, so it stays out of your conversation history.

3. Paste the setup prompt into your agent

   Copy setup prompt

   The agent works out what it is, adds the OpenSEO server its own way, asks you to reload if needed, and checks the connection with two free calls. It does not create anything or spend during setup. The prompt in Settings in the app is already filled in with your install's address.

   Connect yourself to OpenSEO, an open-source SEO suite, over MCP. Work through these steps in order and stop at any step that needs me.
   
   1. Check first. Work out which agent you are (for example Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, OpenCode or Windsurf) and whether an MCP server named "openseo" is already set up. If it is and its tools work, go to step 5.
      If you are ChatGPT, or Claude on the web or in the desktop app, you cannot add servers yourself: tell me to add a custom connector in your settings with the URL https://seo-api.seeserver.ir/mcp and OAuth sign-in, which needs no API key, then stop.
   
   2. The key. The connection needs an OpenSEO API key, which starts with oseo_. Ask me to create one in the OpenSEO app under Settings, API keys, and to store it in an environment variable named OPENSEO_API_KEY. Never ask me to paste the key into this chat, and never write it into a file inside a code repository.
   
   3. Add the server. Add a remote MCP server named "openseo" with:
      - URL: https://seo-api.seeserver.ir/mcp
      - Transport: streamable HTTP
      - Header: Authorization: Bearer <value of OPENSEO_API_KEY>
      Use your own supported way of adding MCP servers, and read the key from the environment variable. If you cannot change your own configuration, tell me exactly what to add and where. Instructions for each agent: https://seo-site.seeserver.ir/docs/mcp
   
   4. Reload. If the openseo tools are not available yet, tell me how to restart or reload you, and stop.
   
   5. Verify, for free. Call whoami and list_projects. Both are free. During setup, do not run any paid lookup, create projects or change settings.
   
   6. Report back in under 120 words: what you set up, whether whoami worked, the projects you found, and three things I could ask you next. Mention that paid lookups show their price first, and that I can give you a spending limit for any request.

Skills and the Claude Code plugin

Skills are written workflows your agent follows, built on the MCP tools. Each one prices paid steps first and keeps to the limit you agree.

In Claude Code, the plugin installs the MCP server and all the skills together. It reads your key from OPENSEO_API_KEY and connects to https://seo-api.seeserver.ir/mcp; set OPENSEO_MCP_URL to use a self-hosted install instead.

/plugin install openseo --marketplace duckduckdeploy/openseo

# On older Claude Code versions, in two steps:
/plugin marketplace add duckduckdeploy/openseo
/plugin install openseo@openseo

Then try /openseo:seo-coach. For other agents, connect the server as below and add the skills with the skills command, or copy the folders from plugins/openseo/skills in the repository into your agent's skills folder.

# Any agent that reads SKILL.md files (Claude Code, Codex, OpenCode and others)
npx skills add duckduckdeploy/openseo/plugins/openseo/skills

How you start a skill depends on the agent: a slash command in some, or just asking ("run the seo-audit skill") in others.

Set it up by hand

Every client needs the same three things: the URL https://seo-api.seeserver.ir/mcp, the streamable HTTP transport, and the header Authorization: Bearer followed by your key. Field names differ by client:

claude mcp add --transport http openseo https://seo-api.seeserver.ir/mcp \
  --header "Authorization: Bearer $OPENSEO_API_KEY"

{
  "mcpServers": {
    "openseo": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://seo-api.seeserver.ir/mcp",
               "--header", "Authorization:Bearer ${OPENSEO_API_KEY}"],
      "env": { "OPENSEO_API_KEY": "oseo_..." }
    }
  }
}

{
  "mcpServers": {
    "openseo": {
      "url": "https://seo-api.seeserver.ir/mcp",
      "headers": { "Authorization": "Bearer ${env:OPENSEO_API_KEY}" }
    }
  }
}

{
  "inputs": [
    { "type": "promptString", "id": "openseo-key", "description": "OpenSEO API key", "password": true }
  ],
  "servers": {
    "openseo": {
      "type": "http",
      "url": "https://seo-api.seeserver.ir/mcp",
      "headers": { "Authorization": "Bearer ${input:openseo-key}" }
    }
  }
}

[mcp_servers.openseo]
url = "https://seo-api.seeserver.ir/mcp"
bearer_token_env_var = "OPENSEO_API_KEY"

{
  "mcpServers": {
    "openseo": {
      "httpUrl": "https://seo-api.seeserver.ir/mcp",
      "headers": { "Authorization": "Bearer $OPENSEO_API_KEY" }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "openseo": {
      "type": "remote",
      "url": "https://seo-api.seeserver.ir/mcp",
      "headers": { "Authorization": "Bearer {env:OPENSEO_API_KEY}" }
    }
  }
}

{
  "mcpServers": {
    "openseo": {
      "serverUrl": "https://seo-api.seeserver.ir/mcp",
      "headers": { "Authorization": "Bearer ${env:OPENSEO_API_KEY}" }
    }
  }
}

Self-hosting? Use your own API address, for example http://localhost:4100/mcp on your computer. See Self-hosting.

Check it works

Ask your agent to call whoami and list_projects. Both are free. If they work, the agent sees all 69 tools, listed with their prices in MCP tools.

Updating

/plugin marketplace update openseo
/reload-plugins

For skills added with the skills command, run npx skills update. Copied folders: replace them with the latest from the repository. The MCP connection itself never needs updating: new tools appear on their own.

Troubleshooting

REST API

The same key works with the REST API, for scripts and your own tools. Send it in the same Authorization header.