内容
# i电池-mcp
[](https://github.com/China-Drummond/ibattery-mcp/actions/workflows/ci.yml)
[](./LICENSE)
[](https://github.com/China-Drummond/ibattery-mcp/releases)
一个MCP（模型上下文协议）服务器，用于为您的AI助手（如Claude Code、Claude Desktop等）提供苹果设备（如Mac、蓝牙配件、iPhone/iPad和Apple Watch）的电池和充电状态。
[中文版本](./README_zh.md)
## 状态
| 设备 | 状态 |
|---|---|
| 这台Mac的电池 | ⚠️ 已实现，单元测试通过 — 但尚未确认与实际硬件兼容 |
| 通用蓝牙设备（标准电池服务 — 大多数蓝牙鼠标/键盘） | ⚠️ 已实现，单元测试通过 — 真实的BLE扫描有效，但尚未确认有兼容的外设 |
| iPhone / iPad | ✅ 已验证通过真实设备 |
| Apple Watch（通过配对的iPhone） | ✅ 已验证通过真实硬件 |
| AirPods | 🚧 尚未实现（计划中） |
| 同一网络上的另一台Mac | 🚧 尚未实现（计划中） |
该项目处于pre-1.0版本，正在积极开发中。有关详细信息，请参见 [CHANGELOG.md](./CHANGELOG.md)。
## 为什么需要一个单独的蓝牙辅助应用？
macOS将CoreBluetooth的隐私（TCC）检查归因于*负责*进程，而不是实际调用API的二进制文件。MCP服务器按照设计，直接由其主机（如Claude Code、Claude Desktop等）启动 — 从不通过macOS LaunchServices（`open`）启动。这意味着一个单独的MCP服务器永远不能成为其自身的蓝牙访问的“负责”进程，并且会在尝试访问时被操作系统终止。`ibattery-mcp`通过与通常的Mac应用程序相同的方式解决了这个问题：一个小的配套应用程序`ibattery-ble-helper`拥有所有的蓝牙访问权限，并且正常启动（`open`，或作为登录项）；无状态的MCP服务器通过本地Unix域套接字与它通信。有关完整的故事，包括如何发现这一点，请参见 [设计文档](./docs/superpowers/specs/2026-07-19-ibattery-mcp-design.md)。
## 安装
### 先决条件
- macOS 13（Ventura）或更高版本
- [Homebrew](https://brew.sh)
### 安装
```bash
brew install China-Drummond/tap/ibattery-mcp
```
这也会安装`libimobiledevice`和`pkg-config`作为依赖项（需要iPhone/iPad/Apple Watch支持），并在您的机器上从源代码构建`ibattery-mcp`。
### Bluetooth设备支持的一次性设置
蓝牙设备（通用BLE配件）需要运行配套辅助应用程序：
```bash
open "$(brew --prefix ibattery-mcp)/libexec/ibattery-ble-helper.app"
```
第一次启动时将提示请求蓝牙权限 — 请授予。辅助应用程序随后在后台运行；您只需要执行此操作一次（或在重启后再次执行，除非您将其设置为登录项）。
### iPhone/iPad/Apple Watch支持的一次性设置
将您的iPhone或iPad通过USB至少一次连接到此Mac，并在提示时点击“信任”。这建立了`libimobiledevice`所需的配对；之后，如果您在设备上启用了WiFi同步，它也可以通过WiFi工作。
## 配置
将`ibattery-mcp`添加到MCP主机的配置中。例如，对于读取具有`command`/`args`形状的JSON配置的主机：
```json
{
"mcpServers": {
"ibattery-mcp": {
"command": "ibattery-mcp"
}
}
}
```
## 可用工具
- **`get_all_devices_status()`** — 当前可从此Mac发现的所有设备的电池/状态。用于“我的设备状态如何”的总结（例如，早晨简报）的 main 工具。
- **`get_device_battery(query)`** — 一个设备的电池状态，与名称或类型子字符串（例如，“iPhone”，“MacBook”）匹配。
- **`list_known_devices()`** — 到目前为止在本会话中看到的设备，无需触发新的扫描。
## 贡献
有关如何设置开发环境、运行测试套件和提交更改的信息，请参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
## 许可证
[MIT](./LICENSE)
## 致谢
- [modelcontextprotocol/swift-sdk](https://github.com/modelcontextprotocol/swift-sdk) — 本项目的MCP协议层所基于的官方Swift SDK。
- [libimobiledevice](https://libimobiledevice.org) — 本项目用于iPhone/iPad和Apple Watch通信的开源库（作为外部依赖项，不捆绑）。
- [AirBattery](https://github.com/lihaoyun6/AirBattery) — 激发了该项目的先前艺术。`ibattery-mcp`是一个独立的、干净的房间实现（参见 [设计文档](./docs/superpowers/specs/2026-07-19-ibattery-mcp-design.md) 了解原因），并且不与其共享任何代码。
## 星级历史
[](https://star-history.com/#China-Drummond/ibattery-mcp&Date)
