小智 AI MCP 桥接 / Xiaozhi AI MCP Bridge

让小智 AI 通过 MCP 协议调用本机能力，支持多接入点管理、消息互发、工具自检，并提供 Web 管理面板。 Enable Xiaozhi AI to access local capabilities via the MCP protocol, with multi-endpoint management, inter-agent messaging, self-testing, and a Web dashboard.

🇨🇳 中文

功能特性

• 40+ 工具：文件操作、多引擎搜索、天气、系统命令、开发者工具、代码执行、消息互发

• 多引擎聚合搜索：必应 + 360 双引擎并行，自动去重，完全免费无限制

• 多小智接入点管理：Web 面板可同时配置多个小智 AI 接入点，分别启动/停止

• 消息交换机：多个小智端之间互发消息（类邮件），支持撤回、已读位置追踪、防重复读取

• 工具自检平台：模拟 MCP 客户端自动测试所有工具服务器，输出通过/失败报告

• Web 管理面板：多接入点管理、连接测试、工具测试、实时日志

• 守护进程：异常兜底、退避重启、刷屏自愈、2 小时定期重启

• 双平台支持：Windows（自动 UAC 提权 + 零窗口静默版）、Linux（权限绑定）

• 权限继承：启动脚本的权限决定所有 MCP 服务进程的权限

架构

小智云端 A (wss://api.xiaozhi.me)   小智云端 B (wss://api.xiaozhi.me)
       │                                    │
       ▼                                    ▼
   mcp_exe (桥接A)                    mcp_exe (桥接B)
       │                                    │
       └────────── 共享 stdio MCP servers ──┘
              ├── filesystem   本机文件操作
              ├── web          必应+360聚合搜索 + 网页抓取
              ├── weather      Open-Meteo 天气
              ├── system       系统/命令/dsh/密码/二维码/单位换算/自检
              ├── dev          JSON/Base64/URL/时间戳/UUID/Hash/正则/DNS/HTTP/端口
              ├── code         Python/C/Bash 代码执行
              └── message      消息交换机（≥2接入点时自动启用）

Web 管理面板 (http://localhost:37246)
       ├── 多接入点管理（添加/删除/启动/停止）
       ├── 连接测试
       ├── 本地工具测试
       └── 实时日志

快速开始

一键部署（推荐）/ One-Click Deploy：

# Linux
curl -fsSL https://raw.githubusercontent.com/ZnFr60/xiaozhi-mcp-bridge/main/install-linux.sh | bash

# Windows — 下载 install-windows.bat 双击运行
# https://raw.githubusercontent.com/ZnFr60/xiaozhi-mcp-bridge/main/install-windows.bat

手动部署 / Manual：

# 1. 安装依赖 / Install dependencies
cd xiaozhi-mcp-bridge
npm install

# 2. 配置小智接入点 / Configure endpoint
cp config.example.js config.js
# 编辑 config.js，填入你的小智 WSS token

# 3. Linux 启动
chmod +x start.sh
./start.sh

# 4. Windows 启动
# 双击 start-windows.bat（自动提权）
# 或 start-windows-silent.vbs（零窗口静默）

启动后访问 http://localhost:37246 打开管理面板。

命令行配置

除了 Web 面板，也可用命令行管理接入点：

# 查看配置状态
node config-cli.js status

# 添加接入点（添加第2个后消息交换机自动启用）
node config-cli.js add "我的小智" "wss://api.xiaozhi.me/mcp/?token=xxx"

# 列出所有接入点
node config-cli.js list

# 删除接入点
node config-cli.js remove <接入点ID>

# 设置默认接入点 token（写入 config.js）
node config-cli.js token "wss://api.xiaozhi.me/mcp/?token=xxx"

工具列表

消息交换机

当系统检测到 ≥2 个小智接入点时，自动启用以下两个工具：

• send_message：发送消息（action=send）、撤回消息（action=recall）、列出用户（action=list_users）

• read_messages：读取新消息（action=read，自动更新已读位置防重复）、列收件箱/发件箱、查看/重置已读位置

消息以 JSON 文件轻量存储（每用户3个文件），撤回不删除消息而是标记 recalled=true。

工具自检

# 命令行运行完整自检
node test-harness.js

# 只测试某个服务器
node test-harness.js system

# JSON 格式输出
node test-harness.js --json

小智端也可直接调用 run_self_test 工具触发自检。

关键注意事项

1. zod 版本锁定：zod@3.25.76 同时写在 dependencies 和 overrides 中（双重保障），全局安装时也能生效，否则 mcp_exe 报 _fieldsToZodSchema 错误

2. mcp.json 动态生成：启动时 guardian.js 从 mcp.template.json 自动生成 mcp.json，所有路径基于安装目录动态解析，无需手动修改

3. token 保密：小智 WSS token 存储在 config.js，已加入 .gitignore，不会提交到公开仓库

4. 搜索：必应 + 360 双引擎聚合，百度/搜狗反爬严格无法抓取

5. 守护机制：30秒启动宽限期 + 刷屏自愈（阈值100KB/10s）+ 2小时定期重启

6. UI 端口：默认 37246，可通过环境变量 PORT 修改

7. 消息工具：仅在配置 ≥2 个接入点时出现，单个接入点时自动隐藏

8. 代理环境：mcp_exe 的 WebSocket 默认不支持 HTTP 代理，有代理的环境需用 proxychains 等工具包装或在无代理环境运行

Related MCP server: Atlas MCP Server

🇬🇧 English

Features

• 40+ tools: file operations, multi-engine search, weather, system commands, dev tools, code execution, inter-agent messaging

• Multi-engine aggregated search: Bing + 360 parallel fetching, auto-dedup, completely free with no limits

• Multi-endpoint management: configure and manage multiple Xiaozhi AI endpoints from the Web dashboard

• Message exchange: send messages between Xiaozhi agents (email-like), with recall, read-position tracking, and duplicate prevention

• Self-test harness: simulates an MCP client to automatically test all tool servers and report pass/fail

• Web dashboard: multi-endpoint management, connectivity test, tool testing, real-time logs

• Guardian process: crash recovery, exponential backoff, spam self-healing, 2h periodic restart

• Cross-platform: Windows (auto UAC elevation + zero-window silent mode), Linux (permission binding)

• Permission inheritance: the permission level of the launch script determines the permission of all MCP service processes

Architecture

Xiaozhi Cloud A (wss://api.xiaozhi.me)   Xiaozhi Cloud B (wss://api.xiaozhi.me)
       │                                          │
       ▼                                          ▼
   mcp_exe (bridge A)                      mcp_exe (bridge B)
       │                                          │
       └────────── shared stdio MCP servers ──────┘
              ├── filesystem   Local file operations
              ├── web          Bing+360 aggregated search + page fetch
              ├── weather      Open-Meteo weather
              ├── system       System/cmd/dsh/password/QR/unit conversion/self-test
              ├── dev          JSON/Base64/URL/Timestamp/UUID/Hash/Regex/DNS/HTTP/Port
              ├── code         Python/C/Bash execution
              └── message      Message exchange (auto-enabled with ≥2 endpoints)

Web Dashboard (http://localhost:37246)
       ├── Multi-endpoint management (add/remove/start/stop)
       ├── Connectivity test
       ├── Local tool testing
       └── Real-time logs

Quick Start

One-Click Deploy (recommended):

# Linux
curl -fsSL https://raw.githubusercontent.com/ZnFr60/xiaozhi-mcp-bridge/main/install-linux.sh | bash

# Windows — download install-windows.bat and double-click
# https://raw.githubusercontent.com/ZnFr60/xiaozhi-mcp-bridge/main/install-windows.bat

Manual:

# 1. Install dependencies
cd xiaozhi-mcp-bridge
npm install

# 2. Configure Xiaozhi endpoint
cp config.example.js config.js
# Edit config.js and fill in your Xiaozhi WSS token

# 3. Start on Linux
chmod +x start.sh
./start.sh

# 4. Start on Windows
# Double-click start-windows.bat (auto elevation)
# or start-windows-silent.vbs (zero-window silent)

Then open http://localhost:37246 for the dashboard.

CLI Configuration

Manage endpoints from the command line (in addition to the Web dashboard):

# View config status
node config-cli.js status

# Add endpoint (message exchange auto-enables with >=2 endpoints)
node config-cli.js add "My Xiaozhi" "wss://api.xiaozhi.me/mcp/?token=xxx"

# List all endpoints
node config-cli.js list

# Remove endpoint
node config-cli.js remove <endpoint-id>

# Set default endpoint token (writes to config.js)
node config-cli.js token "wss://api.xiaozhi.me/mcp/?token=xxx"

Tool List

Message Exchange

When ≥2 Xiaozhi endpoints are configured, the following two tools are automatically enabled:

• send_message: send (action=send), recall (action=recall), list users (action=list_users)

• read_messages: read new messages (action=read, auto-updates read position to prevent duplicates), list inbox/outbox, view/reset read position

Messages are stored as lightweight JSON files (3 files per user). Recall marks recalled=true instead of deleting.

Self-Test

# Run full self-test from CLI
node test-harness.js

# Test a single server
node test-harness.js system

# JSON output
node test-harness.js --json

Xiaozhi can also call the run_self_test tool directly.

Important Notes

1. zod version lock: zod@3.25.76 is pinned in both dependencies and overrides (double protection), works with global installs; otherwise mcp_exe crashes with _fieldsToZodSchema

2. Dynamic mcp.json: guardian.js generates mcp.json from mcp.template.json at startup, all paths resolved relative to install dir — no manual editing needed

3. Token security: Xiaozhi WSS token is stored in config.js, which is gitignored and never committed

4. Search: Bing + 360 aggregated; Baidu/Sogou have strict anti-bot protection

5. Guardian: 30s startup grace period + spam self-healing (100KB/10s threshold) + 2h periodic restart

6. UI port: default 37246, configurable via PORT environment variable

7. Message tools: only appear when ≥2 endpoints are configured; auto-hidden otherwise

8. Proxy environments: mcp_exe's WebSocket does not support HTTP proxies by default; use proxychains or run in a proxy-free environment

文件说明 / File Structure

License

MIT