cazriel/mcp-server

运行在 Android 手机上的本地 Model Context Protocol (MCP) 服务器。通过 Streamable HTTP 协议向 Claude Desktop、Cursor 等 MCP 客户端暴露手机能力：文件操作、系统管理、设备信息、应用管理、脚本执行、通讯交互、网络请求、实用工具等。

[!IMPORTANT] 本项目实现的是 MCP 服务端，运行在被控的 Android 设备上；MCP 客户端运行在 PC 或另一台设备，通过局域网或内网穿透与之通信。

---

目录

• 核心特性
• 工作原理
• 工具清单
• 客户端接入
• 权限说明
• 致谢
• 许可证

---

核心特性

• 标准 MCP 协议：实现 Streamable HTTP 传输（POST /mcp，JSON-RPC 2.0），同时兼容 SSE（GET /sse）。
• 可选 Bearer 鉴权：自动生成 16 位 token，支持开关；未启用时任意局域网客户端均可连接。
• 工作区沙箱：通过系统文件夹选择器（SAF）限定文件操作根目录，避免越权访问。
• 桥接远端 MCP：可将远端 MCP 服务（Streamable HTTP）的工具拉取到本地，合并为单一端点。
• 内网穿透：基于 bore.pub 协议，一键将本地端口暴露到公网。
• 悬浮窗控制：可选悬浮窗快捷开关服务器；支持开机自启动。
• 特权命令：集成 Shizuku，在已授权设备上以 shell 权限执行 am、pm 等命令。
• 内置 JavaScript 引擎：基于 QuickJS（ES2020），提供 mcp_javascript 工具执行脚本自动化。
• 前台服务保活：FOREGROUND_SERVICE_TYPE_DATA_SYNC 与可选 WakeLock，确保长时间后台运行。

---

工作原理

应用以 Android 前台服务（McpServerService）持有 McpHttpServer，在本地端口监听 HTTP 请求。收到符合 MCP 规范的 JSON-RPC 消息后，由 McpHandler 分发到 ToolKit，再路由至各 ToolDefinition 的处理函数，并将结果以 JSON 或 SSE 形式返回。

flowchart LR
    Client[MCP 客户端Claude Desktop / Cursor]
    Server[MCP 服务器McpHttpServer]
    Toolkit[ToolKit]
    Tools[ToolDefinitions]
    Device[设备能力]
    Client |Streamable HTTP / SSE| Server
    Server --> Toolkit
    Toolkit --> Tools
    Tools --> Device

HTTP 端点

服务器实现的 JSON-RPC 方法包括 initialize、notifications/initialized、ping、tools/list、tools/call、resources/list、prompts/list 等。

---

工具清单

服务器启动时由 ToolKit.init 注册以下内置工具。所有工具均返回 JSON 对象；返回错误时填充 isError: true 并附带标准化错误码（详见 ErrorCodes.kt）。

---

客户端接入

任何支持 MCP Streamable HTTP 传输的客户端均可连接。以下示例以 curl 与典型 JSON-RPC 请求演示。

initialize

curl -X POST http://:1145/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "example", "version": "1.0"}
    }
  }'

服务器响应后会下发 Mcp-Session-Id 头，后续请求需原样回传。

列出工具

{"jsonrpc":"2.0","id":2,"method":"tools/list"}

调用工具

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "device_info",
    "arguments": {}
  }
}

客户端配置示例（Claude Desktop / Cline）

{
  "mcpServers": {
    "android-device": {
      "type": "streamableHttp",
      "url": "http://192.168.1.10:1145/mcp"
    }
  }
}

启用 token 鉴权时，需在客户端请求头附加：

Authorization: Bearer 

`` 见应用设置页 “鉴权 token”。

---

权限说明

应用声明以下权限，对应用途如下：

---

致谢

本项目在设计与实现过程中参考或直接使用了以下开源项目，谨此致谢：

• Model Context Protocol — Anthropic 提出的开放协议规范
• Shizuku — 以普通应用身份获取系统级 API 能力
• QuickJS Android — 嵌入式 JavaScript 引擎（ES2020）
• bore — 内网穿透隧道协议实现参考
• Jetpack Compose — 现代 Android UI 工具包
• Gson — JSON 序列化库
• kotlinx.coroutines — Kotlin 协程支持

---

许可证

本项目基于 GNU General Public License v3.0（GPL-3.0）开源。

您可以自由地使用、修改和分发本软件，但所有衍生作品必须以相同许可证开源，并在显著位置保留原始版权与许可证声明。