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: PC Controller MCP Server

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

Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Related MCP Connectors

ZionDeskOAuth
app.ziondesk
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
File Systems Command Line Browser Automation
1
https://mcp.ziondesk.app/mcp
PC Remote CommanderOAuth
io.github.pcremotecommander
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
File Systems Command Line Browser Automation
11
https://pc-remote-commander.pcremotecommander.workers.dev/mcp
DNS-DATA RemoteOAuthDeprecated
com.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
File Systems Command Line OS Automation
11
https://mcp.dns-data.com/mcp
Remote Desktop Commander BOAuth
app.desktopcommander
Remote Desktop Commander: use files, terminal and processes on your own computers from any AI app.
Shell Access OS Automation
292203
https://mcp.desktopcommander.app/mcp

Related MCP Servers

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 2 months ago (2026-09-09 15:27 UTC)
2
-
PC Controller MCP Server
Shell Access File Systems OS Automation
rayss868
A
license
A
quality
B
maintenance
Enables AI assistants to control Windows PCs by executing shell commands, managing files, capturing screenshots, and monitoring system information through a comprehensive set of MCP tools.
Updated 2 months ago (2026-09-09 02:53 UTC)
18
1
MIT
XiaoZhi Windows MCP Agent
Agent Orchestration OS Automation Shell Access
Joho6666
A
license
Not graded
quality
C
maintenance
Enables ESP32 XiaoZhi voice devices to command a Windows PC via MCP, including app control, file operations, screen vision, browser interaction, shell execution, and orchestration of local AI coding agents like Codex CLI and Claude Code.
Updated 2 months ago (2026-08-23 09:51 UTC)
2
MIT
GPT-to-Windows
OS Automation File Systems Shell Access
LaurenceFang
F
license
Not graded
quality
B
maintenance
Enables AI agents to control and interact with a local Windows computer through authenticated MCP tools, including file operations, shell commands, process management, HTTP requests, and system/media inspection.
Updated 2 months ago (2026-09-14 15:10 UTC)
-