appdrift

# AppDrift MCP Server

Read your AppDrift keyword observations, account apps and action plan from Claude Desktop, Cursor or another MCP client. Generate or translate listing copy, review the result, and apply accepted fields to an editable AppDrift draft. These tools do not publish to Apple or Google.

This package is a small local **stdio** client for the [AppDrift REST API](https://appdrift.co/docs/mcp). It requires **Node.js 22 or later** and an AppDrift API key. API access is available on eligible paid plans. Eligible first subscriptions have a seven-day trial with a card; the trial adds no tokens. [Current plans and token allowances](https://appdrift.co/pricing).

## Install

Add AppDrift to your MCP client's configuration (Claude Desktop, Cursor or another MCP client):

```json
{
  "mcpServers": {
    "appdrift": {
      "command": "npx",
      "args": ["-y", "appdrift-mcp"],
      "env": { "APPDRIFT_API_KEY": "ad_live_your_key_here" }
    }
  }
}
```

1. Create a key in the [Developers dashboard](https://appdrift.co/dashboard/developers).
2. Replace the placeholder in your client's local MCP configuration. Keep the key out of shared configuration and source control.
3. Restart the client. Ask it to call `account_status`, then `list_apps`. These calls consume no AI tokens.
4. Choose the returned app ID before asking for its tracked keywords. Review proposed text before allowing a paid action or a saved-draft change.

On the first run, `npx` downloads the package and its dependencies. If the client cannot find `npx`, use its absolute local executable path.

**Without the npm registry:** AppDrift also hosts the same wrapper as a versioned archive. Use `https://appdrift.co/downloads/appdrift-mcp-0.2.0.tgz` in `args` in place of `appdrift-mcp`, and check it against its [SHA-256 checksum](https://appdrift.co/downloads/appdrift-mcp-0.2.0.tgz.sha256). The archive includes the complete wrapper source and MIT license. `server.json` prepares the official MCP registry entry, which is not published yet.

## Tools and costs

**No additional AI tokens:** API access still requires an eligible account plan.

| Tool | Result |
| --- | --- |
| `keyword_difficulty` | Legacy competitor-based difficulty/popularity heuristics. These are not measured keyword demand or ranking probability. Store collection can fail or be incomplete. |
| `list_apps` | Apps connected to the account, including the ID used by app-scoped tools. |
| `app_keywords` | Tracked keywords and latest observed ranks for the selected app. |
| `app_opportunities` | Tracked keywords ranked 11–30, ordered by the legacy difficulty heuristic; candidates to review, not predicted gains. |
| `action_plan` | The account's prioritized ASO actions. |
| `account_status` | Plan and remaining AI-token balance. |
| `apply_optimization` | **Changes saved content:** applies accepted `title`, `subtitle`, `keywords` or `short_description` fields to the app's editable draft. Review and store publishing remain separate. |

**AI tools:** AppDrift charges for successful processing. Check the returned token charge and account balance. The client never retries these actions automatically.

| Tool | Cost | Result |
| --- | --- | --- |
| `optimize_for_keyword` | 3 tokens | Proposed title/subtitle/keyword changes and rationale. |
| `generate_metadata` | 1 per short field; 2 per long field | Listing fields generated from the app brief. |
| `translate_metadata` | Per language: 1 normally; 3 for `description`; 5 for `full_description` | One field translated into 1–15 distinct locales. |

Paid operations and `apply_optimization` are advertised as writes to MCP clients. A timeout or lost response **does not prove that the server stopped processing or charged nothing**. Check the account and draft before retrying. The client sends your API key and supplied listing text to the configured AppDrift API; AI requests may use the account's configured AI provider.

The legacy `keyword_difficulty` tool is separate from the experimental Keyword analyzer. Its scores do not predict rank, traffic or download gains.

## Configuration

| Environment variable | Required | Default |
| --- | --- | --- |
| `APPDRIFT_API_KEY` | Yes | Create it in the Developers dashboard. |
| `APPDRIFT_API_BASE` | No | AppDrift production API. Change only to an endpoint you trust with the key and listing text. HTTPS required; HTTP permitted only for loopback development. |
| `APPDRIFT_REQUEST_TIMEOUT_MS` | No | `90000`; permitted range `1000`–`120000`. |

The client rejects redirects, bounds response size, validates tool inputs before requests and returns authored error messages instead of provider errors or stack traces. These safeguards do not replace backend authorization or review of an agent's proposed actions.

## Troubleshooting

- **No tools:** confirm Node 22+, `npx` availability and a nonempty `APPDRIFT_API_KEY`. MCP protocol messages use stdout; startup errors use stderr.
- **Invalid or revoked key:** create or select an active key in Developers and update the local config.
- **Insufficient tokens:** inspect `account_status` and current [token options](https://appdrift.co/pricing). A trial itself adds no tokens.
- **No editable draft:** create the app's draft in AppDrift, then apply only the fields you reviewed.
- **No store results:** try again later. A missing score is not zero competition.
- **Timeout after a paid action:** inspect balance and saved state before requesting the action again.

## Development

Within a source checkout, run `npm ci`, `npm test` and `npm run verify:package`. Integration checks launch the actual stdio process against local fixture APIs; they do not use production credentials or spend tokens. Package verification packs only the declared runtime files, installs the archive through a local HTTP URL into a clean directory and runs the integration suite against the installed executable.

## License

MIT. See [LICENSE](./LICENSE).