MCP & API
MCP Server & API
Bring your ASO data into Claude, Cursor, and any agent. Ask “what should I optimize this week?” and get an answer grounded in your real keyword ranks, page-one opportunities, and weekly action plan — then let it act: optimize toward a keyword, generate metadata, translate it. Through the MCP server or the REST API.
Building a platform that ships apps for your customers? See the Store-Ops API for platforms →
Read legacy competition heuristics; these do not measure keyword demand or predict ranking.
Read an app's tracked keywords and their latest store rank.
Tracked keywords ranked 11–30, ordered by the legacy difficulty heuristic.
This week's prioritized ASO actions across all your apps.
AI-rewrite title/subtitle/keywords toward a target keyword — with an apply step.
Create editable projects from real captures, preview screens and export store-sized PNGs. No AppDrift AI tokens.
ASO metadata generation and 60+-language translation, from your agent.
1. Get an API key
Create a key in the Developers area of your dashboard. Keys look like ad_live_… and are shown in full exactly once — store it safely, we only keep a hash. API access requires an eligible paid plan. Eligible first subscriptions to Basic or Indie offer an optional seven-day trial with a card. Studio starts paid, with no free trial. Eligible new trials bring your available AI token balance up to 50 once. You can also pay now for the full plan allowance after payment.
2a. MCP server (Claude, Cursor)
Install Node.js 22 or later, then add this configuration to your MCP client. On the first run npx installs AppDrift’s versioned package and its npm dependencies; no npm account is needed. Replace the API-key placeholder and restart the client.
{
"mcpServers": {
"appdrift": {
"command": "npx",
"args": ["-y", "https://appdrift.co/downloads/appdrift-mcp-0.5.0.tgz"],
"env": { "APPDRIFT_API_KEY": "ad_live_your_key_here" }
}
}
} https://appdrift.co/downloads/appdrift-mcp-0.5.0.tgz in args instead of appdrift-mcp. Restart the client and call list_apps for the new app UUIDs. Numeric app IDs are no longer accepted. Existing apps and saved drafts are retained.Inspect the 0.5.0 package and its SHA-256 checksum. The archive contains the MCP client, bundled renderer and artwork licenses. Use this versioned URL for screenshot tools while npm distribution catches up.
Start with account_status, then list_apps. Both consume no AI tokens. Keep the key in private local configuration. Review paid calls and draft changes in your client. A timeout may happen after the API completed an action; check the balance and draft before retrying.
Tools exposed to the agent:
| Tool | What it does |
|---|---|
| keyword_difficulty | Legacy competition heuristics, not search volume or ranking probability. No AI tokens. |
| list_apps | List apps connected to your account. Free. |
| app_keywords | An app's tracked keywords with latest rank. Free. |
| app_opportunities | Review candidates ranked 11–30. No AI tokens. |
| action_plan | This week's prioritized ASO actions. Free. |
| account_status | Plan + remaining token balance. Free. |
| optimize_for_keyword | AI-rewrite toward a target keyword. 3 tokens, charged on success. |
| apply_optimization | Write accepted fields to the app's draft version. Free. |
| generate_metadata | Generate ASO metadata from a brief. 1 token/field (2 for long fields). |
| screenshot_options | Styles, device sizes and browser setup. No account needed. |
| create_screenshot_project | Save an editable project from 3–8 local captures and supplied captions. Paid API access; no AI tokens. |
| list_screenshot_projects | Recent projects created through MCP. No AI tokens. |
| preview_screenshot_project | Return one 480px preview image. No AI tokens. |
| export_screenshot_project | Write RGB PNGs to a new local folder and record completion. No AI tokens. |
| translate_metadata | Translate a field into up to 15 languages. 1 token/language (3–5 for long fields). |
Create screenshots through MCP
Version 0.5.0 creates editable screenshot projects from your real app captures and your agent’s captions. Preview each screen in the conversation, then export opaque RGB PNGs to a new local folder. These tools need a paid API key, including Basic, and use no AppDrift AI tokens. Captures and captions are saved in your workspace.
Install the renderer’s local Chromium browser once:
npx -y https://appdrift.co/downloads/appdrift-mcp-0.5.0.tgz --install-browserNode.js 22 or later is required. On Linux, install Chromium’s system libraries with npx playwright@1.64.1 install-deps chromium. Rendering happens on the MCP server’s machine with bundled fonts and artwork; its browser blocks external requests.
Create an iOS screenshot project from these three local PNG captures. Write short, factual captions, preview each screen, then export iPhone 6.9 and 6.5 inch PNGs to my chosen folder.Give the agent 3–8 portrait PNG/JPEG paths. Each image can be up to 3 MiB and 12 megapixels, with a campaign maximum of 48 megapixels. Use at least 200px width and at most 4096px per side. Choose editorial, bold or minimal styling and a brand color. For a lost create response, retry identical inputs with the same UUID request_id.
The initial presets are iPhone 6.9 inch (1320 × 2868), iPhone 6.5 inch (1284 × 2778) and Google Play phone (1080 × 1920). Saved projects open in the normal screenshot editor. MCP exports the source language and canonical device designs. Use the editor for other sizes, translations and advanced artwork. Simulator capture and store upload are separate.
Export writes a new subfolder and an export.json manifest without overwriting files. The tool reports whether AppDrift recorded the export receipt. Files remain usable if that confirmation fails. This is a new release; inspect every preview before store upload.
2b. REST API
Prefer to call it directly? Every endpoint takes your key as a bearer token; reads are GET, AI actions are POST with a JSON body. A machine-readable OpenAPI spec lives at /.well-known/openapi.json. Base URL:
https://appdrift-backend-1fabfc95f592.herokuapp.comcurl -H "Authorization: Bearer ad_live_your_key_here" \
"https://appdrift-backend-1fabfc95f592.herokuapp.com/v1/apps"Endpoints
keyword (required), platform (ios|android, default ios), country (default us).curl -H "Authorization: Bearer ad_live_..." \
"https://appdrift-backend-1fabfc95f592.herokuapp.com/v1/keyword-difficulty?keyword=meditation&platform=ios&country=us"{
"data": {
"keyword": "meditation",
"platform": "ios",
"country": "us",
"difficulty": 63,
"popularity": 41,
"source": "live"
}
}id below with the app-scoped endpoints.null = outside the tracked range).locked: true and a placeholder in place of the action and detail.AI endpoints (charge tokens on success)
These consume plan tokens at the same prices as the dashboard, and only charge after successful API processing. A lost response or client timeout does not establish failure on the server: check the account before retrying.
keyword (required), country. Costs 3 tokens.curl -X POST -H "Authorization: Bearer ad_live_..." -H "Content-Type: application/json" \
-d '{"keyword": "habit tracker"}' \
"https://appdrift-backend-1fabfc95f592.herokuapp.com/v1/apps/11111111-1111-4111-8111-111111111111/optimize"fields (object from the optimize response's proposed).platform, app_name, app_description, optional fields, language, keywords. iOS fields: name, subtitle, promotional_text, description, keywords. Android: title, short_description, full_description. Costs 1 token per short field, 2 per long field.curl -X POST -H "Authorization: Bearer ad_live_..." -H "Content-Type: application/json" \
-d '{"platform": "ios", "app_name": "Drift", "app_description": "A minimalist habit tracker with streaks and reminders.", "fields": ["subtitle", "keywords"]}' \
"https://appdrift-backend-1fabfc95f592.herokuapp.com/v1/generate-metadata"field (title, subtitle, description, whats_new, promotional_text, android_title, short_description, full_description, recent_changes), text, target_languages. Costs 1 token per language (3 for description, 5 for full_description).curl -X POST -H "Authorization: Bearer ad_live_..." -H "Content-Type: application/json" \
-d '{"field": "subtitle", "text": "Build habits that stick", "target_languages": ["de-DE", "ja", "es-MX"]}' \
"https://appdrift-backend-1fabfc95f592.herokuapp.com/v1/translate"Rate limits
Per API key: 300 requests / 15 min overall, and 30 / 15 min on the AI endpoints. Screenshot creation and export receipts share a limit of 20 writes per 15 minutes. Standard RateLimit-* headers tell you where you stand.
3. Webhooks
Don't want to poll? AppDrift can push events to your own endpoints as they happen. Add up to 5 endpoints from the Developers area of your dashboard — available on every paid plan.
Events
| Event | Fires when |
|---|---|
| keyword.rank_change | Keyword rank threshold crossed |
| monitoring.alert | Store monitoring alert |
| action_plan.ready | Weekly Autopilot plan ready |
Payload
Every delivery is a POST with a JSON envelope:
{
"id": "evt_9f2c1a7d3b",
"type": "keyword.rank_change",
"created_at": "2026-08-03T09:00:00.000Z",
"data": { /* event-specific payload */ }
}Verifying signatures
Each endpoint gets a signing secret (whsec_…) shown exactly once at creation. Every delivery carries an X-AppDrift-Signature header in the form t=<unix>,v1=<hex>. Recompute the HMAC-SHA256 of `${t}.${rawBody}` with your secret, compare with a timing-safe compare, and reject anything whose timestamp is more than 5 minutes old:
const crypto = require("crypto");
// signatureHeader = req.headers["x-appdrift-signature"] → "t=1722672000,v1=abc123…"
// rawBody must be the exact raw request body string, not re-serialized JSON.
function verifyAppDriftSignature(rawBody, signatureHeader, secret) {
const parts = Object.fromEntries(
signatureHeader.split(",").map((kv) => kv.split("="))
);
const t = Number(parts.t);
// Reject stale timestamps (replay protection): older than 5 minutes.
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest("hex");
const provided = parts.v1 || "";
// Compare decoded bytes; malformed hex would otherwise truncate or throw.
const a = Buffer.from(expected, "hex");
const b = Buffer.from(provided, "hex");
if (a.length !== b.length) return false;
try {
return crypto.timingSafeEqual(a, b);
} catch {
return false;
}
}Retries & auto-disable
- 4 attempts per event: immediate, then +1 minute, +10 minutes, and +60 minutes. A 2xx response counts as delivered; anything else (or a timeout) schedules the next retry.
- Auto-disable: after 20 consecutive failed deliveries the endpoint is disabled. Fix your receiver, then re-enable it from the Developers page — a “Send test” button lets you verify before real events flow again.
- Limits: up to 5 endpoints per account, each subscribed to any subset of the events above.
Notes
- Never store-direct. AI endpoints return proposals or write to your app's draft version inside AppDrift — nothing reaches the App Store or Play Store without your normal review → publish flow.
- Charge on success. AI endpoints check your token balance up front and only consume tokens when the call returns a result. Failed calls never charge.
- Tenant-scoped. A key only ever sees the account it was created in. Revoke a key any time from the Developers page.
- Cached where it helps. Keyword difficulty is served from a shared cache when fresh and computed live otherwise — the
sourcefield tells you which.
Ready to build?
Grab a key and wire AppDrift into your agent in a couple of minutes.
Create an API keyMCP and API FAQ
How do I connect App Store Optimization data to Claude?
Create an AppDrift API key and use the versioned appdrift-mcp 0.5.0 archive in the configuration below. Node.js 22 or later is required. The official MCP registry listing is still pending.
Can an AI agent change my app store listing through AppDrift?
Not directly. Reading endpoints consume no AI tokens; API access requires an eligible paid plan. The AI endpoints (keyword optimization, metadata generation, translation) return proposals or apply them to your app's draft version inside AppDrift — everything still goes through your normal review and publish flow before anything reaches the store. AI endpoints consume plan tokens and only charge on success.
What does an AppDrift API key cost?
API access is included on eligible paid AppDrift plans. You can pay now or choose an eligible seven-day Basic or Indie first-subscription trial with a card. Studio has no free trial. Eligible new trials bring the available token balance up to 50 once; the full plan allowance arrives after payment. Keyword scores are legacy competition heuristics, not measured search demand or ranking probability.