MCP Integration

Control your Android phone from Claude Desktop, Cursor, or any MCP-compatible AI client.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI models interact with external tools and services. ScreenMCP exposes a set of phone-control tools through an MCP-compatible HTTP endpoint, allowing AI assistants like Claude to take screenshots, tap buttons, type text, and navigate your Android phone.

ScreenMCP uses the Streamable HTTP transport, which means the MCP server runs as a standard HTTP endpoint -- no stdio process or extra binary required. You just point your MCP client at the URL with your API key and start using the tools.

Quick Start

Get an API Key

Sign in to the Dashboard, then create an API key in the API Keys section. Copy the key -- it starts with pk_ and will only be shown once.

Connect Your Phone

Install the ScreenMCP Android app, sign in with the same Google account, and ensure the phone is connected (the app will show a green "Connected" indicator). The Accessibility Service must be enabled for UI automation to work.

Configure Your MCP Client

Add ScreenMCP to your MCP client configuration. See the examples below for Claude Desktop and other clients.

Endpoint

URL

POST https://mcp.screenmcp.com/mcp

Authentication

Authorization: Bearer pk_your_api_key_here

Transport

Streamable HTTP (as defined by the MCP specification). The client sends JSON-RPC requests via POST and receives responses in the same HTTP response. No SSE or WebSocket upgrade is needed from the client side.

Configuration Examples

Claude Desktop

Open Claude Desktop settings, navigate to the MCP section, and add a new server. Edit the configuration file (claude_desktop_config.json) to include:

claude_desktop_config.json

{
  "mcpServers": {
    "screenmcp": {
      "type": "streamable-http",
      "url": "https://mcp.screenmcp.com/mcp",
      "headers": {
        "Authorization": "Bearer pk_your_api_key_here"
      }
    }
  }
}

Claude Code (CLI)

Add the MCP server using the Claude Code CLI:

Terminal

claude mcp add screenmcp \
  --transport streamable-http \
  --url "https://mcp.screenmcp.com/mcp" \
  --header "Authorization: Bearer pk_your_api_key_here"

Cursor

In Cursor settings, go to the MCP tab and add a new server with the Streamable HTTP transport:

.cursor/mcp.json

{
  "mcpServers": {
    "screenmcp": {
      "type": "streamable-http",
      "url": "https://mcp.screenmcp.com/mcp",
      "headers": {
        "Authorization": "Bearer pk_your_api_key_here"
      }
    }
  }
}

Custom MCP Client

For any MCP client that supports the Streamable HTTP transport, use these parameters:

Server URL:    https://mcp.screenmcp.com/mcp
Transport:     Streamable HTTP (POST)
Auth Header:   Authorization: Bearer pk_your_api_key_here

Available Tools

ScreenMCP exposes 15 tools for controlling your Android phone. When connected, these tools appear automatically in your MCP client.

screenshot

Take a screenshot of the phone screen. Returns a base64-encoded WebP image.

Parameter	Type	Description
`quality`optional	number	Image quality 1-100 (default: 100 = lossless)
`max_width`optional	number	Max width for scaling
`max_height`optional	number	Max height for scaling

ui_tree

Get the accessibility tree of the current screen. Returns an array of UI nodes with bounds, text, clickable state, and more.

click

Tap on the screen at the given coordinates.

Parameter	Type	Description
`x`	number	X coordinate
`y`	number	Y coordinate
`duration`optional	number	Press duration in ms (default: 100)

long_click

Long press at coordinates for 1000ms.

Parameter	Type	Description
`x`	number	X coordinate
`y`	number	Y coordinate

scroll

Scroll the screen with a finger-drag gesture from (x, y) by (dx, dy).

Parameter	Type	Description
`x`	number	Start X
`y`	number	Start Y
`dx`	number	Horizontal delta
`dy`	number	Vertical delta (negative = scroll content up)

drag

Drag from one point to another on the screen.

Parameter	Type	Description
`startX`	number	Start X coordinate
`startY`	number	Start Y coordinate
`endX`	number	End X coordinate
`endY`	number	End Y coordinate
`duration`optional	number	Duration in ms (default: 300)

type

Type text into the currently focused input field.

Parameter	Type	Description
`text`	string	Text to type

get_text

Get text from the currently focused input field.

select_all

Select all text in the currently focused field.

copy

Copy the currently selected text to the clipboard.

paste

Paste clipboard contents into the focused field.

back

Press the Android back button.

home

Press the Android home button.

recents

Open the recent apps view.

camera

Take a photo using the phone camera. Returns a base64-encoded WebP image.

Parameter	Type	Description
`camera`optional	"0" \| "1"	Camera ID: "0" = rear (default), "1" = front
`quality`optional	number	Image quality 1-100 (default: 80)
`max_width`optional	number	Max width for scaling
`max_height`optional	number	Max height for scaling

How It Works

MCP Client (Claude Desktop, Cursor, etc.)
    |
    |  POST /mcp  (Streamable HTTP + JSON-RPC)
    v
ScreenMCP MCP Server  (mcp.screenmcp.com)
    |
    |  Authenticates via API key
    |  Discovers the worker server holding your phone connection
    |  Connects via WebSocket to the worker
    v
Worker  (Rust relay)
    |
    |  Forwards command over existing WebSocket
    v
Phone  (Android app)
    |
    |  Executes command via AccessibilityService
    |  Returns result (screenshot, UI tree, status, etc.)
    v
Response flows back through the same chain

Each MCP tool call triggers a command that flows through the ScreenMCP infrastructure to your connected phone. The phone executes the command using Android's Accessibility Service and returns the result. Screenshots and camera images are returned as base64-encoded WebP.

Troubleshooting

"Authentication failed" or 401 errors

Ensure your API key is correct and prefixed with pk_. The Authorization header must be Bearer pk_... (with a space after Bearer). You can create a new key from the Dashboard if needed.

Tool calls fail with "no phone connected"

Make sure the ScreenMCP Android app is open and showing "Connected". The phone must be signed in with the same account that owns the API key. Check that the Accessibility Service is enabled in Android Settings.

Screenshots return errors

If the phone is locked (keyguard active), screenshots will fail. Unlock the phone and try again. Also ensure the screen capture permission has been granted in the app.

Client does not show ScreenMCP tools

Verify that your MCP client supports the Streamable HTTP transport. Some older clients only support stdio. Check that the URL is reachable from your machine (try curl -X POST https://mcp.screenmcp.com/mcp -H "Authorization: Bearer pk_...").

Commands feel slow

The first command in a session takes 2–4 seconds because the phone needs to wake up and connect. Subsequent commands are faster (screenshots ~0.5–1.5s, taps ~200–400ms). Use quality: 60 and max_width: 720 for faster screenshots. See the Performance & Latency guide for detailed benchmarks and optimization tips.