AkaPhoneDocs
Get started

Quickstart with Claude Code

Give Claude Code a cloud Android phone in two minutes with the AkaPhone MCP server.

View as Markdown

The AkaPhone MCP server (akaphone-mcp on npm) runs locally next to Claude Code over stdio and turns AkaPhone into 13 tools: create a device, run a task on it, install an APK, tap and type, take a screenshot, snapshot it, and so on. Claude decides when to call them.

You need Node.js 20 or newer (for npx) and Claude Code.

1. Get an API key#

  1. Open https://akaphone.abhgnx-417.workers.dev and sign in with Google. New accounts start with 60 free credit minutes.
  2. Go to API keys and click Create key. Give it a name such as laptop-claude-code.
  3. Copy the secret. It looks like ak_live_urQuj41lKvo2VYp2kBoFqRGw5ig661RoAtM5uTvyrhB and is shown only once. If you lose it, revoke it and create another.

2. Get a model key#

Tasks are run by the ARTEMIS agent on the device host, and ARTEMIS calls a model with your key. The MCP server sends it with each task as the X-Model-Key header. AkaPhone never stores it. See Model keys.

The default provider is Gemini, so a Google AI Studio key (AIza…) is the quickest start. To use Claude or OpenAI instead, also set MODEL_PROVIDER (below).

3. Add the server#

Shell
claude mcp add akaphone \
  -e AKAPHONE_API_KEY=ak_live_... \
  -e MODEL_API_KEY=AIza... \
  -- npx -y akaphone-mcp

That registers a stdio server named akaphone for the current project. Add --scope user after add to make it available in every project.

Variable Required What it does
AKAPHONE_API_KEY yes Your ak_live_… key. The server exits at startup without it.
AKAPHONE_API_URL no Defaults to https://akaphone.abhgnx-417.workers.dev.
MODEL_API_KEY for tasks Your model provider key, sent per task as X-Model-Key. Without it, device_run_task has no model to use.
MODEL_PROVIDER no gemini (default), anthropic or openai. Sent as X-Model-Provider. Any other value stops the server at startup.

Check it is connected: run claude mcp list in a terminal, or type /mcp inside Claude Code. The akaphone server should be listed as connected.

4. First prompts to try#

Start a new Claude Code session and paste one of these:

Create a phone, open Settings > About phone and tell me the Android version and build number. Then terminate the phone.

Create a phone called "checkout-test". Open Chrome, go to example.com and take a screenshot. Leave the phone running.

List my phones and how many minutes I have used this month.

Install ./app/build/outputs/apk/debug/app-debug.apk on checkout-test, open the app and tell me what the first screen says.

On checkout-test, save a snapshot called "chrome-ready", then terminate it.

What happens#

For the first prompt, Claude typically makes three tool calls:

  1. device_create boots a new Android 14 device and waits until it is running (up to 90 seconds; usually much faster when a slot is warm). Billing starts when the device is ready, at 1 credit per started minute.
  2. device_run_task with an instruction like “Open Settings > About phone and read the Android version and build number”. ARTEMIS drives the phone step by step. The tool polls every 3 seconds and returns the finished task, including result (the agent's answer), status and step_count. While it runs, you can watch the screen live: open the device in the dashboard.
  3. device_terminate stops the device. Billing stops with it.

Every tool and its arguments are listed in the MCP tools reference.

Troubleshooting#

The server does not show up in /mcp, or shows as failed. Run npx -y akaphone-mcp in a terminal with AKAPHONE_API_KEY set. If it prints AKAPHONE_API_KEY is required, the -e flag did not reach the server: remove it with claude mcp remove akaphone and add it again, keeping -- before npx.

AkaPhone API 401 or unauthorized. The key is wrong or revoked. Keys start with ak_live_. Check the key list in the dashboard; revoked keys disappear from it.

Requests fail to connect or return unexpected 404s. Check you are on akaphone-mcp 1.0.0 or later (npx -y akaphone-mcp fetches the latest). Versions before 1.0.0 defaulted to an older API host; with those, set -e AKAPHONE_API_URL=https://akaphone.abhgnx-417.workers.dev. If you set AKAPHONE_API_URL yourself, it must be exactly https://akaphone.abhgnx-417.workers.dev, with no path.

402 insufficient_credits. Your balance is below 1 credit. Buy a pack on the Billing page.

409 concurrency_limit. You already have as many devices as your plan allows (1 on Free). Ask Claude to list and terminate devices you no longer need, or stop them in the dashboard.

The task fails straight away, or the result mentions an API key. MODEL_API_KEY is missing, invalid, or for a different provider than MODEL_PROVIDER. If the server will not start and its log says MODEL_PROVIDER must be one of gemini, anthropic, openai, fix the variable and add the server again.

409 conflict: Device already has an active task. One task runs per device at a time. Wait for the current one or cancel it in the dashboard.

device_create returns a device that is still queued or creating. The 90-second wait ran out because no slot was free right away; the tool result says so. Ask Claude to check the device again in a minute. A device that cannot be placed within 10 minutes ends in error with no_capacity and is never billed.