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

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers