droidrun-mcp 0.1.3

MCP Server for Droidrun

DroidRun MCP Server

A Model Context Protocol (MCP) server for DroidRun, enabling LLMs (like Claude and Gemini) to control Android devices directly.

Features

• Natural Language Control: "Open Settings and turn on Wi-Fi".
• Visual Understanding: Analyzes screenshots to navigate the UI.
• Trajectory Management: Automatically saves session history and screenshots.
• Safe Execution: Runs locally on your machine.

Prerequisites

• Python 3.10+
• ADB installed and running (adb devices should show your device).
• DroidRun core library (installed in the same environment).

Installation

Option 1: Using uvx (Recommended)

This is the easiest way to run the server without managing virtual environments manually.

uvx droidrun-mcp

Option 2: Using pip

You can also install it directly from PyPI:

pip install droidrun-mcp

Note: Ensure you have ADB installed and your Android device connected.

Option 3: Configure Your Client (Easiest setup)

Add the server to your MCP client configuration (e.g., claude_desktop_config.json or Gemini CLI config or Codex CLI config).

Important: You must provide your API keys and (optionally) configuration paths via environment variables.

{
  "mcpServers": {
    "droidrun": {
      "command": "uvx",
      "args": [
        "droidrun-mcp"
      ],
      "env": {
        "GOOGLE_API_KEY": "your-key-here",
        "OPENAI_API_KEY": "your-key-here",
        "DROIDRUN_TRAJECTORY_PATH": "~/.droidrun-mcp/trajectories",
        "DROIDRUN_CONFIG_PATH": "~/.droidrun-mcp/config.yaml"
      }
    }
  }
}

[!TIP] We recommend copying the default config.yaml to ~/.droidrun-mcp/config.yaml so you can customize it easily.

Environment Variables

Variable	Description	Default
DROIDRUN_TRAJECTORY_PATH	Where to save logs/screenshots.	~/.droidrun-mcp/trajectories
DROIDRUN_CONFIG_PATH	Path to a custom config.yaml.	config.yaml (in package)
GOOGLE_API_KEY	Required for Gemini models.	-
OPENAI_API_KEY	Required for OpenAI models.	-

Available Tools

• execute_task(instruction): Executes a natural language command on the device.
  • instruction: "Open YouTube and search for cats"
  • apk_path: (Optional) Only for testing specific APKs.
• get_trajectory(session_id): Retrieves the event log for a session.
• get_screenshots(session_id): Gets screenshots from a session.
• get_single_screenshot(session_id, step): Gets a specific screenshot.

Development

To contribute to this project:

1. Clone the repo:

   git clone https://github.com/droidrun/droidrun-mcp.git
   

2. Install dependencies:

   uv sync --all-extras
   

3. Run locally:

   fastmcp run droidrun_mcp/server.py