Android ADB MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Android devices through the Android Debug Bridge (ADB). This server bridges the gap between AI capabilities and Android device management, allowing for seamless automation of Android development and testing operations.

⚙️ Quick Setup

Add the server to your MCP configuration file:

{
  "mcpServers": {
    "android-adb": {
      "command": "npx",
      "args": ["-y", "@landicefu/android-adb-mcp-server"],
      "env": {},
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Configuration Locations

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Cline/Roo Code: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json (macOS)
• For Windows/Linux, check the equivalent application support directories

After configuring, restart your AI assistant to load the new server configuration.

📋 Prerequisites

• ADB (Android Debug Bridge) must be installed and available in your system PATH
  • Install ADB on Windows, macOS, or Linux
  • Verify installation by running adb version in your terminal
• For clipboard functionality:
  • macOS: osascript (built-in)
  • Windows: PowerShell (built-in)
  • Linux: xclip (install via apt-get install xclip or equivalent)
• Node.js 16.x or higher

🚀 Features

• Connect to and manage multiple Android devices
• Execute shell commands on Android devices
• Install and uninstall applications
• Push and pull files between local system and Android devices
• Launch applications on Android devices
• Take screenshots and save them locally or copy to clipboard
• Smart device selection when multiple devices are connected

🛠️ Available Tools

| Tool | Description | Required Parameters | Optional Parameters | |------|-------------|---------------------|---------------------| | adb_devices | List connected devices | None | None | | adb_shell | Execute shell commands | command | device_id | | adb_install | Install APK files | path | device_id | | adb_uninstall | Uninstall applications | package_name | device_id | | adb_list_packages | List installed packages | None | device_id, filter | | adb_pull | Pull files from device | remote_path, local_path | device_id | | adb_push | Push files to device | local_path, remote_path | device_id | | launch_app | Launch an application | package_name | device_id | | take_screenshot_and_save | Take and save screenshot | output_path | device_id, format | | take_screenshot_and_copy_to_clipboard | Take screenshot to clipboard | None | device_id, format |

Device Management

The server intelligently handles device selection:

• If only one device is connected, it will be used automatically
• If multiple devices are connected, you must specify a device_id parameter
• If no devices are connected, an error will be returned

Screenshot Path Resolution

When specifying the output_path for saving screenshots, the path is resolved as follows:

• Absolute paths are used as-is
• Paths starting with ~ are expanded to the user's home directory
• Relative paths are resolved relative to the user's home directory

This ensures that screenshots are saved to a location where the MCP server has write permissions.

🔍 Troubleshooting

Common Issues

1. "ADB is not available" error

   • Ensure ADB is installed and in your system PATH
   • Verify by running adb version in your terminal

2. "No Android devices connected" error

   • Check if your device is properly connected with adb devices
   • Ensure USB debugging is enabled on your device
   • Try restarting ADB with adb kill-server followed by adb start-server

3. "Multiple devices connected" error

   • Specify the device_id parameter in your tool call
   • Get the list of available devices with the adb_devices tool

4. Screenshot to clipboard not working

   • Ensure the required platform-specific tools are installed

🔧 Alternative Installation Methods

Option 1: Install from npm

# Install globally
npm install -g @landicefu/android-adb-mcp-server

# Or install locally in your project
npm install @landicefu/android-adb-mcp-server

Option 2: Manual Installation from Source

1. Clone the repository:

   git clone https://github.com/landicefu/android-adb-mcp-server.git
   cd android-adb-mcp-server

2. Install dependencies and build:

   npm install
   npm run build

3. Configure with direct path:

   {
     "mcpServers": {
       "android-adb": {
         "command": "node",
         "args": ["/path/to/android-adb-mcp-server/build/index.js"],
         "env": {},
         "disabled": false,
         "alwaysAllow": []
       }
     }
   }

📄 License

This project is licensed under the ISC License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request