What is an SEO MCP server?
The Model Context Protocol (MCP) lets AI apps call tools on a server. An SEO MCP server exposes SEO data as tools, so a coding agent can answer “why did this keyword drop?” by reading rankings, crawl issues and search data itself, and then change the code. Serpel’s server is remote, so there is nothing to install: your agent connects to a URL.
The server uses Streamable HTTP and answers each request on its own, with JSON. Lists are capped at 25 rows, so agents get compact answers instead of raw data. For Claude Code SEO work, that is the whole integration: one command adds the server.
How do you connect Claude Code, Cursor and other agents?
Every client uses the same URL. The first tool call opens a browser window where you sign in, choose the workspace and approve access. The Claude Code setup guide walks through it step by step.
| Client | How to connect |
|---|---|
| Claude Code | Run claude mcp add --transport http serpel https://serpel.app/mcp. |
| Claude Desktop and claude.ai | Add a custom connector with the URL under Connectors. |
| Cursor | Add the URL to .cursor/mcp.json, as shown above, and sign in when the browser opens. |
| Codex | Add url = "https://serpel.app/mcp" under [mcp_servers.serpel] in ~/.codex/config.toml. |
| ChatGPT | In developer mode, add a connector with the URL under Apps and Connectors. |
| VS Code with GitHub Copilot | Add a server of type http with the URL to .vscode/mcp.json. |
| Gemini CLI | Set httpUrl to the URL under mcpServers in ~/.gemini/settings.json. |
Which tools does the Serpel MCP server offer?
The server offers 13 tools. Each has a title, a description, an input schema and annotations, and the 12 free tools are marked read-only.
| Tool | What it does | Cost |
|---|---|---|
list_projects | Lists the projects you can access, with IDs, domains, markets and your role. Call it first: every other tool needs a project ID. | Free |
get_project_overview | Summarises one project: audit score, rankings, AI visibility, tasks, top issues and next steps. | Free |
get_keyword_rankings | Returns tracked keywords with the latest Google position, the previous position and the change. | Free |
get_search_performance | Returns clicks, impressions, CTR and position from Search Console or Bing, compared with the previous period. | Free |
find_keyword_opportunities | Finds search queries on positions 4 to 20 with impressions and matches them against your tracked keywords. | Free |
get_crawl_issues | Lists the issues of the latest crawl by type, severity and affected pages, with the score and its change. | Free |
get_ai_visibility | Shows how often ChatGPT cites or mentions your website and how often Google AI Overviews cite it, with the latest result per prompt. | Free |
get_seo_recommendations | Lists prioritised recommendations with impact, estimated clicks, effort, page, code route and next action. | Free |
get_codebase_overview | Summarises the latest serpel scan snapshot: routes without metadata and differences between code and the live site. | Free |
get_conversion_performance | Shows sessions, conversions and conversion rate per landing page from your analytics. | Free |
analyze_competitors | Compares the project with saved competitors from stored results, including keywords where a competitor leads. | Free |
get_job_status | Returns the status, progress and result of a background job by its ID. | Free |
research_keywords | Looks up keyword ideas or metrics: search volume, CPC, keyword difficulty and intent. Returns at most 25 keywords. | Credits |
Long-running work such as crawls and rank checks never starts inside a tool call. Start it in the dashboard, the CLI or the REST API, and let the agent follow it with get_job_status.
What can you ask an agent with Serpel connected?
- “Which keywords moved since the last rank check?” The agent calls
get_keyword_rankings. - “Which queries rank on positions 4 to 20?” It calls
find_keyword_opportunities. - “What should I fix first?” It combines
get_crawl_issuesandget_seo_recommendations. - “Which routes in my code lack a title or description?” It calls
get_codebase_overview.
How do budget rules protect your credits?
Only research_keywords spends credits. It runs only when every condition holds:
- The connection includes the
keywords:writepermission. OAuth sign-in grants it. - The workspace has an active Starter or Pro plan.
- The workspace owner has switched on “Agents can spend credits” in the Billing settings, or ran
serpel agents allow. - The call costs at most 50 credits, and today’s agent spending plus the call stays under the daily limit. The default limit is 500 credits, and you can set it up to 100,000. The day follows UTC.
- The balance covers the call. Credits come from your monthly plan allowance first, then from credits you bought.
A repeated call with the same requestId is charged once. If a rule blocks the call, the tool returns a specific error such as plan_required, agent_spend_disabled, daily_cap_reached or insufficient_credits. Plans and credit prices are on the pricing page.
Is it safe to give an agent access?
- OAuth access tokens work only at the MCP server. The REST API rejects them.
- Access tokens last 1 hour. Refresh tokens last 30 days and rotate on every use.
- Tools respect token scopes, your project role and your workspace. A project you can’t access returns
not_found. - You can disconnect an app at any time under Settings, API, Connected apps. Disconnecting revokes its access.
Connect in three steps
Add the server
Point your agent at the Serpel URL. For Claude Code, one command does it.
Terminal claude mcp add --transport http serpel https://serpel.app/mcpSign in
The first tool call opens the browser. Choose the workspace, check the permissions and approve.
Ask a question
Start with “List my Serpel projects”, or ask why a keyword dropped. The agent calls
list_projectsfirst, because every other tool needs a project ID.
Frequently asked questions
Does Serpel’s MCP server work with Claude Code?
Yes. Run claude mcp add --transport http serpel https://serpel.app/mcp, then sign in when the browser opens. Cursor, Codex, VS Code with GitHub Copilot, ChatGPT and the Gemini CLI connect to the same URL.
Can the agent start a crawl or a rank check?
No. The MCP server doesn’t start long-running jobs. Start crawls and rank checks in the dashboard, the CLI or the API. The agent can follow progress with get_job_status and read the results as soon as the job has succeeded.
Can an agent spend my credits?
Only through research_keywords, and only if you have a Starter or Pro plan, have switched on “Agents can spend credits” and stay within the per-call and daily limits. Every other tool is free.
Do I need an API key for the MCP server?
No. Sign in with OAuth in the browser. A client without OAuth support can use an API token with the mcp:read permission instead, plus the read permissions for the data you want to use, and send it as a bearer token.
Updated 10 Oct 2026
Keep reading
- CLIThe Serpel SEO CLI runs rank checks, site audits and AI visibility checks from your terminal, with JSON output, documented exit codes and CI support.
- SEO APISerpel’s SEO API is a REST API for rank tracking, site audits, AI visibility and search data, with bearer tokens, JSON responses and credit-based pricing.
- Google Search Console MCP: connect your agent to search dataSet up a Google Search Console MCP server for Claude Code and other agents: the options compared and Serpel’s search performance tool step by step.
- Connect Claude Code to Serpel over MCPConnect Claude Code to the Serpel MCP server with one command, sign in with OAuth and let the agent read rankings, audits and search data.