How do I use xiaozhi-bridge?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@xiaozhi-bridge open google.com in the browser" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

xiaozhi-bridge

by weemadscotsman

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

🦞 PURPCLAW v7.0 — ULTIMATE

The AI Voice Agent MCP Bridge — Gives your Xiaozhi AI hardware full autonomous PC control via 58 MCP tools. Built by WEEMADSCOTSMAN at Pixel Dynasty.

🚀 New Here? Read the Full Setup Guide →

The setup guide covers everything from buying the hardware to your first voice command. Anyone with a Xiaozhi ball can use this.

What Is This?

PURPCLAW is an MCP (Model Context Protocol) bridge that connects a Xiaozhi AI voice agent to your Windows PC. It turns a voice-enabled AI ball into a fully autonomous engineering assistant that can:

🖥️ See your screen — Screenshots + OCR text recognition
📸 See YOU — Webcam capture, face/object detection
🌐 Browse the web — Playwright-powered: click links, fill forms, read pages
📁 Manage files — Read, write, copy, move, delete, search, zip/extract
🖱️ Control your desktop — Mouse clicks, keyboard typing, window management
⬇️ Download files — Direct URL downloads
📦 Install packages — pip, npm, or choco
🔊 Control audio — Volume up/down/mute/set
🔧 Run commands — Shell execution with injection protection
🧠 Remember things — Persistent memory across sessions
🦞 Run AI pipelines — Start/stop/monitor PURPCLAW build pipelines

Related MCP server: WinCommander

Architecture

┌──────────────────┐     WebSocket      ┌──────────────────┐
│   Xiaozhi Ball   │ ◄──────────────── │  xiaozhi_bridge   │
│  (DeepSeek V3.1) │   MCP Protocol    │     v7.0.0        │
└──────────────────┘                   └────────┬─────────┘
                                                │
                              ┌─────────────────┼─────────────────┐
                              │                 │                 │
                        ┌─────┴─────┐   ┌──────┴──────┐   ┌─────┴─────┐
                        │ Playwright │   │ PowerShell  │   │  Python   │
                        │  Browser   │   │  .NET APIs  │   │  OpenCV   │
                        └───────────┘   └─────────────┘   └───────────┘

58 MCP Tools

Vision (5)

Tool	Description
`screen_capture`	Screenshot the screen
`screen_ocr`	Read text from screen via OCR
`screen_find_object`	Detect objects with YOLO
`screen_find_template`	Find image on screen (template match)
`screen_info`	Get monitor sizes

Webcam (3)

Tool	Description
`webcam_look`	Take a photo with PC webcam
`webcam_detect`	Detect people/faces/objects
`webcam_read`	OCR text visible to camera

Mouse & Keyboard (3)

Tool	Description
`mouse_click`	Click, double-click, right-click, drag
`mouse_scroll`	Scroll wheel
`keyboard_type`	Type text or press shortcuts

UI Automation (1)

Tool	Description
`find_and_click`	Find and click UI elements by text

Window Management (3)

Tool	Description
`window_list`	List open windows
`window_focus`	Focus a window by title
`window_close`	Close a window

File System (8)

Tool	Description
`file_read`	Read file contents
`file_write`	Write/append to files
`file_list`	List directory contents
`file_search`	Search by name or content (Node.js, fast)
`file_copy`	Copy files/directories
`file_move`	Move/rename files
`file_delete`	Delete files (system path protected)
`dir_create`	Create directories

Browser (9) — Playwright-Powered

Tool	Description
`browser_open`	Open URL with full interaction
`browser_click`	Click links/buttons by visible text
`browser_type`	Type into form fields
`browser_scroll`	Scroll pages up/down
`browser_get_content`	Read page text content
`browser_screenshot`	Screenshot the browser
`browser_navigate`	Navigate: goto/back/forward/reload
`browser_tabs`	List open tabs
`browser_close_tab`	Close a tab

Downloads (1)

Tool	Description
`download_file`	Download file from URL

Process Management (2)

Tool	Description
`process_list`	List running processes
`process_kill`	Kill process by name/PID (critical procs blocked)

Audio (1)

Tool	Description
`volume_control`	Set volume, mute/unmute, up/down

Archives (2)

Tool	Description
`zip_create`	Create zip archives
`zip_extract`	Extract zip archives

Package Management (1)

Tool	Description
`install_package`	Install via pip/npm/choco

PURPCLAW Pipeline (4)

Tool	Description
`purpclaw_start`	Start AI build pipeline
`purpclaw_stop`	Stop pipeline
`purpclaw_status`	Get pipeline status
`purpclaw_logs`	Read pipeline logs

Git (1)

Tool	Description
`git_command`	Run git commands

Communication (4)

Tool	Description
`http_request`	HTTP GET/POST/PUT/DELETE
`clipboard`	Read/write clipboard
`speak`	Text-to-speech via Kokoro TTS
`notification`	Desktop toast notifications

Context & System (5)

Tool	Description
`active_window`	Get focused window info
`system_status`	CPU, RAM, process overview
`disk_info`	Drive space for all disks
`network_info`	IP, WiFi, internet status
`execute_command`	Execute shell commands (injection-proof)

Apps & Tasks (4)

Tool	Description
`open_application`	Launch apps by name
`memory`	Persistent remember/recall/forget/list
`task_schedule`	Schedule delayed tasks
`task_list`	List scheduled tasks

Setup

Prerequisites

Node.js 18+
Python 3.10+ with opencv-python
Playwright (npm i playwright)
Xiaozhi.me account + configured agent

Install

git clone https://github.com/weemadscotsman/purpclaw.git
cd purpclaw
npm install
cp .env.example .env
# Edit .env with your Xiaozhi MCP token

Run

# Windows (recommended)
start_xiaozhi_bridge.bat

# Or manually
set XIAOZHI_MCP_URL=wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN
node lib/xiaozhi_bridge.js

Environment Variables

Variable	Description
`XIAOZHI_MCP_URL`	WebSocket URL from Xiaozhi MCP settings
`OPENCLAW_GATEWAY`	OpenClaw WebSocket (default: `ws://127.0.0.1:18789`)
`MCP_BRIDGE_URL`	Bridge HTTP server (default: `http://localhost:3001`)

Security

Shell injection protection — All user input is sanitized via san() function
System path protection — Cannot delete Windows/Program Files/AppData
Critical process protection — Cannot kill explorer, csrss, lsass, svchost
Destructive command blocking — Blocks format, recursive system deletes, shutdown
Tool timeout — Every tool has a timeout to prevent hanging

Tech Stack

Runtime: Node.js (single-process, async event loop)
Browser: Playwright (Chromium, headless: false)
Vision: Python OpenCV + Haar cascade face detection
Screen: .NET System.Drawing (fast screenshot via PowerShell)
Shell: PowerShell -NoProfile -NonInteractive (fast startup)
Protocol: MCP over WebSocket (JSON-RPC 2.0)

Built With

Created by Eddie Cannon (@weemadscotsman) — Edinburgh, Scotland 🏴󠁧󠁢󠁳󠁣󠁴󠁿

Pixel Dynasty — Gaming Archive & Collab Hub
NDK Threads — ndkthreads.com
PixelBits420 — Fair-launch cryptocurrency

License

MIT

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

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Superforms B
co.superforms
Human-input bridge for AI agents with voice-first answer links, MCP tools, and HTTP APIs.
Agent Orchestration Speech Processing App Automation
112
dittu A
io.github.BorisGujvin
Turns a phone into a camera+Bluetooth remote so AI assistants can see and control any PC.
Image & Video Processing OS Automation
122
nexusOAuth
com.civic
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Agent Orchestration Developer Tools App Automation
2
china-market-intelligence-mcpOAuth
com.thenextgennexus
MCP server giving AI agents one-connection access to China A-share market intelligence: financials,
Finance Research & Data
2

Related MCP Servers

mcp-windows-server
OS Automation Browser Automation
mukul975
A
license
Not graded
quality
D
maintenance
Enables AI assistants to control Windows systems through natural language commands, providing 200+ automation tools for system control, file operations, web automation, and more.
Updated 3 months ago (2026-06-03 22:11 UTC)
52
MIT
WinCommander
Shell Access Browser Automation OS Automation
Chaiyuhao
F
license
Not graded
quality
B
maintenance
Turns any Windows device into a remotely controllable MCP toolset, allowing a mobile AI agent to execute CLI, GUI, browser, and system commands on Windows without an API key.
Updated 2 months ago (2026-07-05 01:14 UTC)
2
-
Windows-MCP
OS Automation Testing & QA Tools Shell Access
Books-QAQ
F
license
Not graded
quality
B
maintenance
Enables AI agents to seamlessly integrate with the Windows operating system, performing tasks such as file navigation, application control, UI interaction, and QA testing via the MCP protocol.
Updated 24 days ago (2026-08-20 12:17 UTC)
-
xiaozhi-pc-control
OS Automation Command Line Shell Access
violet-05
F
license
Not graded
quality
C
maintenance
MCP server enabling voice-controlled Windows PC automation via Xiaozhi AI, supporting 200+ apps, media playback control, and terminal command execution.
Updated a month ago (2026-08-06 05:54 UTC)
1
-