droid-mcp

Give your Android AI app access to the entire phone.
Calendar, contacts, SMS, camera, location, sensors, notification reply + push subscription, accessibility-driven UI control, IME typing, floating overlay, shell-UID admin via Shizuku, root-UID admin via libsu, and more — 145 tools across 53 modules.

droid-mcp is an Android SDK that gives LLMs typed, structured access to phone capabilities. It implements the Model Context Protocol (MCP) — the same standard used by Claude, Cursor, and other AI tools — so any MCP client can call your phone's APIs over a local network.

It also works without MCP. If you're building an on-device AI app, you can call tools directly as Kotlin functions.

// Build with the modules you need
val mcp = DroidMcp.builder()
    .addTools(CalendarTools.all(context))
    .addTools(ContactsTools.all(context))
    .addTools(LocationTools.all(context))
    .build()

// Your LLM decides to read the calendar
val result = mcp.callTool("read_calendar", mapOf("start_date" to "2026-04-12"))
// result.data = { "events": [...], "count": 3 }

// Or start an HTTP server and connect Claude Code over WiFi
mcp.startServer()
// Connect from desktop: http://<phone-ip>:8080/mcp

Why

On-device LLMs and AI agents are getting good, but they can't do much without access to the phone. droid-mcp bridges that gap:

• For on-device LLM apps — call tools directly from your model's output. No server needed.
• For desktop AI tools — connect Claude Code, Cursor, or any MCP client to your phone over WiFi.
• For agent builders — 145 pre-built, validated tools covering the full Android API surface. Skip the boilerplate.

Installation

Add the modules you need:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        maven { url = uri("https://jitpack.io") }
    }
}

// build.gradle.kts
dependencies {
    // Core (required)
    implementation("com.github.stixez.droid-mcp:droid-mcp-core:0.10.1")

    // Pick what you need
    implementation("com.github.stixez.droid-mcp:droid-mcp-calendar:0.10.1")
    implementation("com.github.stixez.droid-mcp:droid-mcp-contacts:0.10.1")
    implementation("com.github.stixez.droid-mcp:droid-mcp-sms:0.10.1")
    implementation("com.github.stixez.droid-mcp:droid-mcp-location:0.10.1")
    implementation("com.github.stixez.droid-mcp:droid-mcp-camera:0.10.1")
    implementation("com.github.stixez.droid-mcp:droid-mcp-mlkit:0.10.1")
    implementation("com.github.stixez.droid-mcp:droid-mcp-accessibility:0.10.1")
    implementation("com.github.stixez.droid-mcp:droid-mcp-ime:0.10.1")
    // ... see full list below

    // Or include everything (except Tier 4/5 power-user modules)
    implementation("com.github.stixez.droid-mcp:droid-mcp-all:0.10.1")

    // Power-user tiers — opt in only if you want them (they pull third-party deps)
    implementation("com.github.stixez.droid-mcp:droid-mcp-shizuku:0.10.1")    // Tier 4: shell-UID admin (pulls dev.rikka.shizuku)
    implementation("com.github.stixez.droid-mcp:droid-mcp-root:0.10.1")       // Tier 5: root-UID admin (pulls libsu)
}

Usage

On-device (direct calls)

val mcp = DroidMcp.builder()
    .addTools(DeviceTools.all(context))
    .addTools(CalendarTools.all(context))
    .addTools(SmsTools.all(context))
    .build()

// Get tool definitions as JSON — pass this to your LLM
val toolsJson = mcp.listToolsJson()

// Execute whatever tool the LLM picks
val result = mcp.callTool("send_message", mapOf(
    "to" to "+1234567890",
    "body" to "On my way!"
))

if (result.isSuccess) {
    val data = result.data  // Map<String, Any?>
} else {
    val error = result.errorMessage
}

Desktop connection (MCP over HTTP)

Start the server on the phone:

val mcp = DroidMcp.builder()
    .addTools(DeviceTools.all(context))
    .addTools(CalendarTools.all(context))
    .enableHttpServer(
        port = 8080,
        // token = null → auto-generated via SecureRandom (read it from mcp.serverToken)
        // readOnly = true → hide destructive tools from clients
        context = context,        // enables mDNS broadcast on _mcp._tcp
    )
    .build()

mcp.startServer()
val token = mcp.serverToken  // share via QR / pairing

Connect from Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "my-phone": {
      "type": "http",
      "url": "http://<phone-ip>:8080/mcp",
      "headers": {
        "Authorization": "Bearer <token-from-mcp.serverToken>"
      }
    }
  }
}

The phone broadcasts itself on the local network via mDNS (_mcp._tcp) — the sample app's pairing QR encodes the URL and token, so clients can scan and connect without copying the IP by hand.

Now Claude can read your calendar, search contacts, check battery level, and use any other registered tool — directly from your terminal.

Permission handling

The library never requests permissions. Your app stays in control:

if (CalendarTools.hasPermissions(context)) {
    mcp.addTools(CalendarTools.all(context))
} else {
    val needed = CalendarTools.requiredPermissions()
    // Show your own permission UI
}

Modules

53 modules, 145 tools. Each module is independent — only the permissions for included modules are added to your manifest. Root (Tier 5) reuses the same 17 shell tools as Shizuku (Tier 4) via the shared ShellBackend interface.

The table below lists 48 of them (core plus the tool modules; overlay is listed too, though it exposes a programmatic API rather than LLM tools). The remaining five are infrastructure: two support modules (notification-listener, shell-core) that the listener-based and shell-based modules wire against, plus three opt-in hardening modules added in 0.10.0 (audit, tls, server-service) — see Hardening modules below.

Full parameter reference: docs/TOOLS.md. Generated API docs (KDoc): stixez.github.io/droid-mcp.

Hardening modules (0.10.0)

Three opt-in infrastructure modules harden the HTTP transport and operations. They expose no LLM tools — they're programmatic APIs the host wires in. Each pulls a third-party dependency, so all three stay outside :droid-mcp-all.

Per-tool gating (DroidMcp.setToolEnabled / setDisabledTools) and token rotation / per-client pairing (rotateToken / pairClient / revokeClient) are built into core — no extra module. See docs/SECURITY.md for the threat model.

Capability tiers

Modules are grouped into five tiers by the kind of permission they need. Tiers 1–3 are the core surface; Tiers 4–5 are opt-in power tools for hosts that need shell-UID or root-UID admin — they pull third-party native dependencies and stay outside :droid-mcp-all to keep the default APK lean.

Special permissions

Some modules require permissions that can't be requested at runtime. The tools work without them for read operations, and return clear error messages for write operations that need the grant.

Architecture

                    Your App
                       |
              +--------+--------+
              |                 |
        On-device LLM    Desktop MCP Client
              |              (Claude Code, etc.)
              v                 |
        InProcessTransport      v
              |            HttpTransport
              |           (Ktor/Netty)
              +--------+--------+
                       |
                  ToolRegistry
                       |
     +-----+-----+----+----+-----+-----+
     |     |     |    |    |     |     |
   Device Cal  SMS  Files Loc  Camera ...
   Tools  Tools Tools Tools Tools Tools
     |     |     |    |    |     |     |
     Android System APIs

Safety

Requirements

• Android 9+ (API 28)
• Kotlin 2.0+
• Gradle 8.12+

Sample App

The sample-app module includes a Compose UI that exercises the full tool surface — every module is registered (subject to permission availability) with quick-test buttons for representative tools in each category. Categories that require special permissions show a "Grant Access" button that opens the relevant system settings page. Start the HTTP server from the app to connect desktop MCP clients — pair via the QR code or copy the bearer token shown on the home screen. See docs/PAIRING.md.

It also demonstrates the 0.10.0 hardening features end-to-end:

• Tools tab — quick-test buttons per category.
• Gating tab — a per-tool switch grid (with filter + bulk enable/disable) that toggles tools off the live tools/list / tools/call surface without restarting the server.
• Audit tab — browse the persisted RoomAuditSink log of HTTP calls (tool, client, outcome, duration, arguments), clear it, or export to JSON.
• TLS toggle — serve over HTTPS with a self-signed cert; the SHA-256 fingerprint is shown (copyable) and folded into the pairing QR for the client to pin.
• The server runs inside a foreground service (DroidMcpServerService) so it survives screen-off / backgrounding.

Contributing

Contributions welcome. Please open an issue before submitting a PR for non-trivial changes.

License

Copyright 2026

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0