内容
<div align="center">
# Android Studio MCP
**让 Claude 操作 Android Studio 和整个 Android 工具链 — 而不仅仅是讨论它。**
专业的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，将 Claude（Claude Code / Claude Desktop）转变为真正的 Android **操作员**：构建、测试、检查、运行在设备和模拟器上、分析 APK、搭建项目、静默检查代码，并驱动实时 IDE。
</div>
---
## 为什么存在
Android Studio 是一个 **基于 IntelliJ 的 IDE**。可靠地以编程方式操作它的方法不是 **点击 GUI**，而是驱动 IDE 使用的相同工具。该服务器构建 **稳定优先**：大部分功能来自坚实的命令行工具链，实时 IDE 桥接和 UI 自动化作为额外的层，优雅地降级。
| 层级 | 机制 | 涵盖 | 健壮性 |
|------|-----------|--------|-----------|
| **1. 构建 / SDK 命令行** | `gradlew`、`adb`、`emulator`、`avdmanager`、`sdkmanager`、`apkanalyzer`、`apksigner`、`aapt2`、`bundletool` | 构建、测试、检查、依赖、签名、设备、模拟器、APK/AAB 分析 | ★★★★★ 静默、确定性 |
| **2. 静默 IDE 命令行** | `studio64.exe inspect` / `format` / `diff`，打开项目/文件 | 完整的代码检查报告、重新格式化、导航 | ★★★★☆ |
| **3. 实时 IDE** | 内置 HTTP 服务器 (`:63342`) + `stdioMcpServer` MCP 桥接 | 打开 IDE、IDE 状态、IDE 操作 — *当 IDE 运行时* | ★★★☆☆ |
| **4. UI 备用方案** | 原生 Win32 焦点 + SendKeys + 截图 | 任意操作通过 "查找操作"，视觉验证 | ★★☆☆☆ |
第 1-2 层的所有功能都 **无论 IDE 是否打开**，并且不需要插件。
---
## 亮点
- 🟢 **一键 "运行" 按钮** — `as_run_app`：构建 → 安装 → 启动 → 捕获日志 → **检测崩溃** → 截图，一步到位。
- 🔨 **完整的 Gradle 控制** — 构建 APK/AAB，单元测试和仪器测试，检查，依赖，签名报告 — 附 **结构化** 发现（检查 XML 和 JUnit XML 解析为文件/行/严重性）。
- 🩺 **自我修复构建** — 失败的构建返回一个 `remediation` 列表，将错误映射到下一个要调用的确切工具（许可证 → 接受，缺少平台 → 安装，没有设备 → 启动模拟器）。
- 📱 **设备和模拟器** — 列出/创建/启动/停止 AVD，安装/卸载，**流式 logcat** 你可以轮询，截图，屏幕录制，输入注入。
- 🏗️ **项目搭建** — 生成一个真实的、可构建的 Views 或 Compose 项目（捆绑 Gradle 包装器，正确的 AGP/Kotlin/SDK 级别）。
- 🔍 **静默代码检查** — 运行 IDE 的离线 "检查代码" 引擎，并获取结构化的问题。
- 📦 **APK / AAB 分析** — 包/版本/权限，方法计数，大小，签名验证，APK 差异，AAB → 可安装的 APK 集。
- 🔒 **安全优先** — 工作区路径允许列表，破坏性操作的确认门控，自动备份，秘密删除，强化设备外壳。
- 🧪 **测试** — 73 个工具，真正的 APK 构建端到端，15 个解析器单元测试，安全门控回归，对抗性多代理代码审查。
---
## 需求
- **Windows** （服务器针对 Windows 平台；路径和进程控制使用 Win32）。
- **Android Studio** （针对构建 `AI-261`，2026.1.x 进行测试）— 在 `C:\Program Files\Android\Android Studio` 处自动发现。
- **Android SDK** 带有命令行工具、平台工具、模拟器和构建工具 — 在 `%LOCALAPPDATA%\Android\Sdk` 处自动发现。
- **Python ≥ 3.10** 和 **[uv](https://docs.astral.sh/uv/)**。
所有路径都自动发现，但可以重写（参见 [配置](#配置))。
---
## 安装
```powershell
git clone https://github.com/MauricePutinas/Android-Studio-MCP-Claude-Code.git
cd Android-Studio-MCP-Claude-Code
uv sync
# 健全性检查
uv run python -m android_studio_mcp --selfcheck # 已解析路径 + 工具数量
uv run python -m android_studio_mcp --list-tools # 所有 73 个工具
uv run python scripts/smoke_test.py # 17/17 功能检查
uv run pytest tests -q # 15 个解析器单元测试
```
### 连接到 Claude
**Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"android-studio": {
"command": "C:\\Users\\<you>\\AppData\\Local\\hermes\\bin\\uv.exe",
"args": ["--directory", "C:\\path\\to\\Android-Studio-MCP-Claude-Code", "run", "python", "-m", "android_studio_mcp"]
}
}
}
```
**Claude Code (CLI):**
```powershell
claude mcp add android-studio --scope user -- uv --directory "C:\path\to\Android-Studio-MCP-Claude-Code" run python -m android_studio_mcp
```
**一键安装包：** 使用 `powershell -File scripts\build_mcpb.ps1` 构建一个 `.mcpb` 文件，并通过 *Claude Desktop → 设置 → 扩展 → 安装扩展* 进行安装。参见 [docs/CLAUDE_SETUP.md](docs/CLAUDE_SETUP.md) 和 [docs/PACKAGING.md](docs/PACKAGING.md)。
> **注意：** 提交的 `manifest.json` / 示例配置已预填充为作者的机器。调整两个绝对路径（项目目录，`uv.exe`）以适应您的设置。
---
## 工具目录（73 个工具）
> 所有工具都以 `as_` 为前缀，并返回带有 `status` 的 JSON（`ok` | `error` | `confirmation_required`）和人类 `summary`。
> 破坏性工具需要 `confirm=true`。
<details open>
<summary><b>生命周期和导航</b></summary>
`as_status` · `as_is_running` · `as_launch` · `as_close` · `as_restart` · `as_open_project` · `as_open_file` · `as_diff`
</details>
<details>
<summary><b>运行和后台进程</b></summary>
`as_run_app` （构建→安装→启动→日志→崩溃→截图） · `as_logcat_watch_start` / `as_logcat_watch_read` / `as_logcat_watch_stop` · `as_proc_list` / `as_proc_stop`
</details>
<details>
<summary><b>Gradle（构建 / 测试 / 检查）</b></summary>
`as_gradle_tasks` · `as_gradle_assemble` · `as_gradle_bundle` · `as_gradle_test` *（结构化 JUnit）· `as_gradle_lint` *（结构化发现）· `as_gradle_clean` · `as_gradle_dependencies` · `as_gradle_signing_report` · `as_gradle_run_task` · `as_gradle_stop`
</details>
<details>
<summary><b>SDK 管理器</b></summary>
`as_sdk_list` · `as_sdk_install` · `as_sdk_accept_licenses`
</details>
<details>
<summary><b>模拟器 / AVDs</b></summary>
`as_avd_list` · `as_avd_create` · `as_avd_delete` · `as_avd_start` · `as_avd_stop`
</details>
<details>
<summary><b>设备（ADB）</b></summary>
`as_adb_devices` · `as_adb_install` · `as_adb_uninstall` · `as_adb_logcat` · `as_adb_logcat_clear` · `as_adb_shell` *（保护）· `as_adb_screenshot` · `as_adb_input` · `as_adb_start_app` · `as_adb_stop_app` · `as_adb_pull` · `as_adb_push`
</details>
<details>
<summary><b>项目</b></summary>
`as_project_create` *（真实 Views/Compose 搭建）· `as_project_info` *（包括版本目录）· `as_project_validate` · `as_project_backup` · `as_project_list_recent`
</details>
<details>
<summary><b>APK / AAB 分析</b></summary>
`as_apk_info` · `as_apk_methods` · `as_apk_filesize` · `as_apk_verify_signature` · `as_apk_compare` · `as_aab_build_apks` · `as_aab_install`
</details>
<details>
<summary><b>静默 IDE 分析</b></summary>
`as_inspect_code` *（离线 "检查代码" → 结构化问题）· `as_format_code` *（原位重新格式化，备份优先）*
</details>
<details>
<summary><b>附加功能</b></summary>
`as_retrace` *（反混淆 R8/ProGuard 堆栈跟踪）· `as_screenrecord` *（录制设备屏幕 → mp4）*
</details>
<details>
<summary><b>实时 IDE 桥接</b></summary>
`as_ide_status` · `as_ide_list_mcp_tools` · `as_ide_call_mcp_tool`
</details>
<details>
<summary><b>原生 UI 备用方案</b></summary>
`as_ui_screenshot` · `as_ui_focus` · `as_ui_send_keys` · `as_ui_invoke_action` *（任意 IDE 操作通过 "查找操作"）*
</details>
<details>
<summary><b>报告 / 日志 / 安全</b></summary>
`as_report_health` · `as_logs_ide` · `as_logs_mcp` · `as_config` · `as_backup_file` · `as_restore_backup`
</details>
**资源：** `asmcp://config` · `asmcp://idea-log` · `asmcp://projects/recent`
**提示：** `run_app` · `diagnose_build`
---
## 安全模型
- **路径允许列表** — 写/删除操作必须针对配置的工作区根目录（默认：`E:\Projekte` + 主目录）。使用 `ASMCP_WORKSPACE_ROOTS` 覆盖。
- **确认门控** — 破坏性工具（`as_close --force`，`as_adb_uninstall`，`as_avd_delete`，`as_format_code`，`as_sdk_install`，`as_restore_backup`，...）除非调用 `confirm=true`，否则返回 `confirmation_required`。
- **备份优先** — 文件在重新格式化/覆盖之前会备份；项目可以使用 `as_project_backup` 压缩。
- **保护的设备外壳** — `as_adb_shell` 运行识别的只读命令，但需要 `confirm=true` 进行任何包含 shell 运算符（`;`、`|`、`&&`、`$()`，...）或破坏性标记的命令。
- **秘密删除** — 密钥库/存储/密钥密码和令牌在所有捕获的输出和日志中被屏蔽。
- **stdio 安全日志** — 所有日志都输出到 stderr + 旋转文件，从不输出到 stdout。
---
## 配置
每个设置的解析顺序：**环境变量 → `config.json` → 自动发现 → 默认**。
| 设置 | 环境变量 | 默认值 |
|--------|---------|---------|
| Android Studio 主目录 | `ASMCP_STUDIO_HOME` / `STUDIO_HOME` | `C:\Program Files\Android\Android Studio` |
| Android SDK | `ASMCP_ANDROID_SDK` / `ANDROID_HOME` / `ANDROID_SDK_ROOT` | `%LOCALAPPDATA%\Android\Sdk` |
| 工作区根目录（允许列表） | `ASMCP_WORKSPACE_ROOTS` （`;`分隔） | `E:\Projekte;%USERPROFILE%` |
| 内置服务器端口 | `ASMCP_BUILTIN_SERVER_PORT` | `63342` |
| bundletool jar | `ASMCP_BUNDLETOOL` | 自动下载后首次使用 |
参见 [`config.example.json`](config.example.json)。
---
## 架构
```
src/android_studio_mcp/
├── app.py FastMCP 实例
├── config.py 工具链自动发现 + 设置
├── runner.py 安全的子进程执行（环境变量、.bat、超时、删除）
├── safety.py 路径允许列表、确认门控、备份
├── procregistry.py 后台进程注册表（logcat 监视，...）
├── parsers.py Gradle / ADB / AVD / SDK / aapt 输出解析器
├── report_parsers.py lint XML、JUnit XML、版本目录
├── diagnostics.py 构建失败 → 修复规则
├── scaffold.py 项目模板（Views / Compose）
├── ide_http.py 内置 IDE 服务器 (:63342) 客户端
├── mcp_bridge.py stdioMcpServer 桥接
├── winauto.py 原生 Win32 UI 自动化
└── tools/ 73 个 @mcp.tool 定义，按域分组
```
---
## 测试
| 测试套件 | 测试内容 | 结果 |
|------|------|--------|
| `scripts/smoke_test.py` | 环境检查、门控、路径允许列表、项目模板往返 | 17/17 |
| `scripts/build_test.py` | 真实的 `gradlew assembleDebug` → 签名 APK → 分析 | BUILD SUCCESSFUL |
| `scripts/security_test.py` | adb-shell 注入/链接门控 | 6/6 |
| `pytest tests` | 纯解析器函数 | 15/15 |
| `evals/android_studio_eval.xml` | 10 个只读评估 Q&A（mcp-builder 格式） | — |
完整的性能/风险矩阵在 [docs/QUALITY.md](docs/QUALITY.md) 中。
---
## 限制
- 官方 **实时 IDE MCP** (`stdioMcpServer`) 需要 *MCP Server* 插件 (`com.intellij.mcpServer`)。在原始 Android Studio 上可能未安装 — `as_ide_status` 会告诉你，并且 CLI 工具无论如何都涵盖了所有内容。
- **静默 `inspect`** 首先索引项目，因此可能需要几分钟；不要在同一个项目打开的正在运行的 IDE 上运行它（配置目录争用）。
- **UI 自动化** （SendKeys）是尽力而为的，并且面向英语键盘映射；始终通过返回的截图进行验证。
- 服务器 **仅限 Windows** 设计。
---
## 许可证
MIT © Maurice Putinas — 参见 [LICENSE](LICENSE)。
> 使用 [FastMCP](https://github.com/modelcontextprotocol/python-sdk) 构建。 不隶属于 Google 或 JetBrains。 "Android" 和 "Android Studio" 是 Google LLC 的商标。
