@rankd/mcp

Model Context Protocol server for Rankd. Connect your App Store keyword rankings, competitor data, and ASO health scores to Claude, Cursor, Cline, and other AI agents via MCP — and let them analyze your data in plain English.

"What apps am I tracking?" "Did my ranking for 'meditation app' improve this month?" "Compare my health score to my top competitor."

1. Get an API key

1. Sign in to Rankd and open Settings → API Keys (rankd.dev/settings/api-keys). Requires an active subscription.
2. Click Create API Key, give it a name (e.g. "My laptop"), and copy the key. It's shown once — save it somewhere safe.

Keys look like rkd_v1_live_<32 chars>.

2. Add the server to your client

Pick your client below. After adding, restart the client so it picks up the new tools.

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "rankd": {
      "command": "npx",
      "args": ["-y", "@rankd/mcp"],
      "env": { "RANKD_API_KEY": "rkd_v1_live_PASTE_YOUR_KEY" }
    }
  }
}

Claude Desktop

Edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add a rankd entry under mcpServers:

{
  "mcpServers": {
    "rankd": {
      "command": "npx",
      "args": ["-y", "@rankd/mcp"],
      "env": {
        "RANKD_API_KEY": "rkd_v1_live_PASTE_YOUR_KEY"
      }
    }
  }
}

Quit Claude Desktop completely (Cmd+Q on macOS) and reopen. You should see "rankd" in the MCP indicator at the bottom of the input box.

Claude Code

claude mcp add-json rankd '{
  "command": "npx",
  "args": ["-y", "@rankd/mcp"],
  "env": {
    "RANKD_API_KEY": "rkd_v1_live_PASTE_YOUR_KEY"
  }
}'

Verify with claude mcp get rankd — should show Status: ✓ Connected. Then start a new session: /exit and run claude again.

Cline / Continue / Zed

Same schema (command + args + env) — paste the snippet into your client's MCP config file. The exact path varies by client; check their docs for the location.

3. Chat with your Rankd data

Prompt ideas:

• "What apps am I tracking in rankd?"
• "Show me the keyword rankings for [app name] over the last 30 days."
• "What's the ASO health score for app id 284882215?"
• "List my competitors for [app] and tell me which one is doing best."
• "What are popular keywords in the Health & Fitness category right now?"

The AI will pick the right tool, fetch your data, and summarize.

Use cases

Conversational reporting

Ask in plain English instead of opening the dashboard.

• "Summarize this week's keyword movement for [app]." → list_keywords + sorts by change.
• "Which of my apps regressed the most over the last 30 days?" → list_tracked_apps → get_rank_history per app.
• "How healthy is my top app's listing?" → get_app_report returns the score + the breakdown.

Find winning keywords from your tracked set

Each tracked keyword already carries Rankd's discovery output. No extra calls needed.

• "Which tracked keywords have I improved on the most this week?" → sort list_keywords by rank_change desc.
• "Which of my tracked keywords have high opportunity but aren't ranked yet?" → filter opportunity_score > 60 and rank IS NULL.
• "What expansion keywords should I add based on what I already track?" → flatten the suggested_keywords field across all tracked keywords, dedupe, sort by opportunity.
• "For 'meditation app', who's beating me right now?" → top_apps on that keyword shows the 5 apps currently ranked higher.

Compare against competitors

Use what's already on competitor apps to spot gaps.

• "Compare my ASO health score breakdown to [competitor app id] — where am I losing?" → two get_app_report calls, diff the category scores.
• "What changed in my competitors' apps recently?" → get_competitors includes recent version updates and metadata changes.
• "Show me the top 5 keywords [competitor app id] is optimizing for in the App Store." → get_app_report(competitor_id) returns a preview of their extracted keywords.

Cross-context analysis

Connect Rankd data with other MCP servers.

• (with GitHub MCP) "Did my keyword rank for 'meditation' improve after I shipped the v2.3 release on April 12?"
• (with Linear MCP) "Open Linear tickets for each suggested keyword Rankd flagged with opportunity > 70."

What read-only can't do (yet)

v1 is read-only. Your agent can list, summarize, and recommend — but if you want to add a tracked app, track a new keyword, or pin a competitor, you still do that in the dashboard.

Tools

| Tool | What it returns | |---|---| | search_apps | App Store search results for a query. | | get_app_report | Free ASO health report for any App Store app — works on apps you don't track. | | list_tracked_apps | All apps you're tracking. | | list_keywords | Tracked keywords for an app with current rank, popularity, difficulty, and opportunity. | | get_rank_history | Daily rank history over the last N days (default 30, max 90). | | get_competitors | Competitor list for an app with metadata, health scores, and recent version updates. | | get_popular_keywords | Trending App Store keywords by country, platform, and genre. |

All tools are read-only in v1.

Configuration

| Env var | Default | Notes | |---|---|---| | RANKD_API_KEY | required | Your Rankd API key. | | RANKD_API_URL | https://api.rankd.dev | Override for self-hosted / staging. | | RANKD_TIMEOUT_MS | 12000 | Per-request timeout. Clamped to 5000–60000. |

Troubleshooting

MCP server fails to connect

Run the server by hand to see the actual error — works for any client:

RANKD_API_KEY=rkd_v1_live_YOUR_KEY npx -y @rankd/mcp < /dev/null

Expected: prints [rankd-mcp] connected (...) on stderr, then exits when stdin closes. If it errors, the message tells you what's wrong (invalid key, network, etc.).

If you're editing config in JSON files, JSON does not allow trailing commas — a stray comma after the last field will silently break things.

"Failed to connect" on first launch (npx cold start)

The first time npx -y @rankd/mcp runs, it has to resolve and download the package — which can exceed your client's MCP startup timeout, leaving a stale Failed to connect even though the config is correct. Subsequent launches hit the npx cache and succeed.

If this keeps happening, install the server globally so npx skips the download:

npm install -g @rankd/mcp

Your existing config keeps working — npx -y @rankd/mcp resolves to the global install and starts instantly.

"RANKD_API_KEY is required"

The env var didn't make it to the server. Common causes:

• Quotes/escaping in the JSON config — the key value must be a plain JSON string.
• Editing the config file but not restarting the client.
• (Claude Code) Adding via claude mcp add with positional args — use claude mcp add-json with a literal JSON config instead, the positional form silently drops args in some shells.

"rankd API key is invalid or revoked"

The key was revoked, deleted, or never existed in your account. Create a fresh one in Settings → API Keys and update the config.

"rankd API rate limit hit"

You're hitting the per-user rate limit (currently 20 req/min). Wait a minute and retry.

Tools don't appear in the client

Most clients only read MCP config at startup. If you edit the config mid-session, you need to restart the client.

Pinning a version

npx -y @rankd/mcp always resolves to the latest published version. If you want to pin (e.g. for reproducible team configs), specify the version:

"args": ["-y", "@rankd/[email protected]"]

Security

• Your API key is sent only to RANKD_API_URL (default https://api.rankd.dev) with HTTPS.
• The MCP server runs locally on your machine — it does not relay data through any third party.
• Treat keys like passwords. Anyone with a key can read your Rankd data.
• Revoke keys at any time in Settings → API Keys. Revocation takes effect immediately; the next request from the revoked key returns 401.
• Each key tracks last_used_at so you can spot unused or stale keys.

License

MIT — see LICENSE.