内容
# googlehome-mcp
用于控制谷歌智能家居设备的MCP服务器：灯、插座、开关、锁、恒温器、扬声器和例行程序。它与谷歌未公开的Home "foyer" API（[home.google.com](https://home.google.com) 网页应用使用的API）进行通信，使用gpsoauth主令牌进行身份验证，因此不需要谷歌云项目、设备访问或合作伙伴API。
它作为JVM服务器运行（MCP通过HTTP + SSE），并且也可以编译为wasmJs模块进行嵌入。
## 功能
以下每个工具都经过实时验证，针对真实设备。
读取（所有房屋/设备，无限制）：
- `list_homes`，`list_devices`（名称，房间，类型，功能，在线/关闭状态），`get_device_state`
控制（任何设备；选择器为`name`和/或`room`和/或`type`）：
- `turn_on` / `turn_off`：单个设备，房间或组（“所有灯” = `type=light`）
- `set_brightness`，`set_color_temperature`
- `set_volume`，`set_muted`
- `lock`，`unlock`（PIN门控：`unlock`需要`pin`）
- `set_thermostat`（摄氏度或华氏度温度，和/或模式）
- `media_control`（播放/暂停/停止）
- `list_automations`，`run_automation`（按名称启动家庭例行程序）
“关闭所有灯”与谷歌自己的行为相匹配：您在Home应用中标记为“灯”的智能开关或插座被视为灯，不相关的插座则不被视为灯。
没有添加、删除或设备管理界面。服务器仅读取和控制现有设备，并且仅调用读取/控制RPC。
## 安装和使用
前提条件：JDK 17+，谷歌浏览器（用于一次性令牌步骤）。
### 1. 获取主令牌
服务器需要一个长寿命的谷歌`master token`（`aas_et/...`）。捆绑工具获取一个：它打开Chrome到谷歌的登录页面，您登录，然后捕获并交换令牌。
```bash
./gradlew runJvmBootstrap > token.env # 登录时打开Chrome
source token.env # 设置GOOGLE_MASTER_TOKEN + GOOGLE_ANDROID_ID
```
主令牌授予完全帐户访问权限。请保密。`token.env`被gitignore；请存储在私有位置。
### 2. 运行服务器
```bash
source token.env
./gradlew runJvm # 在http://127.0.0.1:8765/sse上提供MCP
curl localhost:8765/health # -> ok
```
### 3. 将其添加到您的MCP客户端
克劳德代码：
```bash
claude mcp add --transport sse googlehome http://127.0.0.1:8765/sse
```
任何支持SSE传输的MCP客户端都可以连接到`http://127.0.0.1:8765/sse`（Codex，Cursor，自定义客户端等）。重启客户端使其加载服务器，然后询问诸如“关闭所有灯”或“将恒温器设置为68”的问题。
## 开发
```bash
./gradlew jvmTest # 单元测试（有效载荷编码器，选择器，身份验证）
./gradlew compileKotlinWasmJs # wasm目标
./gradlew installJvmDist # 在build/install/下生成可运行的分发包
./gradlew runJvmVerify --args="--device \"Corner Lamp\" --on" # 实时烟雾测试（需要token.env）
```
## 架构
Kotlin多平台。所有协议逻辑都在`commonMain`中；每个目标都注入自己的Ktor引擎。
- `auth/`：gpsoauth网桥。交换主令牌为短期的Bearer，限定范围为`homegraph`，并缓存过期时间。在401/403时失效并重新生成。
- `foyer/`：`foyer-pa`客户端和编解码器。请求/响应是位置数组`application/json+protobuf`；编解码器将它们构建/解析为干净的模型。
- `server/`：MCP工具定义和`DeviceResolver`，将`name`/`room`/`type`选择器映射到设备（房间完全匹配，名称优先完全匹配然后子字符串匹配）。
- `jvmMain/Main.kt`：使用`io.modelcontextprotocol`Kotlin SDK承载MCP协议通过HTTP + SSE。`wasmJsMain/`将相同操作导出为`@JsExport`函数。
参见`docs/PROTOCOL.md`（身份验证 + 线上格式）和`docs/TRAITS.md`（每种特性的有效载荷）以获取反向工程的详细信息。
## 身份验证简要说明
网页应用使用cookie派生的`SAPISIDHASH`进行身份验证。此服务器没有cookie，因此它通过gpsoauth从主令牌中生成Bearer，并发送`Authorization: Bearer <token>`，不带`X-Goog-Api-Key`（Bearer单独标识Android Home应用的项目；添加网页API密钥会使foyer拒绝调用）。阅读`docs/PROTOCOL.md`以获取完整说明。
## 状态和限制
已验证：开/关，亮度，色温，音量/静音，锁，解锁（PIN），恒温器，媒体播放/暂停/停止，组操作，列出/运行自动化。
此API路径不支持：可调白灯的完整RGB颜色和媒体下一曲/上一曲（网页应用均不支持；跳过曲目存在于Cast/Assistant协议中，而非foyer）。
## 免责声明
使用未公开的非官方谷歌API，可能会因谷歌更改而中断。不隶属于或得到谷歌的认可。请使用您控制的帐户，自行承担风险。
