SerpBeats MCP

A read-only MCP server that opens the data of the projects in your SerpBeats account to an AI agent. In every paid plan at no extra cost.

Server
https://stage.serpbeats.com/mcp
Transport
Streamable HTTP (MCP), POST https://stage.serpbeats.com/mcp
Authorization
OAuth 2.1 + PKCE or a personal token
Access
Read-only
Available in
Every paid plan; not in the free trial
Machine-readable
/en/seo-mcp-server.md · /llms.txt

Clients

Any client that speaks streamable HTTP MCP can connect. Setup is ready for the ones below.

ClientAuthorizationWhere it is added
ClaudeOAuthSettings → Connectors → Add custom connector. URL: https://stage.serpbeats.com/mcp. Authentication: Sign in now, OAuth client: Register automatically.
ChatGPTOAuthSettings → Apps → add a custom MCP server (turn on Developer mode first if needed). URL: https://stage.serpbeats.com/mcp, authentication: OAuth.
Gemini appOAuthSettings → Connected Apps → Add a custom app. URL: https://stage.serpbeats.com/mcp. Google currently offers this only in the US, on personal accounts and in English.
Claude CodeTokenclaude mcp add
CodexToken~/.codex/config.toml
CursorToken~/.cursor/mcp.json
Gemini CLITokengemini mcp add
Other MCP clientsTokenURL and an Authorization header

Configuration for the token clients

YOUR_TOKEN is the token you create on the /ai-connection page.

Claude Code
claude mcp add --transport http --scope user serpbeats https://stage.serpbeats.com/mcp --header "Authorization: Bearer YOUR_TOKEN"
Codex · ~/.codex/config.toml
[mcp_servers.serpbeats]
url = "https://stage.serpbeats.com/mcp"
http_headers = { Authorization = "Bearer YOUR_TOKEN" }
Cursor · ~/.cursor/mcp.json
{
  "mcpServers": {
    "serpbeats": {
      "url": "https://stage.serpbeats.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
Gemini CLI
gemini mcp add --transport http --header "Authorization: Bearer YOUR_TOKEN" serpbeats https://stage.serpbeats.com/mcp
Other
URL: https://stage.serpbeats.com/mcp
Authorization: Bearer YOUR_TOKEN

Authorization

Two methods; both reach the same data with the same rights (read-only). Chat apps sign in with your account over OAuth; coding tools that cannot open a sign-in window use a token.

OAuth 2.1: sign in with your account

Where
You add the connector in the client; SerpBeats' approval page opens, you sign in with your account and allow it. No token to create.
Flow
Authorization Code + PKCE (S256); public client, no client secret
Client registration
Dynamic Client Registration (RFC 7591): POST /oauth/register, the app registers itself
Endpoints
/oauth/authorize · /oauth/token
Discovery
/.well-known/oauth-authorization-server · /.well-known/oauth-protected-resource
Scope
mcp:use
Lifetimes
Access token 1 hour, refresh token 30 days
Allowed redirect hosts
claude.ai, claude.com, chatgpt.com, chat.openai.com, platform.openai.com, gemini.google.com, Google's oauth-redirect relays, localhost and 127.0.0.1

Personal token

Where
Signed in, on the /ai-connection page: Create token
Use
Authorization: Bearer sbk_… header
Lifetime
30, 90 or 365 days, or none; chosen when you create it
Ability
agent:read (read only)
Storage
Shown once; only its hash is kept
Count
At most 5

On every call the account is checked for an active paid plan. No or invalid credentials get 401; the free trial and an ended plan get 403.

Services and the data they serve

12 tools are active, all read-only. Data comes from stored scans, with no live lookups, and every answer carries the date of its data (data_as_of). Every tool except list_projects takes project: an id, a domain or a name; it may be left out when the account has a single project.

ToolData servedParameters
Projects and rankings
list_projectsThe account's projects: id, name, domain, country, tracked keyword count, date of the last scan.project only
get_project_summaryProject summary: distribution over top 100 / 50 / 30 / 10 / 3 / 1 (cumulative), how many keywords improved, dropped or left the rankings, visibility, average position, estimated monthly clicks and their changes.period_days7 | 30
get_keyword_rankingsTracked keywords that are listed in Google: position, previous position, change, monthly volume, difficulty, intent, ranking page, estimated clicks, AI Overview and SERP features. sort=dropped_out returns the ones that left the rankings.period_days7 | 30sortposition | volume | gain | loss | dropped_outlimit1–100
get_keyword_historyOne keyword: daily positions (7–90 days), best and worst position, the ranking page and the days it changed, 12 months of volume, the AI Overview (text, sources, whether it cites the site), the results page (top 20) and where the rivals stand.keyword*days7–90
Site audit
get_site_auditSite health from the latest crawl: score and its change, pages scanned, counts of errors / warnings / recommendations, four area scores, Core Web Vitals.project only
get_audit_issuesEvery site issue: severity, area, how many pages it hits, the points fixing it adds. For one issue: what it means, how to fix it and the affected pages.issueseveritycritical | warning | recommendation
get_audit_pagesThe crawled pages: status code, score, load time, size, click depth, word count, title, description, H1, issues and the evidence for each. url opens one page in full.urlissuestatusok | errorsortworst | slowest | largest | deepest | thinnest | lowest_scorelimit1–50offset
get_audit_linksWhat the crawl found between pages: broken links (by target, with every page that carries the link and its anchor text), redirected links, redirect chains, pages hidden from search engines.kind*broken_links | redirected_links | redirect_chains | non_indexable_pagespagelimit1–50offset
Rivals, AI visibility, local SEO and report
get_competitorsTracked rivals (visibility, average position, who is ahead on shared keywords) and suggestions for rivals that keep appearing beside the site and are not tracked yet.period_days7 | 30suggestions1–20
get_ai_visibilityVisibility in AI answers: score (0–100), score per platform and its change, the weekly trend, and for every tracked question cited, not cited or no data.Needs: AI Bundlelimit1–100
get_local_seoThe business on Google Maps (rating, reviews, profile gaps) and, per local keyword, the average rank over the scanned points, the share of top-3 points, the share by distance, the leaders and the strongest rivals.Needs: local keywordsproject only
get_report_dataOne call for a report: distribution, movements, site health, rivals and AI visibility.period_days7 | 30

* required

Revoking access

OAuth app
On the /ai-connection page, Remove access next to the app. All of the app's keys are revoked at that moment.
Token
On the same page, Delete next to the token. The token stops working at once.
Plan ends
When the plan ends or the account is deactivated, every connection closes (403).
Log
Which tool was called and when is recorded; the data returned is not kept.

Limits

Request rate
60 requests a minute and 1,500 an hour per connection; beyond that, 429.
Answer size
At most about 120 KB; long lists are paged with limit and offset.
Rows per call
get_keyword_rankings and get_ai_visibility up to 100, get_audit_pages and get_audit_links up to 50.
History
get_keyword_history covers 7 to 90 days.
Data freshness
From the daily scans; no live lookups. Parts gone stale are marked in the answer (age_days, stale_sections).
Reading
No tool starts a scan, spends credits, changes a setting or deletes anything.
Tokens
At most 5 per account; OAuth access key 1 hour, refresh 30 days.
Out of scope
Keywords that were never listed are only counted, never listed. Without local keywords (local SEO) or an AI Bundle (AI visibility) the tool returns no data.