Skip to documentation

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 →

Keyword scores

Read legacy competition heuristics; these do not measure keyword demand or predict ranking.

Rank tracking

Read an app's tracked keywords and their latest store rank.

Keywords to review

Tracked keywords ranked 11–30, ordered by the legacy difficulty heuristic.

Weekly action plan

This week's prioritized ASO actions across all your apps.

One-click optimize

AI-rewrite title/subtitle/keywords toward a target keyword — with an apply step.

Screenshot campaigns

Create editable projects from real captures, preview screens and export store-sized PNGs. No AppDrift AI tokens.

Generate & translate

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.

MCP configuration — screenshots in 0.5.0
{
  "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" }
    }
  }
}

Upgrading an existing client? Use 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:

ToolWhat it does
keyword_difficultyLegacy competition heuristics, not search volume or ranking probability. No AI tokens.
list_appsList apps connected to your account. Free.
app_keywordsAn app's tracked keywords with latest rank. Free.
app_opportunitiesReview candidates ranked 11–30. No AI tokens.
action_planThis week's prioritized ASO actions. Free.
account_statusPlan + remaining token balance. Free.
optimize_for_keywordAI-rewrite toward a target keyword. 3 tokens, charged on success.
apply_optimizationWrite accepted fields to the app's draft version. Free.
generate_metadataGenerate ASO metadata from a brief. 1 token/field (2 for long fields).
screenshot_optionsStyles, device sizes and browser setup. No account needed.
create_screenshot_projectSave an editable project from 3–8 local captures and supplied captions. Paid API access; no AI tokens.
list_screenshot_projectsRecent projects created through MCP. No AI tokens.
preview_screenshot_projectReturn one 480px preview image. No AI tokens.
export_screenshot_projectWrite RGB PNGs to a new local folder and record completion. No AI tokens.
translate_metadataTranslate 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:

Screenshot browser setup
npx -y https://appdrift.co/downloads/appdrift-mcp-0.5.0.tgz --install-browser

Node.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.

Example prompt
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:

Base URL
https://appdrift-backend-1fabfc95f592.herokuapp.com

Authenticated request
curl -H "Authorization: Bearer ad_live_your_key_here" \
  "https://appdrift-backend-1fabfc95f592.herokuapp.com/v1/apps"

Endpoints

GET/v1/keyword-difficulty
Read legacy competitor-based keyword scores. These are not measured search demand or ranking probability. Query params: keyword (required), platform (ios|android, default ios), country (default us).
Code example
curl -H "Authorization: Bearer ad_live_..." \
  "https://appdrift-backend-1fabfc95f592.herokuapp.com/v1/keyword-difficulty?keyword=meditation&platform=ios&country=us"

Response
{
  "data": {
    "keyword": "meditation",
    "platform": "ios",
    "country": "us",
    "difficulty": 63,
    "popularity": 41,
    "source": "live"
  }
}

GET/v1/apps
List the apps connected to your account. Use an id below with the app-scoped endpoints.
GET/v1/apps/:id/keywords
An app's tracked keywords, each with its latest store rank (null = outside the tracked range).
GET/v1/apps/:id/opportunities
Tracked keywords ranked 11–30, ordered by the legacy difficulty heuristic. Review their relevance and current listing before choosing a change; the order does not predict gains or ROI.
GET/v1/action-plan
This week's prioritized ASO action plan across all apps — keyword pushes, rank drops, review themes, competitor overtakes, and localization gaps. As in the dashboard, a workspace without a paid plan or trial reads the first open action; the others arrive with locked: true and a placeholder in place of the action and detail.
GET/v1/me
Key introspection: plan name + remaining token balance. Use it to check affordability before calling an AI endpoint.

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.

POST/v1/apps/:id/optimize
One-click keyword optimization — AI-rewrites title/subtitle/keywords toward a target keyword and returns a before/after diff with rationale. Body: keyword (required), country. Costs 3 tokens.
Code example
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"

POST/v1/apps/:id/optimize/apply
Write accepted proposal fields into the app's editable draft version (free — the rewrite was already paid for). Everything still goes through your normal review → publish flow. Body: fields (object from the optimize response's proposed).
POST/v1/generate-metadata
Generate ASO metadata from an app brief. Body: 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.
Code example
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"

POST/v1/translate
Translate one metadata field into up to 15 languages with ASO-aware localization. Body: 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).
Code example
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

EventFires when
keyword.rank_changeKeyword rank threshold crossed
monitoring.alertStore monitoring alert
action_plan.readyWeekly Autopilot plan ready

Payload

Every delivery is a POST with a JSON envelope:

Webhook payload
{
  "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:

verify.js (Node)
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 source field tells you which.

Ready to build?

Grab a key and wire AppDrift into your agent in a couple of minutes.

Create an API key

MCP 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.