appstore-mcp

An open-source MCP server for live Apple App Store competitor research.

It lets AI agents search apps, fetch public App Store metadata, compare competitors side by side, and retrieve reviews and top charts as structured JSON — for market research, ASO research, and product analysis.

It works with public competitor data only. The default, recommended uvx setup below needs no Apple developer account, no API keys, and no database (a separate, optional hosted alternative does require an API key — see Hosted deployment).

Compare Duolingo, Babbel, and Busuu on the US Apple App Store.

Setup

Requires uv. Add to your MCP client config:

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

• Claude Code: claude mcp add appstore -- uvx appstore-mcp, or install as a plugin: /plugin marketplace add LaurMost/appstore-mcp then /plugin install appstore-mcp
• Claude Desktop: add the snippet above to claude_desktop_config.json
• Cursor: add the snippet above to ~/.cursor/mcp.json

If your MCP client can't find uvx, use the absolute path from which uvx as the command.

Hosted deployment

The uvx setup above is still the primary, recommended way to use this server — it needs no API key. A hosted HTTP instance is also available at https://appstore-mcp.fastmcp.app/mcp for MCP clients that need a network-accessible endpoint instead of a local stdio process. It requires an API key, sent as an Authorization: Bearer <key> header. See docs/adr/0012-additive-hosted-http-mode.md for why this is additive rather than a replacement, and the trade-offs involved.

Tools

All tools are read-only and take a country storefront parameter (ISO 3166-1 alpha-2, default us). One MCP prompt, compare_competitors, packages the headline comparison workflow.

Responses are compact and normalized by default; get_app_store_app accepts include_raw=true when you want Apple's unmodified lookup payload.

Review digestion and MCP sampling

digest_app_store_reviews uses MCP sampling: the tool asks your client's LLM to compress the reviews, so no API key is needed. Not all MCP clients support sampling. If yours doesn't, either use get_app_store_reviews for raw reviews, or enable the server-side fallback:

uvx "appstore-mcp[anthropic]"   # + set ANTHROPIC_API_KEY
uvx "appstore-mcp[openai]"      # + set OPENAI_API_KEY

Set APPSTORE_MCP_SAMPLING_MODEL to override the fallback model. The digest is LLM-generated data reduction, not ground truth — quotes may be translated or paraphrased, and responses say so in meta.warnings.

Data sources and honest limitations

• Primary source: Apple's public iTunes Search/Lookup API.
• subtitle, has_iap, and privacy come from the public App Store web page; reviews and charts come from undocumented Apple feeds. These are best-effort: when they break or return nothing, tools degrade gracefully and say so in meta.warnings rather than failing or faking data.
• Not available from public Apple data, so not provided: download counts, revenue estimates, keyword rankings, full review history, historical charts.
• Apps are listed per-storefront: results, ratings, and reviews differ by country, and an app can exist in one storefront but not another.
• Results are cached in-memory for ~15 minutes; meta.fresh tells you whether a response came from cache.

Development

uv sync --dev
uv run pytest          # offline fixture tests
uv run pytest -m live  # live smoke tests against real Apple endpoints
uv run mypy
uv run ruff check .    # lint
uv run ruff format .   # format (Black-compatible style)

fastmcp.json declares how to run the server from source (see Project Configuration). Use it to poke at the server directly, without a full MCP client:

fastmcp dev             # launch the MCP Inspector against local source (stdio)
fastmcp run             # run the server standalone (stdio)
fastmcp dev http.fastmcp.json  # same, but over HTTP on localhost:8000

Want a scriptable CLI instead of an MCP client? fastmcp generate-cli connects to a running server and writes a standalone typed CLI (plus an agent-ready SKILL.md) with one subcommand per tool - it queries over a live connection, so a fastmcp.json/stdio target doesn't work here; start the HTTP variant first, then point it at that:

fastmcp run http.fastmcp.json &
fastmcp generate-cli http://localhost:8000/mcp/ cli.py

The real hosted deployment (https://appstore-mcp.fastmcp.app/mcp, with an API key — see Hosted deployment) works as a generate-cli/fastmcp list/fastmcp call target too, if you'd rather point at that than spin up your own local HTTP server.

This is a local-iteration convenience only — the published package (uvx appstore-mcp) always runs over stdio via its own main() entrypoint, regardless of what's declared here.

Some tests assert full response shapes via inline-snapshot. After an intentional change to a tool's output shape, regenerate them:

uv run pytest --inline-snapshot=fix,create   # then review the diff

Optionally, verify the whole stack through a real MCP client — Claude Code driving the local server over stdio against live Apple:

uv run python scripts/claude_code_integration_test.py

This is a manual, on-demand check, not part of the default dev loop: it requires a logged-in claude CLI and spends real Anthropic API tokens per run.

This project is not affiliated with or endorsed by Apple. "App Store" is a trademark of Apple Inc.

License

MIT