AI agents and MCP

Give Claude, ChatGPT, Cursor, VS Code, Gemini CLI or any MCP client the ability to see and use an Android phone through droidline mcp, with setup for each client and tips for good results.

MCP (Model Context Protocol) is the standard way AI assistants use outside tools. droidline mcp is an MCP server: once your assistant is connected to it, the assistant can look at a phone's screen and tap, type and scroll on it, using the same commands you would use in a script.

How it works

  • Every Droidline command becomes a tool with the same name. Dotted names use an underscore: chrome.go is chrome_go.
  • dump returns a compact screen tree with empty fields removed, so it costs the model fewer tokens.
  • screenshot returns an image the model can see.
  • The server tells the agent how to work: look with dump, act on elements by text, id or desc, and use coordinates only on screens without elements.
  • For Wi-Fi, mobile data and airplane mode, the server tells the agent to open the Settings page with intent and press the switch in a batch with cuts_network=true and wait=true, so the phone finishes on its own while it is offline.
  • If droidline serve is not running, droidline mcp starts one inside its own process. You still need to pair phones once with droidline pair.

Set up your client

Use the tab for your assistant. In every case the command is droidline mcp; if droidline is not on your PATH, use the full path to the program instead, such as C:\\Tools\\droidline\\droidline.exe (backslashes doubled inside JSON).

Open Settings, Developer, Edit Config, or edit the file directly:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "droidline": { "command": "droidline", "args": ["mcp"] }
  }
}

Restart Claude Desktop. The Droidline tools appear in the tools menu of a new chat.

In the ChatGPT desktop app, open Settings, MCP servers, Add server. Enter droidline as the name, choose STDIO, enter droidline as the command and mcp as the argument, then save and select Restart.

The ChatGPT desktop app, the Codex CLI and the Codex IDE extension share one configuration, so you can also add the server from a terminal:

codex mcp add droidline -- droidline mcp

or write it into ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml):

[mcp_servers.droidline]
command = "droidline"
args = ["mcp"]

ChatGPT in a web browser does not read this local configuration, so use the desktop app or Codex.

claude mcp add droidline -- droidline mcp

Then start claude and ask it to look at your phone. claude mcp list shows whether the server is connected.

Add this to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:

{
  "mcpServers": {
    "droidline": { "command": "droidline", "args": ["mcp"] }
  }
}

Open Cursor's settings, MCP, and check that droidline is listed and enabled.

Add this to .vscode/mcp.json in your workspace:

{
  "servers": {
    "droidline": { "type": "stdio", "command": "droidline", "args": ["mcp"] }
  }
}

Start the server from the code lens that appears above it, then use the tools in Copilot's agent mode.

gemini mcp add -s user droidline droidline mcp

-s user adds it for every project; leave it out to add it to the current project only. You can also write it into ~/.gemini/settings.json:

{
  "mcpServers": {
    "droidline": { "command": "droidline", "args": ["mcp"] }
  }
}

Inside Gemini CLI, /mcp shows whether the server is connected and lists its tools.

In AI Assistant, open Settings, Tools, AI Assistant, Model Context Protocol (MCP) and click Add. Choose the STDIO connection and paste this into JSON configuration:

{
  "mcpServers": {
    "droidline": { "command": "droidline", "args": ["mcp"] }
  }
}

Click OK, then Apply to start the server. The Status column shows whether it connected.

Open Settings, AI, MCP Servers, click Add Server and choose Add Local Server, or add this to Zed's settings.json:

{
  "context_servers": {
    "droidline": { "command": "droidline", "args": ["mcp"], "env": {} }
  }
}

A green dot next to droidline in MCP Servers means the server is active.

Any MCP client that can start a server over standard input and output works. Configure it to run:

droidline mcp

with no environment variables required. Settings such as DROIDLINE_DEVICE and DROIDLINE_TOKEN are read if present.

Choosing a phone

With one phone online, the agent uses it. With several, the agent calls devices and passes a device to each tool. To make one phone the default, add --device. The agent can still name another phone in a tool call, so it is a default, not a limit:

{
  "mcpServers": {
    "droidline": { "command": "droidline", "args": ["mcp", "--device", "shelf-01"] }
  }
}

Two entries with different names and devices let one assistant use two phones by name.

Asking for good results

Agents do best with a clear goal and a way to check it. Some prompts that work well:

  • "Open Settings on my phone and tell me which Wi-Fi network it is connected to."
  • "In the demo app, sign in as knife, then read me the balance on the main screen."
  • "Take a screenshot, find the button that dismisses this pop-up, and tap it."
  • "Write a Python script that does what you just did, using the droidline package."

The last one is a good habit: let the agent explore a new app once, then turn what it did into a script you can run without it.

Limit what an agent can use

By default every Droidline command is a tool, except sms, calls and contacts, which an agent only gets when --tools names them. Two options, available from version 0.1.6, narrow that down:

  • --tools lists the only tools the agent sees and can call. A call to any other tool is refused, and a misspelled name stops droidline mcp from starting.
  • --read-only keeps only the tools that look at the phone, such as dump, screenshot, ocr, exists and notifications. Nothing that taps, types, opens an app or changes a setting is left.
{
  "mcpServers": {
    "droidline-look": { "command": "droidline", "args": ["mcp", "--read-only"] },
    "droidline-tap": { "command": "droidline", "args": ["mcp", "--tools", "dump,screenshot,touch"] }
  }
}

With both options, a tool has to pass each. Steps inside a batch are checked the same way, so batch can't run a tool the agent was not given. The agent can't change these options, because they are part of how your client starts droidline mcp. Commands that pair, rename or revoke phones are never tools.

Be careful with what you connect

An agent connected to droidline mcp can do anything you could do on the phone, including sending messages and changing settings. Droidline can't tell a harmless button from one that sends or pays, so an agent that can call touch can press either. Use a test phone or a phone without personal accounts while you try things out, give the agent only the tools the task needs, and keep the per-tool confirmation in your client turned on for commands that change data, such as clear_data, input and notification_reply.