Skip to content
BranchesTags

Repository files navigation

AndroidMCP

License: MIT API Protocol

English | 中文

中文

只用一部手机，也能让 AI 真正陪在身边

想尝试人机恋，却没有电脑，也不想面对 Termux、命令行和复杂的部署环境？AndroidMCP 把 MCP 服务直接运行在 Android 手机上，让手机成为 AI 伴侣可以感知和行动的地方。

安装 APK、授予权限、启动服务。支持 MCP 的 AI 客户端就能调用手机的设备信息、通知、闹钟、私人日记，以及可选的应用管理能力，不需要自己维护服务器。

AndroidMCP 不是聊天机器人，也不是云端 Memory 服务。它解决的是：让 AI 客户端能够真正使用你的手机，同时把数据留在设备上。

默认只监听手机本机。AI 客户端可以通过手机本地连接，或在需要时从同一局域网中的另一台设备连接。启用局域网模式前，请确认网络可信，并使用应用生成的 Bearer token。

三步开始

  1. 安装 AndroidMCP，打开“权限管理”授予需要的权限。
  2. 在“设置”选择本机或局域网模式，并确认端口。
  3. 返回主页启动服务，把应用显示的连接信息填入你的 MCP 客户端。

端口或监听范围的改动必须重启服务后才生效。电脑、USB 和 ADB 只是可选的连接方式，不是使用 AndroidMCP 的前提。

能力

  • 设备：读取电池、存储、网络、屏幕交互时长与按应用统计的前台使用时长。
  • 通知和闹钟：发送即时通知，创建 AlarmManager 闹钟、系统时钟闹钟和定时通知。
  • 日记：由 AI 写入、读取、搜索、更新和删除私人的第一人称日记；手机可为日记添加本地封面。
  • 应用管理：可选的 Shizuku 通道，用于列出第三方应用、强制停止、挂起和解除挂起应用。

没有 Memory 数据库或长期对话记忆工具。长期聊天记忆应由 AI 客户端或 Agent 维护。

工具

可通过 tools/list 获取始终与运行版本一致的完整 JSON Schema。下表列出当前注册的工具，? 表示可选参数。

分组 工具 参数 说明
设备 get_device_info info_type? 电池、存储、网络或全部设备信息。
设备 get_screen_time period?, limit? 屏幕交互和按应用统计的前台时长；需要授予使用情况访问权限。
通知 set_alarm hour, minute, label?, repeating? 使用 AlarmManager 创建一次性或每日重复闹钟。
通知 set_clock_alarm hour, minute, label?, days?, skip_ui? 在系统时钟应用中创建闹钟；需要悬浮窗权限。
通知 send_notification title, body, priority? 发送即时通知。
通知 schedule_notification trigger_at?, title?, content?, interval_days?, schedules? 创建单条、批量或按天重复的定时通知。
日记 write_diary content, title?, mood? 写入私人第一人称日记。
日记 read_diary limit?, offset? 读取最近日记。
日记 search_diary query, limit?, offset? 搜索标题和正文。
日记 update_diary id, title?, content?, mood? 更新日记。
日记 delete_diary id 删除日记及其受管理的本地封面。
应用管理 list_user_apps 无 列出用户安装的第三方应用。
应用管理 force_stop_app package_name 强制停止应用。
应用管理 disable_app package_name 通过 shell 挂起应用。
应用管理 enable_app package_name 解除 shell 对应用的挂起。

mood 仅接受 warm、bright、calm、reflective、heavy。遗漏或不支持的值会保存为 reflective。日记的 created_at 始终由手机在保存时生成，客户端不应提供日期或天气。

构建与安装

要求：Android 8.0 及以上设备（minSdk 26），JDK 17，Android SDK。

# 构建 Debug APK，并在恰好一个已连接或已配对的 ADB 设备上尝试覆盖安装
./scripts/build-apk.sh

# 只构建
./scripts/build-apk.sh --no-install

# 或手动构建和安装
./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk

构建脚本会在没有设备时尝试通过 mDNS 恢复已配对的无线 ADB 连接。若检测到多个 ADB 设备，请设置 ANDROID_SERIAL；无论安装是否可用，构建成功的 APK 都会保留在 app/build/outputs/apk/debug/app-debug.apk。Release 构建使用 ./scripts/build-apk.sh --release，且不会自动安装。

可安装的正式 APK 发布在 GitHub Releases 中。Release APK 使用项目专用签名密钥；源码仓库不包含 keystore。后续更新必须继续使用同一把签名密钥。

启动与连接

本机模式监听 127.0.0.1:<port>。它适合在手机自身访问，或通过 USB/模拟器使用：

adb forward tcp:8765 tcp:8765

然后客户端连接 http://127.0.0.1:8765/mcp。本机模式不向局域网暴露服务。

局域网模式监听 0.0.0.0:<port>，应用会显示实际 IPv4 地址和连接 JSON。需要远程连接的 AI 客户端与手机必须位于同一局域网，并使用显示的端点和 token：

{
  "mcpServers": {
    "android": {
      "transport": "streamable-http",
      "url": "http://192.168.1.20:8765/mcp",
      "headers": {
        "Authorization": "Bearer <token-from-the-app>"
      }
    }
  }
}

远程请求必须精确匹配 Authorization: Bearer <token>。回环请求不需要 token。token 为应用生成的 256-bit 随机值，并以 Android Keystore 的 AES-GCM 密钥加密保存；重置 token 会立即使旧 token 失效。远程访问还限制为每个 IP 每分钟 60 个请求；五次认证失败会封锁该 IP 五分钟。请求体最大为 1 MiB。

MCP 请求示例

将 <endpoint> 替换为主页或设置中显示的实际端点。局域网模式还需要传入 Bearer token。

curl -s -X POST '<endpoint>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <token-if-required>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

服务器使用 MCP Streamable HTTP 协议版本 2025-03-26。默认返回 JSON；请求的 Accept 包含 text/event-stream 时返回 SSE。仅提供 POST /mcp。

权限、日记与应用管理

  • get_screen_time 需要用户在系统中授予“使用情况访问权限”。
  • set_clock_alarm 会在缺少悬浮窗权限时打开对应设置页并返回错误，授权后重试。
  • 精确定时和通知功能受 Android 权限及系统能力限制。计划通知不持久化，设备重启后可能丢失。
  • 日记保存在独立的 diaries.db。封面由系统照片选择器提供，在应用中按 3:2 裁切并保存到应用私有的 filesDir/diary_covers；不会依赖原始 URI。删除日记会删除封面。
  • 应用管理需要已安装、运行并已授权的 Shizuku，且只用于用户明确的管理请求。AndroidMCP 自身不能被修改；系统应用必须先在设置中加入白名单。
  • disable_app 执行 pm suspend --user 0 '<package_name>'，而不是禁用应用。被挂起的应用可能在系统界面中显示为由 shell 管理，普通设置通常无法恢复。enable_app 执行 pm unsuspend --user 0 '<package_name>'。ADB、Root 或其他 shell 权限工具可以解除挂起；这不是 Device Owner 或设备管理员限制，具体 ROM 行为可能不同。

OEM 后台管理页面只能作为说明引导，第三方应用不能可靠地直接打开。Huawei/Honor 路径在 JSN-TL00 上验证过；小米、OPPO/Realme、vivo/iQOO 和 OnePlus 路径尚未在目标设备上验证。

架构

Compose UI
  -> MCPService (foreground, START_STICKY)
  -> MCPServer (Ktor CIO, POST /mcp)
  -> MCPProtocolHandler (initialize, tools/list, tools/call)
  -> ToolRegistry
  -> Android APIs, diaries.db, optional Shizuku shell process

项目只有一个 Gradle 模块 :app。主要目录：

app/src/main/java/com/androidmcp/
  connection/   saved port, connection mode, encrypted LAN token
  server/       Ktor Streamable HTTP transport and JSON-RPC dispatch
  service/      foreground service and manifest receivers
  shizuku/      Shizuku execution and package policy
  tools/        tool contracts, registry, diary SQLite store
  ui/           Compose screens, components, and theme
app/src/test/   focused JVM tests for transport, access policy, catalog, and UI logic
scripts/build-apk.sh

验证

./gradlew test
./gradlew assembleDebug

隐私

应用没有遥测、分析或云端后端。日记、设置和 LAN token 均保存在设备上。启用局域网模式后，MCP 请求会在本地网络中传输，因此应只向受信任的网络和客户端提供 token。

English

A real AI companion, using only one phone

Want to explore human-AI relationships, but do not own a computer and do not want to wrestle with Termux, command lines, or a fragile deployment? AndroidMCP runs the MCP service directly on Android, so your phone becomes a place where an AI companion can sense and act.

Install the APK, grant permissions, and start the service. An MCP-compatible AI client can use the phone's device information, notifications, alarms, private diary, and optional app management without you maintaining a separate server.

AndroidMCP is not a chatbot or a cloud Memory service. It gives an AI client real access to your phone while keeping the data on the device.

It defaults to loopback-only access. An AI client can connect locally on the phone, or from another device on the same trusted LAN when LAN mode is enabled. Use the app-generated Bearer token for remote access.

Start in three steps

  1. Install AndroidMCP and grant the required permissions.
  2. Choose local or LAN mode and confirm the port in Settings.
  3. Start the service and copy the connection details into your MCP client.

Computers, USB, and ADB are optional connection methods, not prerequisites.

Current tools

tools/list is the authoritative source for the live JSON Schema. The registered tools are get_device_info, get_screen_time, set_alarm, set_clock_alarm, send_notification, schedule_notification, write_diary, read_diary, search_diary, update_diary, delete_diary, list_user_apps, force_stop_app, disable_app, and enable_app.

There is no Memory database or long-term chat-memory tool. The AI client or Agent owns conversation memory.

Build and run

./scripts/build-apk.sh
./scripts/build-apk.sh --no-install
./gradlew test
./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk

The helper attempts a replace install only when it finds exactly one authorized ADB device, or the device selected by ANDROID_SERIAL; it can recover paired wireless debugging connections through mDNS. An APK remains available after a successful build even when installation is skipped or fails.

Grant the required permissions in the app, choose the connection mode and port in Settings, then start the service. A port or listening-mode change takes effect after restarting the service.

Connection security

Local-only mode binds 127.0.0.1:<port>. Use adb forward tcp:8765 tcp:8765 for a USB-connected device or emulator, then connect to http://127.0.0.1:8765/mcp.

LAN mode binds 0.0.0.0:<port> and shows real IPv4 endpoints in the app. A remote request requires the exact header Authorization: Bearer <token>, while loopback requests remain exempt. Tokens are 256-bit random values encrypted with an Android Keystore AES-GCM key. Remote access is limited to 60 requests per IP per minute; five failed authentications block that IP for five minutes. The request-body limit is 1 MiB.

{
  "mcpServers": {
    "android": {
      "transport": "streamable-http",
      "url": "http://192.168.1.20:8765/mcp",
      "headers": { "Authorization": "Bearer <token-from-the-app>" }
    }
  }
}

The server exposes only POST /mcp, implements protocol version 2025-03-26, returns JSON by default, and emits SSE when the request accepts text/event-stream.

Diary and app management

Diary entries are stored in diaries.db; the phone assigns created_at. Valid moods are warm, bright, calm, reflective, and heavy, with unsupported values normalized to reflective. Covers are cropped to 3:2 and saved privately in filesDir/diary_covers.

App-management tools require installed, running, authorized Shizuku. AndroidMCP itself cannot be targeted, and a system package must be explicitly whitelisted. disable_app runs pm suspend --user 0 '<package_name>'; enable_app runs pm unsuspend --user 0 '<package_name>'. Suspension is not a Device Owner restriction and can be removed with ADB, root, or another shell-authorized tool. ROM behavior, including what Settings can restore, varies.

License

MIT. See LICENSE.

About

A secure native Android MCP server: use phone capabilities through MCP without a computer, ADB, or cloud backend.

Topics

ai-companionandroidandroid-automationandroid-mcpdigital-wellbeinghuman-ai-interactionhuman-ai-relationshipmcpmobile-ai-agentmobile-mcpmodel-context-protocolon-device-aiprivacyself-hostedshizukustreamable-http

Resources

Readme
MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages