droidrun-mcp 0.1.2

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 (Development)

Since this package is currently in development, you will run it from the source code.

1. Clone the repository:

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

2. Install dependencies: Using uv (recommended) or pip:

   # Install with uv (including google/anthropic support)
   uv pip install -e ".[google,anthropic]"
   
   # OR using pip
   pip install -e ".[google,anthropic]"
   

   Note: Ensure droidrun is also installed or accessible in your environment.

Usage

1. Run the Server

You can run the server directly using fastmcp:

fastmcp run droidrun-mcp/server.py

2. Configure Your Client

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

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

{
  "mcpServers": {
    "droidrun": {
      "command": "/path/to/your/venv/bin/fastmcp",
      "args": [
        "run",
        "/absolute/path/to/droidrun-mcp/droidrun-mcp/server.py"
      ],
      "env": {
        "GOOGLE_API_KEY": "your-key-here",
        "OPENAI_API_KEY": "your-key-here",
        "DROIDRUN_TRAJECTORY_PATH": "~/.droidrun-mcp/trajectories"
      }
    }
  }
}

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 verify the server without a client, you can run the test script:

python3 droidrun-mcp/test_client.py

Future Plans

• PyPI Publishing: We plan to publish this package to PyPI soon. Once published, you will be able to run it directly with uvx:

  uvx droidrun-mcp
  

  Configuration will look like this:

  {
    "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": "/path/to/your/config.yaml"
        }
      }
    }
  }
  

• Docker Support: A Docker container will be provided for easier deployment.