Kranked MCP

An MCP server that exposes App Store keyword intelligence — keyword difficulty, popularity, and live rank — as tools any MCP client (Claude, etc.) can call. It's the headless companion to the Kranked ASO app: same scoring, no GUI.

Stateless and zero-config: every tool is a live call to Apple's public endpoints (the iTunes Search API and search-hints). No database, no API keys. Runs locally via uvx or as a hosted server.

Speaks MCP 2026-07-28 (Python SDK v2), and stays backwards compatible with 2025-era clients from the same server. Era is selected per request from the MCP-Protocol-Version header, so over stdio — which has no headers — the server answers the 2025 initialize handshake. Nothing to configure either way; clients negotiate it themselves.

Tools (free / open core)

All tools take a two-letter country (default us).

Premium (hosted): popular_keywords — top most-searched keywords by category with real Apple Search Ads popularity (0–100) — is available on the hosted service, not in this open-source package.

How the scores work

• Difficulty (0–100) — analyzes the top-10 ranking apps' review volume and rating quality. More established competitors = harder. Labeled Very Easy → Very Hard.
• Popularity (20/50/80) — whether Apple auto-suggests the term (exact / related / neither). For real ASA popularity numbers, use popular_keywords.
• KEI — Keyword Efficiency Index = popularity / difficulty. Higher is a better bet.

Install

On PyPI — nothing to clone or build. uvx fetches and runs it on demand. Needs Python 3.10+ and uv (brew install uv). Add to your MCP client config:

{
  "mcpServers": {
    "kranked": {
      "command": "uvx",
      "args": ["kranked-mcp"]
    }
  }
}

For Claude Code: claude mcp add kranked -- uvx kranked-mcp

Source

The sdist on PyPI carries the full source and the test suite — it's on the Download files tab. Unpack it and uv sync, then point your client at that directory:

{
  "mcpServers": {
    "kranked": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/kranked-mcp", "run", "kranked-mcp"]
    }
  }
}

Run the tests — they're offline (pure scoring plus server wiring driven through the real ASGI app), so they don't hit Apple and can't flake on rate limiting:

uv run pytest

Self-hosting (remote MCP)

Kranked runs in two modes from the same code:

The hosted server is stateless, so it scales horizontally — no sticky routing, no session affinity. Since MCP 2026-07-28 that is the protocol's own model rather than an opt-in: there is no initialize handshake and no session id, and clients negotiate up front with server/discover instead. Deploy the included Dockerfile to any container host (Railway, Fly, Render, …); it reads PORT from the environment and exposes GET /health for liveness checks.

server/discover and tools/list carry a one-hour public cache hint (ttlMs / cacheScope), so clients can hold the tool list instead of re-listing it every session.

Deploy to Railway

The repo ships a railway.toml (Dockerfile build, /health healthcheck). To deploy:

# one-time
npm i -g @railway/cli && railway login

# from the repo root
railway init            # create/select a project
railway up              # build the Dockerfile and deploy
railway domain          # get a public https URL

Or connect the GitHub repo in the Railway dashboard — it picks up railway.toml automatically. Set KRANKED_CACHE_TTL in the service's Variables if you want a longer/shorter cache.

Then point a client at the URL:

claude mcp add --transport http kranked https://your-app.up.railway.app/mcp

Config

Caching is not optional for a hosted deployment. All users' requests leave from one IP, so without it you hit Apple's per-IP throttle immediately. Difficulty/popularity change slowly, so cached results stay useful for hours. For multiple instances, move the cache to Redis.

Setting KRANKED_API_KEY gates every endpoint except GET /health behind a bearer token; unauthenticated callers get a 401. Leave it unset and the server is open, which is what you want for a local stdio run. Usage metering for a paid tier is still roadmap.

Rate limiting

The iTunes API throttles unauthenticated callers per IP with a 403/429 and a non-JSON body. The server serializes requests through a global throttle and retries throttles with exponential backoff + jitter, so it degrades gracefully instead of surfacing bogus decoding errors.

License

MIT © Akos Komuves