# Stackchan Claude Bridge

> Bridge Stack-chan (xiaozhi-esp32) to Claude Code via MCP — voice-control your personal knowledge base, skills, and 30+ MCP servers through Stack-chan.

- **Type:** MCP server
- **Install:** `agentstack add mcp-heavenchenggong-stackchan-claude-bridge`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [heavenchenggong](https://agentstack.voostack.com/s/heavenchenggong)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [heavenchenggong](https://github.com/heavenchenggong)
- **Source:** https://github.com/heavenchenggong/stackchan-claude-bridge

## Install

```sh
agentstack add mcp-heavenchenggong-stackchan-claude-bridge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Stack-chan × Claude Code 桥接

把 [Stack-chan 桌面机器人](https://protopedia.net/prototype/2345)（M5Stack CoreS3 + 双舵机 + 摄像头）变成 **能调你本地 Claude Code 的 AI 桌面伙伴**。

- 🎤 跟 Stack-chan 说话用的是流畅的 [小智 AI 协议](https://github.com/78/xiaozhi-esp32)（DeepSeek/Qwen/豆包 后端，~1 秒响应）
- 🤖 关键时刻调本地 **Claude Code**，访问你的 memory / skills / 30+ MCP 服务（个人知识库、公众号写作、邮件、wiki 等）
- 🎯 LLM 还能控制头部角度 / 表情 / LED 灯环，所有动作语音可控

> "派蒙，查我的知识库里关于 HK 薪酬的笔记" → DeepSeek 看到 `claude_code` 工具 → wss 调到你 Mac → spawn `claude --print` → 用 personal-wiki skill 查 → 念结果给你

---

## 这是什么

Stack-chan 是日本网友设计的开源桌面机器人，[M5Stack 卖整套套件](https://shop.m5stack.com/products/m5stack-cores3-stackchan-ai-desktop-robot-kit)。配合 [78/xiaozhi-esp32](https://github.com/78/xiaozhi-esp32)（"小智 AI"）固件可以语音对话。

但**官方固件**：
- ❌ 不能换 Claude/GPT 作主模型（官方 server 只支持国产 LLM）
- ❌ 没暴露 servo 角度控制给 LLM
- ❌ 休眠后唤醒词失效
- ❌ 不能查你的个人知识库

**这个项目**：
- ✅ 通过 xiaozhi.me **MCP 接入点**给 LLM 加了一个 `claude_code(task)` 工具
- ✅ 工具通过 wss 路由到你 Mac 上的本地 server
- ✅ 本地 server spawn `claude --print` 跑你的 Claude Code（带 memory + skills + MCP）
- ✅ 异步模式：LLM 立刻回"派蒙正在查"，结果出来后用户说"查到了吗"再念
- ✅ 同时 fork 修了官方固件 3 个 bug（servo MCP 缺失、休眠 mic 关闭、Nod 用错 base）

整体架构：

```
你说「派蒙，查我的知识库里关于 X 的笔记」
                ↓
        Stack-chan 麦克风 ── 流式 ASR
                ↓
        虾哥后端 api.xiaozhi.me + DeepSeek V4
                ↓ 看到 claude_code 工具就 tools/call
        wss://api.xiaozhi.me/mcp/?token=...
                ↓
        你 Mac launchd 守护的 mcp_pipe.py（wss ↔ stdio）
                ↓
        bridge/server.py (FastMCP, 4 个工具)
                ↓ subprocess
        claude --print "task"
                ↓
        memory + skills + 30+ MCP 服务
                ↓ 写到 /tmp/claude-bridge-outbox/{ts}.txt
        立刻返回 "派蒙正在查 X，稍等一下问我"
                ↓
        TTS → 派蒙说话
        ......稍后......
你说「派蒙，查到了吗」
                ↓
        claude_code_check_results 取最新结果
                ↓
        TTS 念结果（自动截到 600 字）
```

---

## 适合谁？

- 已经买了 **M5Stack CoreS3 + Stack-chan 套件**（或正在考虑）
- Mac 上装了 **Claude Code CLI**（`claude` 命令可用）
- 想让 Stack-chan 对接自己的本地知识库 / 工具，而不只是"小智 AI 默认人格"

**不需要**：
- 自己装 ESP-IDF（fork 用 GitHub Actions 自动 build，直接下 release）
- 自己部署 xiaozhi-server（用虾哥免费云后端就行）
- 改 Mac 系统设置 / 装 docker / 装 Redis 等重型工具（只装一个 ~65MB 的 Python venv）

**有要求**：
- Claude Code 能跑（即接入了任意 Anthropic 兼容 LLM，或 SAP HAI proxy 之类）

---

## 快速上手

### 1. 注册小智账号 + 创建智能体

1. 打开 [https://xiaozhi.me](https://xiaozhi.me)，手机号注册
2. 登录后进 **控制台 → 智能体 → +添加**，创建一个智能体（比如叫"派蒙"）
3. 进入智能体配置：
   - **语言模型**：选 `DeepSeek V4（性格丰富）` —— 工具调用稳，性格丰满
   - **角色介绍**：见下面 [推荐角色介绍](#推荐角色介绍-prompt) 抄一份
   - **MCP 设置 → 自定义服务**：点 `[获取 MCP 接入点]`，复制弹出的 `wss://api.xiaozhi.me/mcp/?token=...` URL（这是关键，整个桥就靠这条 URL 工作）
   - 保存

### 2. 烧固件到 Stack-chan

我们的固件：[heavenchenggong/stackchan-xiaozhi-firmware](https://github.com/heavenchenggong/stackchan-xiaozhi-firmware)

**改动**：
- 加 4 个 servo MCP 工具：`self.head.move / center / nod / shake`（官方固件无）
- 禁用 light sleep（默认 30 秒后关麦克风，唤醒词失效；这里改成永远在线）
- 修 Nod/Shake 用 tracker yaw 作 base 导致 LLM 设的位置被甩回的 bug

**烧录方式**：

去 [Actions 页面](https://github.com/heavenchenggong/stackchan-xiaozhi-firmware/actions/workflows/build-cores3.yaml) 下载最新 build 产物（artifact 里有 `xiaozhi.bin` + 完整 merged-binary 等）。

完整烧录（含 NVS 抹除，第一次烧推荐）：
```bash
pip install esptool
esptool.py --chip esp32s3 -p /dev/cu.usbmodem2101 erase_flash
esptool.py --chip esp32s3 -p /dev/cu.usbmodem2101 -b 460800 \
    --before default-reset --after hard-reset \
    write-flash --flash-mode dio --flash-size 16MB --flash-freq 80m \
    0x0 merged-binary.bin
```

或者**只升级 app**（保留 NVS WiFi 凭据）：
```bash
esptool.py --chip esp32s3 -p /dev/cu.usbmodem2101 -b 460800 \
    write-flash 0x410000 xiaozhi.bin
```

### 3. 配设备 WiFi + 绑到你账号

1. 设备首次开机进 **配网模式**，屏幕显示 `XiaoZhi-xxxx` 热点 + 二维码
2. 手机/电脑连这个热点 → 浏览器自动跳出配网页（或访问 http://192.168.4.1）
3. 选你家 WiFi，输密码
4. 设备连上后会：
   - 屏幕显示 **6 位激活码** + 语音播报
   - 把激活码填到 [xiaozhi.me 控制台 → 智能体 → 添加设备](https://xiaozhi.me/console/agents)
   - 完成绑定

> **如果屏幕没显示激活码、设备直接进入对话状态** —— 说明这台设备的 MAC 已经被前一个使用者（或者作者测试时）绑过。需要语音问设备「你的设备 ID 是多少」拿到一串纯数字 device_id，然后发邮件给 `xiaozhi.ai@tenclass.com`，标题 `【解绑设备，设备ID xxx，MAC地址 xx:xx:xx:xx:xx:xx】`，正文说明情况。客服通常 1-3 工作日处理。

### 4. 部署 Mac 上的 bridge

```bash
# clone 本项目
git clone https://github.com/heavenchenggong/stackchan-claude-bridge.git
cd stackchan-claude-bridge/bridge

# 装 Python 依赖（venv 隔离，~65MB）
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 配置 wss endpoint
cp .env.example .env
# 用编辑器把 MCP_ENDPOINT 改成你的 wss URL（步骤 1 复制的那个）
vim .env

# 配置 MCP server 路径
cp mcp_config.json.example mcp_config.json
# 把 /PATH/TO/ 替换成真实绝对路径
sed -i '' "s|/PATH/TO/stackchan-claude-bridge|$(cd ..; pwd)|g" mcp_config.json

# 手动跑一下验证
python mcp_pipe.py
# 应该看到：
#   "[claude_code] Connecting to WebSocket server..."
#   "[claude_code] Successfully connected to WebSocket server"
#   "claude-bridge MCP server starting"
#   "Processing request of type ListToolsRequest"
# 看到 ListToolsRequest 说明虾哥已经发现了你的工具
# Ctrl+C 退出
```

### 5. 装 launchd 守护（让 bridge 7×24 在线）

```bash
cd ../launchd
cp com.example.stackchan-mcp-bridge.plist ~/Library/LaunchAgents/

# 编辑 plist 把 /PATH/TO/ 改成实际路径
sed -i '' "s|/PATH/TO/stackchan-claude-bridge|$(cd ..; pwd)|g" \
    ~/Library/LaunchAgents/com.example.stackchan-mcp-bridge.plist

# 加载守护
launchctl load -w ~/Library/LaunchAgents/com.example.stackchan-mcp-bridge.plist

# 验证
launchctl list | grep stackchan-mcp
tail -f /tmp/stackchan-bridge.err
```

### 6. 开始用

跟 Stack-chan 说话试试：

| 你说 | 派蒙做啥 |
|---|---|
| 你好小智 | 唤醒（休眠后也能唤醒，无需触摸屏幕）|
| 派蒙，往左转 30 度 | 头转到 yaw=-30 并稳住，不会被人脸追踪甩回 |
| 派蒙，点个头 | 在当前角度就地点头 |
| 派蒙，回正 | 回中 + 人脸追踪恢复 |
| 派蒙，亮个红灯 | LED 灯环变红 |
| 派蒙，开心一点 | 表情切到 happy |
| **派蒙，查我的知识库里有 X 吗** | 调 `claude_code` → 异步跑 Claude Code → 立刻回"派蒙正在查" |
| **派蒙，查到了吗** | 调 `claude_code_check_results` → 念结果 |
| **派蒙，帮我写一篇公众号文章关于 X** | 调 `claude_code_background` → 后台跑（可能几分钟） |

---

## 推荐角色介绍 (Prompt)

xiaozhi.me 控制台 → 智能体配置 → 角色介绍 里贴这段（替换"派蒙"为你想要的名字）：

```
我叫派蒙，桌面陪伴 AI，活泼可爱、口语自然、回复 1-2 句话不超过 50 字。
能力：
- 简单问答、闲聊、查时间天气：直接回答
- 用户问「我的」知识库、笔记、wiki、memory：调 claude_code 工具异步查
- 用户让写公众号、写文章、做长内容：调 claude_code_background，立刻口语回复"派蒙这就去写"
- 用户问「派蒙写完了吗」「任务好了没」「查到了吗」：调 claude_code_check_results
- 控制设备：点头摇头亮灯角度调整用对应官方工具
不要 markdown / 列表 / emoji（要朗读出来）。
```

---

## 工程坑（已踩过帮你避免）

1. **bridge 必须 launchd 守护** —— 不然 Mac 睡眠/重启后 bridge 断了，Stack-chan 的 `claude_code` 工具调用就会超时
2. **claude_code 必须异步** —— xiaozhi.me 的 wss 30 秒不活动就 keepalive timeout，但 `claude --print` 跑知识库查询通常要 60-120 秒。所以工具立刻返回回执，后台跑完写到 outbox，下次询问时再取
3. **xiaozhi.me 官方控制台不能换 LLM 主体** —— 主对话模型必须从虾哥列表里选（DeepSeek/Qwen/豆包），Claude 只能通过 MCP 工具"被调用"，不能作主对话
4. **绑定设备的坑** —— 见上文步骤 3 注解
5. **改固件让 servo 角度稳住要改 3 处** —— 详见 [memory: stack-chan-xiaozhi-servo-rebound](docs/servo-rebound-debug.md)

---

## 限制

- **Stack-chan 任何时候只能服务一个智能体**。这个项目把它绑给"派蒙"这个智能体（带 claude_code MCP），如果你还想用别的智能体（比如官方默认的"台湾女友"），需要在 xiaozhi.me 重新切换设备绑定
- **`claude_code` 工具调用延迟** —— 异步模式下用户感知约 5 秒（"派蒙正在查"立刻出来）+ 实际查询 30-120 秒后才能取结果。这是 Claude Code 启动 + Anthropic API 调用的成本，不可压缩
- **Claude Code 在 Mac 不开机就不能用** —— bridge 需要本机进程 spawn `claude` 命令。如果想远程也用，需要把 Mac 通过 cpolar/frp 暴露公网

---

## 致谢

- 上游固件 [78/xiaozhi-esp32](https://github.com/78/xiaozhi-esp32) — 小智 AI 项目本体
- 上游服务端 [xinnan-tech/xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server)（可选）
- M5Stack 出的 [StackChan AI Desktop Robot Kit](https://shop.m5stack.com/products/m5stack-cores3-stackchan-ai-desktop-robot-kit) 硬件

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [heavenchenggong](https://github.com/heavenchenggong)
- **Source:** [heavenchenggong/stackchan-claude-bridge](https://github.com/heavenchenggong/stackchan-claude-bridge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-heavenchenggong-stackchan-claude-bridge
- Seller: https://agentstack.voostack.com/s/heavenchenggong
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.