trace-mcp

A Python MCP server for controlling Android system tracing via a native traceserver binary, supporting device selection and custom port forwarding. Designed for use with the uv/uvx toolchain.

Prerequisites

• Python 3.12+
• uv (for dependency management and running scripts)
• Android Debug Bridge (adb) in your PATH
• Android device (API 21+), with USB debugging enabled
• Prebuilt traceserver binaries in the bin/ directory for all supported ABIs

Installation

uv pip install -e .

Usage

Start the MCP server (with uvx)

uvx trace-mcp --port 12345

• --port (optional): Specify the port for traceserver and forwarding (default: 12345)

MCP Tool Functions

All tool functions accept an optional sn (device serial number) and port argument.

1. begin_trace

Begin a trace section on the device.

• Arguments:
  • trace_tag (str): Trace tag name
  • sn (str, optional): Device serial number
  • port (int, optional): Port (default: 8080)

2. end_trace

End a trace section on the device.

• Arguments:
  • trace_tag (str): Trace tag name
  • sn (str, optional): Device serial number
  • port (int, optional): Port (default: 8080)

3. trace_test_mode

Start traceserver in test mode on the device.

• Arguments:
  • sn (str, optional): Device serial number
  • port (int, optional): Port (default: 8080)

4. stop_traceserver

Stop the traceserver process and remove port forwarding.

• Arguments:
  • sn (str, optional): Device serial number
  • port (int, optional): Port (default: 8080)

Example

uvx trace-mcp --port 9000

Then, use your MCP client to call the tool functions with the appropriate arguments.

Project Structure

• main.py: MCP server and tool function implementations
• bin/: Prebuilt traceserver binaries for each ABI
• pyproject.toml: Project configuration for uv/uvx

License

MIT