espresso-mcp

An MCP Server for the Espresso Android Test Framework, crafted to improve testing capabilities and optimize development workflows.

Installation

• Python 3.x
• uv: `pip install uv`

# Run in stdio mode
uvx espresso-mcp

# Run in sse mode
uvx espresso-mcp --sse

Usage

• On Github Copilot: Add below JSON config to the file `.vscode/mcp.json`

{
  "servers": {
    "espresso-mcp": {
      "command": "uvx",
      "args": ["espresso-mcp"],
      "env": {}
    }
  }
}

• On Claude: Add below JSON config to the file `claude_desktop_config.json`

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["espresso-mcp", "--timeout-ms", "30000"]
    }
  }
}

• Using OpenAI SDK

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "mcp",
            "server_label": "espresso-mcp",
            "server_url": "http://localhost:8000/sse",
            "require_approval": "never",
        },
    ],
    input="Open Teams App",
)

print(resp.output_text)

Available Tools

The following tools are available in the `espresso-mcp` project:

• list_avds: List all available Android Virtual Devices (AVDs).
• list_emulators: List all running Android Emulators.
• start_emulator: Start an Android Emulator by name.
• kill_emulator: Kill a specific Android Emulator.
• dump_ui_hierarchy: Dump the UI hierarchy of the connected Android device.
• open_uri: Open a URI on the connected Android device.
• list_apps: List all installed apps on the connected Android device.
• install_app: Install an APK on the connected Android device.
• start_app: Start a specific app on the connected Android device.
• stop_app: Stop a specific app on the connected Android device.
• uninstall_app: Uninstall an app from the connected Android device.
• clear_app_data: Clear app data for a specific app on the connected Android device.
• take_screenshot: Take a screenshot of the connected Android device.
• record_screen: Record the screen of the connected Android device for a specified duration.
• press_button: Simulate a button press on the connected Android device.
• type_text: Type text on the connected Android device.
• clear_and_type_text: Clear all text and type new text on the connected Android device.
• replace_text: Replace text by clearing current text and typing new text on the connected Android device.
• tap: Simulate a tap on the connected Android device at specific coordinates.
• swipe: Perform a swipe gesture in a specific direction on the connected Android device.
• dump_current_activity: Dump the current activity name of the connected Android device.

Resources

The following resources are available:

• config://app: Retrieve static configuration data.
• greeting://{name}: Get a personalized greeting.

Local Setup

• Python 3.x
• uv: `pip install uv`

# Install dependencies
uv sync
# OR
uv sync --frozen --all-extras --dev

# Run Server
uv run espresso-mcp

# Run in Dev Mode
uv run mcp dev src/espresso_mcp/server.py

Debugging

• Use MCP Inspector

# Install MCP Inspector
yarn global add @modelcontextprotocol/inspector

# Test MCP Server
yarn run @modelcontextprotocol/inspector python server.py

Linting and Testing

# Lint
uv run ruff check

# Tests
uv run pytest

Publishing

# Build the package
uv build
uv build --wheel
uv build --no-sources

# Upload to PyPI
uv publish

Developement Notes

uv tool install espresso-mcp

# OR

uvx espresso-mcp

uv init espresso-mcp

uv add "mcp[cli]"

uv run mcp dev server.py

uv tool run espresso-mcp

uv run pre-commit install

pre-commit run --all-files