Android MCP Server for Windsurf: Setup & Config

What you can do with Android in Windsurf

Pick it for direct ADB access paired with screenshot and clickable-UI inspection.

• Capture device screenshots for assistant review
• Run ADB commands from an MCP client

Before you start: Android in Windsurf

• Python 3.x; setup example installs 3.11
• uv
• ADB installed and configured
• An Android device; emulator support is untested

Replace both path placeholders. Clone the repository and run uv sync first. Select a device in config.yaml when more than one is attached.

Android Windsurf configuration

1. Choose Windsurf configuration scope

   For Android MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Android MCP Server to Windsurf

   Use the android-mcp-server entry below in mcpServers. Keep Android MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check Android MCP Server in Windsurf

   Android MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "android-mcp-server": {
      "command": "path/to/uv",
      "args": [
        "--directory",
        "path/to/android-mcp-server",
        "run",
        "server.py"
      ],
      "env": {}
    }
  }
}

Android tools available to Windsurf

Android's stored tool list documents 5 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

get_packages

After refreshing Android in Windsurf settings, check Cascade's tool list for get_packages.

List packages installed on the selected device.

execute_adb_command

After refreshing Android in Windsurf settings, check Cascade's tool list for execute_adb_command.

Run an ADB command and return its output.

get_uilayout

After refreshing Android in Windsurf settings, check Cascade's tool list for get_uilayout.

get_screenshot

After refreshing Android in Windsurf settings, check Cascade's tool list for get_screenshot.

get_package_action_intents

After refreshing Android in Windsurf settings, check Cascade's tool list for get_package_action_intents.

Retrieve non-data activity actions for a package.

Android: full stored tool descriptions

Troubleshooting Android in Windsurf

• Check uv on the machine running Windsurf's MCP integration for Android MCP Server; refresh MCP and inspect Cascade's tools.
• Android MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Emulator use is marked untested
• Known limitation: Requires ADB installation and a connected device
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions