🦞 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

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