MCP Server
The Ranktracker MCP server lets an AI client — Claude (Desktop or Code), Cursor, ChatGPT, or anything that speaks the Model Context Protocol — read your rank-tracking data directly. Ask "which of my tracked keywords dropped the most this week?" or "summarise the backlink trend for example.com" and the model calls the right tool, scoped to your account, with no glue code from you.
It's a hosted, remote MCP server mounted on the Ranktracker API at a single endpoint. Connect it with OAuth — paste the URL, approve in your browser, nothing to copy — or with a dedicated API token for CI and scripting.
:::tip Ready to connect? Jump to Connect a client — two minutes with OAuth, and no token to handle. :::
MCP or REST — which should I use?
They talk to the same data; they suit different jobs.
| MCP server | REST API | |
|---|---|---|
| Best for | AI assistants & agents exploring your data conversationally | Dashboards, warehouses, scheduled jobs, your own app |
| Caller | Claude, Cursor, ChatGPT, MCP clients | Any HTTP client / your backend |
| Shape | Named tools the model picks and fills in | Fixed HTTP endpoints you call |
| Endpoint | POST /mcp (one endpoint) | /v1/... resources |
| Auth | OAuth, or Authorization: Bearer tkn_mcp_usr_… | Authorization: tkn_usr_… (no Bearer) |
| Writes | Read-only, plus one safe run_report | Full CRUD |
Use MCP when a person or agent is in the loop asking questions. Use the REST API when your software is moving data on a schedule. Many teams use both, each authorised separately.
The connection at a glance
- Endpoint:
POST https://api.ranktracker.com/mcp(Streamable HTTP transport) - Plan: your plan must have API access enabled (same flag as the REST API)
- Scope: a connection only ever sees data in the account that authorised it
There are two ways to authenticate, and most people want the first:
| OAuth (recommended) | API token | |
|---|---|---|
| How you connect | Paste the endpoint URL into your AI client and approve in the browser | Create a token, paste it into the client's config |
| Nothing to copy | ✅ | ❌ |
| Who can set it up | An account administrator | An account administrator |
| Permissions | Chosen at approval: mcp:read, optionally mcp:write | Full access |
| Expiry | Access tokens last 1 hour and refresh automatically | Never expires until deleted |
| Best for | Claude, ChatGPT, Cursor — anything a person uses interactively | CI, scripts, clients without OAuth support |
Connect a client → walks through both.
API tokens are a distinct kind of key. They work only on /mcp — never on
/graphql or the REST API — and a REST API key will not authenticate against
/mcp. Keeping the two separate means you can hand an AI client an MCP token and
revoke it independently without touching your programmatic integrations.
Tool surface
Fourteen tools: 13 read-only (annotated readOnlyHint: true) and one
write, run_report. Everything is keyed by uuid — start with list_domains
and pass the returned domain_uuid to the keyword, competitor, backlink and
audit tools. Your client discovers these automatically via tools/list.
Arguments, defaults and return fields for every tool live in the Tool reference, which is generated from the running server — so it never drifts from what your client actually sees.
Reads
| Tool | What it returns |
|---|---|
list_domains | Tracked domains in the account, with uuids |
get_domain | One domain: monitor limits and configuration |
list_keywords | Tracked keywords for a domain with their latest rankings |
get_keyword_rankings | Daily ranking history for one keyword (organic / absolute / local-pack, SERP features, AI Overview) |
list_competitors | Competitor websites configured for a domain |
list_keyword_research | Keyword Finder research sessions in the account |
get_monitor_summary | Backlink, keyword and audit monitor summary for a host |
list_backlinks | Backlinks for a domain, newest first |
get_backlink_summary | Backlink profile trend (domain rank, new / lost) |
list_reports | Configured SEO reports, with uuids |
get_report | One report: schedule, recipients, latest run (with file URL) |
list_website_audits | Website audits for a domain, with status and scores |
get_website_audit | One audit: crawl stats, scores, warnings, technical issues |
Write
| Tool | What it does |
|---|---|
run_report | Generates a fresh run of an existing report |
:::note run_report is deliberately safe
It only re-runs a report you already configured, at most once per report
period, and it never emails your report recipients — the run appears in
the app, and the tool returns the run's status and file URL. It does not
create reports, spend keyword credits, or change anything you track. Tools that
would consume paid credits (adding keywords, refreshing rankings, creating
domains) are intentionally not exposed to AI clients.
:::
Response format
Tool results are pretty-printed JSON by default. For large tables
(keywords, backlinks) you can request TOON —
a compact tabular text format that uses roughly 40–60% fewer tokens — by adding
?format=toon to the endpoint:
https://api.ranktracker.com/mcp?format=toon
The data is identical; only the encoding changes. Leave it on JSON unless you're optimising token usage on big result sets.
Rate limits
The /mcp endpoint is throttled independently of the REST API:
| Scope | Limit |
|---|---|
| Per MCP token | 200 requests / minute |
| Per IP address | 300 requests / minute |
Over the limit returns HTTP 429; back off and retry. See Errors and rate limits for the general throttling model.
Next steps
- Connect a client → — connect with OAuth, or with an API token for CI.
- Tool reference → — every tool's arguments, defaults and return fields.
- Authentication — how API access and the
apiEnabledplan flag work (shared with MCP). - API Reference — the REST surface for programmatic integrations.