# DroidRun MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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**:
    ```bash
    git clone https://github.com/droidrun/droidrun-mcp.git
    cd droidrun-mcp
    ```

2.  **Install dependencies**:
    Using `uv` (recommended) or `pip`:
    ```bash
    # 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`:

```bash
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.

```json
{
  "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:

```bash
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`:
    ```bash
    uvx droidrun-mcp
    ```

    Configuration will look like this:
    ```json
    {
      "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.
