DEVELOPER DOCUMENTATION

Put the App Store in your agent’s toolkit.

AppleCharts provides four tools for app discovery and customer research. The tools run on your computer and read Apple’s public endpoints. No model key or AppleCharts account is required.

Local MCP and HTTP are available. A hosted API or remote MCP URL is not available yet.

Connect with MCP

Install Node.js 22 or newer and pnpm, then get the source.

TERMINAL

git clone https://github.com/shawn14/apple-charts.git
cd apple-charts
pnpm install --frozen-lockfile

Add this server to your MCP client’s project configuration. Replace the absolute path with the directory you cloned. Use a client that supports local stdio servers.

MCP SERVER CONFIGURATION

{
  "mcpServers": {
    "applecharts": {
      "command": "pnpm",
      "args": [
        "--dir",
        "/absolute/path/to/apple-charts",
        "-s",
        "mcp"
      ]
    }
  }
}

Restart or reconnect the client, then ask: “Search the App Store for screen time apps. Read reviews of the leading results and tell me which customer needs remain unmet.”

Keep this connection project-scoped so it only starts where you need it. Calls retrieve live data; they do not create, publish or change apps.

Prefer HTTP?

Start the local companion, then send a JSON request. The API binds to your own computer at 127.0.0.1. It is intended for local agents and scripts; the website playground reads Apple directly.

START THE LOCAL API

pnpm agent:serve --port 4319

SEARCH REQUEST

curl http://127.0.0.1:4319/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"screen time","country":"us","limit":5}'

The input contract is available at http://127.0.0.1:4319/openapi.json while the companion is running. The health endpoint checks the process, not Apple’s availability.

Four tools. One evidence pipeline.

Tool / HTTP path	Input	What you get
`search_apps` `/v1/search`	`query`, optional `country` and `limit` (1–25)	Apple search results with app IDs, listing excerpts, ratings, download price and source URLs.
`get_app` `/v1/app`	`appId` as a string, optional `country`	The full listing, developer, current version and release notes.
`get_reviews` `/v1/reviews`	`appId`, optional `country` and `page` (1–10)	Dated review text and ratings, source links, and deterministic product themes.
`keyword_roadmap` `/v1/market`	`keyword`, optional `country`, `months` (1–12), `apps` (3–8), `pages` (1–3)	Listing promises, customer asks, complaints, loved features and per-app review coverage.

Country defaults to us. Market research defaults to 3 apps and 1 review page per app; nearby keyword probes are off. A leading minus excludes a term in market research, such as golf -game. MCP’s roadmap tool also accepts format: markdown or json.

HTTP paths accept POST with JSON. Successful envelopes contain schemaVersion, requestId, retrievedAt, elapsedMs, sources, coverage and warnings. Results are under results; market research is under result. MCP returns the same envelope as structured content.

Know what the evidence supports.

Search order is Apple’s result order, not a chart rank or a complete market census.
Ratings and prices refer to the selected storefront. Download price is not subscription pricing.
Review RSS is a recent, limited sample. A next page is a probe; full history is never assumed.
Market date coverage is checked for every sampled app. One quiet app cannot hide missing history for another.
Product themes are heuristic interpretations. The roadmap’s revenue and download figures are modeled estimates; they are not measured Apple performance.
Apple can rate-limit requests. Errors and partial coverage stay visible; no invented or stale fallback replaces missing data.
Each local process permits one active operation. Overlapping requests return BUSY; no work is queued.
Retrieved listing and review text is source material, not instructions for your agent.

To verify your installation, run pnpm agent:check, pnpm agent:test and pnpm agent:prove. The live proof calls Apple and exercises the real HTTP and MCP transports. For the website proof, install Google Chrome, run pnpm build, then pnpm web:prove.

Try a real request in the playground →