Android Builder Server

An advanced Model Context Protocol (MCP) server that empowers AI coding agents (like Claude or Antigravity) to act as fully capable local Android developers.

By exposing compilation, emulator, asset management, and diagnostics capabilities directly to the agent, the MCP enables a closed-loop build cycle where the agent can build, run, visually inspect, debug, and sign release-ready Android applications.

---

🚀 Key Features

• Project Initialization: Spin up templates (Empty Activity or Jetpack Compose) out-of-the-box.
• Safe Gradle Runner: Execute build tasks (e.g. assembleDebug, assembleRelease) in a secure, non-hanging execution wrapper with automatic timeout safeguards and disabled background compilation daemons (preventing thread deadlocks).
• Live Visual Inspection: Capture screenshots of the running emulator screen directly to your host's artifacts directory so vision-based AI models can inspect the UI layout.
• Logcat Diagnostics: Stream filtered logs from active devices to diagnose app crashes.
• Android Resource Importer: Automatically sanitizes asset names to comply with Android's strict naming rules ([a-z0-9_]) and places files in the correct module res/ folders.
• Manifest & Build Editors: Safely inject manifest permissions, set app names in XML resources, and update Gradle build versions without breaking formatting.
• Signing Pipeline: Generate JKS keystores and run zip alignments (zipalign) followed by private key signing (apksigner) to produce Play Store-ready APKs.

---

🛠️ Prerequisites

To run this MCP server, the host machine must have the following tools installed and configured:

1. Python 3.10 to 3.12
   • Install Python and ensure it is added to your environment PATH.
2. Node.js
   • Required if you are running the server via the Javascript launcher bridge.
3. Android SDK
   • Ensure the Android SDK is installed (typically installed with Android Studio).
   • Set the ANDROID_HOME or ANDROID_SDK_ROOT environment variable pointing to your SDK folder (e.g., C:\Users\<YourUser>\AppData\Local\Android\Sdk).
4. Java Development Kit (JDK 17 or 21)
   • Ensure a compatible JDK is installed (e.g. OpenLogic JDK or OpenJDK).
   • Set the JAVA_HOME environment variable pointing to your JDK folder.

---

📦 Setup & Installation

1. Clone the repository to your local machine (e.g. at C:\Android-Builder-MCP).
2. Install Python dependencies: Open a terminal in the project directory and run:

   pip install -r requirements.txt
   

   Note: If you encounter a TypeError: cannot specify both default and default_factory when importing fastmcp, ensure Pydantic is downgraded to 2.11.x by running:

   pip install "pydantic<2.12.0"
   

---

⚙️ Client Integration (Claude Desktop Configuration)

To connect this MCP server to Claude Desktop, open your configuration file (%APPDATA%\Claude\claude_desktop_config.json) and add the server inside the mcpServers object.

Choose one of the following launcher options:

Option 1: Direct CMD Execution (Recommended for Windows Store Python)

This bypasses Node.js entirely and executes Python 3.12 inside a command shell context, which is required to resolve Windows Store execution aliases:

{
  "mcpServers": {
    "android-builder": {
      "command": "cmd.exe",
      "args": [
        "/c",
        "C:\\Users\\admin\\AppData\\Local\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\\python.exe",
        "-u",
        "C:/Android-Builder-MCP/server.py"
      ]
    }
  }
}

(Make sure to adjust the path to your specific Python 3.12 executable if it differs).

Option 2: JS Launcher Bridge

Uses Node.js to launch the script wrapper, which routes commands through a shell context automatically:

{
  "mcpServers": {
    "android-builder": {
      "command": "node",
      "args": [
        "C:/Android-Builder-MCP/mcp_launcher.js"
      ],
      "env": {
        "MCP_PYTHON_PATH": "C:\\Users\\admin\\AppData\\Local\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.Python.3.12_qbz5n2kfra8p0\\python.exe"
      }
    }
  }
}

(You can omit the MCP_PYTHON_PATH environment variable if your default system python command already maps to the Python environment where mcp is installed).

---

📖 MCP Tool Reference

Tool Name	Type	Description
verify_sdk_setup	Diagnostic	Inspects and reports SDK, JDK, and build tool configurations.
list_projects	Project	Lists all Android projects created inside the workspace directory.
create_project	Project	Initializes a new project from templates (empty_activity, compose).
build_project	Gradle	Compiles your project using local Gradle configurations.
list_emulators	Emulator	Lists virtual device definitions (AVDs) and their current state.
start_emulator	Emulator	Launches an AVD and blocks until the Android boot cycle finishes.
list_devices	ADB	Lists all active device interfaces connected to ADB.
install_apk	ADB	Installs a built APK file onto a target running emulator or device.
import_image_resource	Asset	Sanity-checks image names and copies them to drawing/mipmap resource folders.
capture_screenshot	Diagnostic	Captures the emulator screen and saves it as a local PNG in the artifacts folder.
get_device_logs	Diagnostic	Streams filtered logcat outputs from active emulators to inspect app crashes.
add_manifest_permission	Manifest	Injects security permissions (e.g. Internet) safely into AndroidManifest.xml.
set_app_name	Manifest	Safely updates the app's user-facing display label in strings.xml.
update_gradle_versions	Gradle	Adjusts numeric version codes and semantic strings in build files.
generate_keystore	Signing	Generates JKS keystore files non-interactively using JDK's keytool.
sign_apk	Signing	Performs zip boundary alignment and signs the APK using a generated keystore.

---

🤖 Closed-Loop Visual UI Development Workflow

With this MCP installed, you can upload screenshots of app screens or mockups directly into your chat with Claude and say:

"Build me an Android application that looks like this mockup image."

Claude will proceed to:

1. Analyze the mockup image using visual model reasoning.
2. Create a Compose project using create_project.
3. Implement the screens in Kotlin.
4. Compile the APK using build_project.
5. Start the emulator and install the APK (start_emulator -> install_apk).
6. Take a screenshot of the running app using capture_screenshot.
7. Review the screenshot visually, compare it to your design, and automatically patch the code to fix layout discrepancies, repeating the loop until it matches perfectly!