Skip to main content
Glama
deenesjakoruzh
Joho6666

XiaoZhi Windows MCP Agent Bridge

by Joho6666
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

XiaoZhi Windows MCP Agent Bridge

XiaoZhi Windows MCP Agent Bridge is a bridge service that connects an ESP32 XiaoZhi AI device with a microphone and speaker on your desktop to a local Windows computer.

Through the standard Model Context Protocol (MCP), XiaoZhi can act as a Voice Commander, invoking local Windows tools, performing computer operations, reading and writing files across the entire disk, controlling the Edge browser, capturing screenshots for visual analysis, and, most importantly, orchestrating a matrix of local AI Agents such as Codex CLI / Claude Code / OpenCode to execute heavy development and engineering tasks.

Overall Architecture: Voice Commander + Local Agent Matrix

小智 ESP32 硬件 (麦克风/喇叭/屏幕)
       ↓ (语音交互)
 xiaozhi.me 官方云端 (ASR / LLM / TTS / MCP Client)
       ↓ (WebSocket JSON-RPC 2.0)
 XiaoZhi Windows Agent Bridge (本机 Python 进程)
       ↓
  Tool Registry (注册 49 个本地能力工具)
       ↓
┌─────────────────┬─────────────────┬─────────────────┬─────────────────┐
│ Windows 应用    │ 本地文件系统    │ 终端与 PowerShell│ 多 Agent 调遣器 │
│ • 智能启动/搜索 │ • 全盘/目录遍历 │ • Safe Terminal │ • Codex CLI 主力│
│ • 进程聚焦/退出 │ • 文件读写/删除 │ • 任意 Shell    │ • Claude / Open │
├─────────────────┼─────────────────┼─────────────────┼─────────────────┤
│ Desktop GUI     │ 屏幕视觉 (Vision│ Edge 浏览器     │ Skills/Workflow │
│ • 窗口枚举/点击 │ • 内存屏幕截图  │ • 网页搜索/打开 │ • 声明式 Skill  │
│ • 文本输入/按键 │ • MCP Image 回传│ • 页面提取/点击 │ • YAML 工作流   │
└─────────────────┴─────────────────┴─────────────────┴─────────────────┘

Related MCP server: agentic-remote-pc

Core Features and Voice Commands

Feature Category

Voice Command Example

Underlying Tool

Agent Dispatch

"XiaoZhi, have Codex add Wi-Fi reconnection logic to my ESP32 project"

dispatch_agent(agent_type="codex", task="...", mode="modify")

Agent Progress

"XiaoZhi, is the Codex task from earlier done?"

get_agent_status() (returns a concise voice summary and change statistics)

Agent List

"XiaoZhi, which agents can work on my computer?"

list_active_agents() (detects Codex, Claude, OpenCode, etc.)

Launch Software

"XiaoZhi, open VS Code" / "open Feishu"

open_application (intelligently scans the Start Menu and PATH)

Screen Vision

"XiaoZhi, look at what's on my screen"

screen_capture (in-memory screenshot sent back for multimodal analysis)

File Search

"XiaoZhi, see what PDFs are on the desktop"

find_files(path="Desktop", pattern="*.pdf")

File Read/Write

"XiaoZhi, help me read this config / write a Snake game"

read_text_file / write_text_file

Project Git

"XiaoZhi, see what's changed recently in my project"

git_status / git_diff / git_log

Terminal Execution

"XiaoZhi, run this project's tests / check the Python version"

run_project_tests / run_shell_command

Browser Interaction

"XiaoZhi, search for the ESP32-S3 datasheet"

browser_search / browser_open

Quick Setup and Startup

1. Environment Preparation

  • Windows 10 / 11

  • Python 3.11+

  • (Optional) Installed Codex CLI (npm i -g @openai/codex), Claude Code, etc.

Install dependencies:

pip install -r requirements.txt

2. Configure the MCP Endpoint

Copy .env.example to .env and fill in the Endpoint obtained from the XiaoZhi console:

XIAOZHI_MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN_HERE

3. Configure the Workspace (Optional)

Add your local development project paths to config.yaml:

workspaces:
  agent:
    path: .
  esp32:
    path: D:/Projects/esp32
  stm32:
    path: D:/Projects/stm32

4. Run the Agent

python main.py

The terminal will output:

===================================
 XiaoZhi Windows Agent
===================================
XiaoZhi MCP     CONNECTING
Tools           49
Security        ENABLED
Permission      UNRESTRICTED
MCP server handshake completed
Connected; registered 49 local tools

Automated Testing

Run the full test suite:

python -m pytest

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers