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.goischrome_go. dumpreturns a compact screen tree with empty fields removed, so it costs the model fewer tokens.screenshotreturns an image the model can see.- The server tells the agent how to work: look with
dump, act on elements bytext,idordesc, 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
intentand press the switch in abatchwithcuts_network=trueandwait=true, so the phone finishes on its own while it is offline. - If
droidline serveis not running,droidline mcpstarts one inside its own process. You still need to pair phones once withdroidline 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 mcpor 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 mcpThen 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 mcpwith 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:
--toolslists the only tools the agent sees and can call. A call to any other tool is refused, and a misspelled name stopsdroidline mcpfrom starting.--read-onlykeeps only the tools that look at the phone, such asdump,screenshot,ocr,existsandnotifications. 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.