MCP setup

Quick start

1. Open Settings > MCP in the Emu GUI.
2. Click Add to config next to your AI tool (Cursor, Claude Code, OpenCode, etc.).
3. Restart your AI tool — it now has access to all connected Android devices.

Emu’s MCP server can run in two modes: embedded inside the GUI, or as a standalone headless daemon.

Headless daemon

Use this when you want the MCP server running without the GUI — for example, in a CI environment or when you only need AI agent access.

emu mcp

This starts a background daemon (if one isn’t already running) and prints the connection URL. The daemon runs independently and persists until you stop it with emu stop.

GUI-embedded server

When you run the full Emu GUI, you can start the MCP server from Settings > MCP. The server runs inside the GUI process — no separate daemon needed. This is the recommended mode for day-to-day development because you get both the visual interface and AI agent access at the same time.

Auto-configuration

From Settings > MCP, Emu detects installed MCP clients and can inject the server configuration with one click.

1. Emu shows the status of each detected client — Configured, Not Configured, or Not Installed.
2. Click Add to config next to any client to write the Emu server entry into its configuration file.

Supported clients: Claude Code, Cursor, Windsurf, Cline, OpenCode, Zed.

Caution

Claude Desktop does not support HTTP-based MCP servers directly. It requires the npx mcp-remote bridge. Emu shows the correct configuration snippet in the settings screen, but you need to paste it manually.

Manual configuration

If you prefer to configure manually, add the Emu server to your client’s MCP config:

{
  "mcpServers": {
    "emu": {
      "url": "http://127.0.0.1:8565/mcp"
    }
  }
}

The exact format varies by client — Windsurf uses serverUrl, Cline uses type: "streamableHttp", Zed uses context_servers. The auto-configuration handles these differences for you.

Daemon lifecycle

These commands apply to the headless daemon mode.

emu mcp             # Start daemon (if needed) and print URL
emu mcp             # Reuses existing daemon — idempotent
emu stop            # Graceful shutdown
emu mcp --port 9000 # Custom port

The daemon follows the adb pattern: probe the port, spawn a detached process if nothing is listening, wait for readiness, then print the URL.

Security

The MCP server binds to 127.0.0.1 (localhost) only. DNS rebinding protection rejects requests with non-localhost Host headers. No bearer token is required — same trust model as adb, the Docker socket, and Chrome DevTools.