adb-mcp

Go-based MCP server scaffold for orchestrating Android adb commands. The initial drop focuses on configuration, logging, and lifecycle wiring so new MCP tools and resources can be layered in next.

Getting Started

go build ./cmd/adb-mcp
./adb-mcp -config path/to/config.json

The binary runs as a long-lived process (stdio MCP transport placeholder) and terminates via Ctrl+C/SIGTERM.

Using the stdio MCP transport

The server now speaks the Model Context Protocol over newline-delimited JSON on stdin/stdout:

1. Launch ./adb-mcp (optionally piping into a supervising IDE/tool).
2. Send an initialize request (JSON-RPC 2.0) specifying protocol version 2025-03-26 (or 2024-11-05 for older clients).
3. After receiving the initialize result, send tools/list and tools/call requests to enumerate and invoke the built-in adb helpers described below.

The transport enforces the MCP handshake, responds to ping, and returns structured content arrays for every tool invocation. All requests must be JSON-RPC objects separated by newlines; batches are supported when the client sends an array.

Configuration

Configs are optional JSON files; unspecified values fall back to sane defaults.

{
  "adb_path": "/usr/local/bin/adb",
  "command_timeout": "45s",
  "logging": {
    "directory": "~/adb-mcp/logs",
    "file_name": "adb-mcp.log",
    "level": "debug",
    "also_console": true
  },
  "mcp": {
    "transport": "stdio"
  }
}

Key defaults:

• adb_path: adb (resolved via PATH)
• logging.directory: $HOME/.adb-mcp/logs
• logging.file_name: adb-mcp.log
• logging.also_console: false (logs go to file by default)
• command_timeout: 30s
• mcp.transport: stdio

Logging

The server uses zerolog with structured JSON entries. By default logs are written to $HOME/.adb-mcp/logs/adb-mcp.log so long-running commands can flush rich output without flooding stdout. Enable console mirroring with "also_console": true if you need interactive feedback.

Built-in Tools

The MCP registry is pre-populated with high-value device management and UI automation helpers. These surface as MCP tools (and can already be exercised via Server.InvokeTool while the stdio transport is under construction):

• device.list — enumerate adb devices -l output with optional state filter.
• device.connect / device.disconnect — manage TCP/IP or Wi-Fi debugging endpoints (host:port).
• device.reboot — reboot into system, bootloader, recovery, or fastboot.
• ui.tap / ui.swipe — simulate touch interactions; swipe accepts optional duration in milliseconds.
• ui.text — type arbitrary text via adb shell input text, encoding whitespace for reliability.
• ui.keyevent — trigger a keycode (e.g., 3 for KEYCODE_HOME).

All long-running commands stream their stdout/stderr into the zerolog file so Codex/Claude integrations can fetch artifacts without blocking stdin/stdout.