内容
# ibattery-mcp
[](https://github.com/China-Drummond/ibattery-mcp/actions/workflows/ci.yml)
[](./LICENSE)
[](https://github.com/China-Drummond/ibattery-mcp/releases)
一个遵循MCP（模型上下文协议）的服务器，旨在为您的苹果设备提供电池和充电状态信息——包括这台Mac、附近的蓝牙配件、iPhone/iPad和Apple Watch——作为AI助手（如Claude Code、Claude Desktop、Work Buddy等MCP客户端）可以调用的工具。
[中文版本](./README_zh.md)
## 状态
| 设备 | 状态 |
|---|---|
| 这台Mac自身的电池 | ⚠️ 已实现，单元测试完成 — 尚未确认与真实硬件兼容 |
| 普通蓝牙设备（标准电池服务 — 大多数蓝牙鼠标/键盘） | ⚠️ 已实现，单元测试完成 — 真实蓝牙扫描功能正常，但尚未确认有兼容的外设 |
| iPhone / iPad | ✅ 已在真实设备上验证 |
| Apple Watch（通过配对的iPhone） | ✅ 已在真实硬件上验证 |
| AirPods | ⚠️ 已实现，单元测试完成 — 尚未确认与真实硬件兼容 |
| 同一网络下的另一台Mac | ❌ 不计划支持 — 参见下文[为什么不支持另一台Mac？](#为什么不支持另一台Mac) |
该项目仍处于0.1版本之前，正在积极开发中。详见[CHANGELOG.md](./CHANGELOG.md)了解最新进展。
## 为什么需要一个单独的蓝牙辅助应用？
macOS将CoreBluetooth的隐私（TCC）检查归因于*负责进程*，而非实际调用API的二进制文件。MCP服务器按照设计，是由其宿主（Claude Code、Claude Desktop等）直接 spawned 的子进程 — 从未通过macOS LaunchServices（`open`）启动。这意味着一个裸MCP服务器永远不能成为其自身的“负责进程”，以便访问蓝牙，否则操作系统会在其尝试时立即终止。`ibattery-mcp`通过一种正常Mac应用的方式来解决这个问题：一个名为`ibattery-ble-helper`的小型伴侣应用拥有所有蓝牙访问权限，并正常启动（`open`或作为登录项）；无状态MCP服务器通过本地Unix域套接字与其通信。详见[设计文档](./docs/superpowers/specs/2026-07-19-ibattery-mcp-design.md)了解完整故事。
## 为什么不支持另一台Mac？
与iPhone/iPad、Apple Watch和AirPods不同 — 其中macOS或iOS已经在后台静默收集和同步电池数据（lockdownd的配对关系、iCloud密钥共享为这台Mac的蓝牙栈提供数据）而该项目只需读取 — 没有等效的内置通道来获取另一台Mac的电池信息。Find My可以显示它，但仅通过封闭的、基于云的路径，且没有本地或可脚本访问的接口。查看另一台Mac的状态确实需要一个自定义的对等应用程序在*每台*涉及的Mac上运行，可能在macOS的本地网络权限后面 — 与蓝牙受其负责进程规则的限制相同 — 第二个持久化辅助应用，其自身的发现/身份验证设计，没有官方API可以依赖。在设计过程中权衡了这一成本后，决定不继续开发。详见[设计文档](./docs/superpowers/specs/2026-07-20-lan-multi-mac-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`。
### 蓝牙设备支持的一次性设置
蓝牙设备（普通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发现的所有设备的电池/状态。用于“我的设备状态如何”的总结（例如，晨间简报）的主要工具。
- **`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)
