MCPgee
MCPgee
MCPgeeMCPgee

Py Xiaozhi

v1.0.0•Cloud Services•stable

A Python-based Xiaozhi AI for users who want the full Xiaozhi experience without owning specialized hardware.

cross-platformedge-computingembodied-aiesp32esp32-s3
Share:
3,323
Stars
0
Downloads
0
Weekly
0/5
View on GitHub

What is Py Xiaozhi?

Py Xiaozhi is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to python-based xiaozhi ai for users who want the full xiaozhi experience without owning specialized hardware.

A Python-based Xiaozhi AI for users who want the full Xiaozhi experience without owning specialized hardware.

This server falls under the Cloud Services category on MCPgee, the world's largest MCP server directory with 33,000+ servers.

Features

  • A Python-based Xiaozhi AI for users who want the full Xiaozh

Use Cases

Run Xiaozhi AI without specialized hardware.
Build edge AI systems on ESP32 and IoT devices.
huangjunsen0406

Maintainer

LicenseMIT
Languagepython
Versionv1.0.0
UpdatedMay 22, 2026
Statushealthy
Maintenanceactive

Works with

ClaudeOpenAIwindowsmacoslinux
View SourceBrowse All Servers

Installation

Manual Installation

npx py-xiaozhi

Configuration

Configuration Details

Config File

claude_desktop_config.json

Performance

Response Metrics

Response Time< 200ms
ThroughputMedium

Resource Usage

Memory UsageLow
CPU UsageLow

How to Set Up and Use Py Xiaozhi

py-xiaozhi is a Python implementation of the Xiaozhi AI assistant that runs on standard PC hardware, replicating the experience of the dedicated ESP32-based Xiaozhi device without requiring proprietary hardware. It provides real-time voice streaming with sub-20ms latency via the Opus codec, offline wake-word detection, multi-modal vision via camera capture, and an extensible MCP tool ecosystem covering music playback, weather, volume control, and application management. Developers and hobbyists who want to experiment with embodied AI, IoT integration, or voice-controlled agents on desktop hardware will find py-xiaozhi a complete starting point.

Prerequisites

  • Python 3.10, 3.11, or 3.12 (3.13 not yet supported)
  • Working microphone and speaker hardware
  • 4 GB RAM minimum (8 GB recommended), modern CPU with AVX support
  • uv package manager (recommended) or pip
  • Stable internet connection for cloud AI backend
1

Clone the repository

Clone the py-xiaozhi source code to your local machine.

git clone https://github.com/huangjunsen0406/py-xiaozhi.git
cd py-xiaozhi
2

Install base dependencies

Install the core dependencies using uv sync. Add the --extra gui flag if you want the graphical desktop interface with PySide6.

# CLI mode only (minimal dependencies):
uv sync

# GUI mode (includes PySide6 and qasync):
uv sync --extra gui
3

Configure the application

Copy the example configuration and fill in your Xiaozhi backend credentials, WebSocket endpoint, and any optional API keys for weather or music services.

cp config/config.example.yaml config/config.yaml
# Edit config/config.yaml with your settings
4

Download wake-word models (optional)

For offline wake-word detection, download the Sherpa-ONNX models referenced in the documentation. This step is optional; without it, wake-word detection is disabled.

# Follow the model download instructions in the documentation:
# https://github.com/huangjunsen0406/py-xiaozhi/blob/main/docs/
python scripts/download_models.py
5

Run the assistant

Start py-xiaozhi in your chosen mode. GUI mode opens a desktop window; CLI mode runs in the terminal with minimal dependencies.

# GUI mode (default):
python main.py

# CLI mode:
python main.py --mode cli

# Specify protocol:
python main.py --protocol websocket

Py Xiaozhi Examples

Client configuration

py-xiaozhi acts as its own AI client rather than as a subprocess of Claude Desktop. If you want to expose its MCP tools to an external client, the server runs locally on WebSocket. The configuration below is for reference if integrating with an external MCP client.

{
  "mcpServers": {
    "py-xiaozhi": {
      "command": "python",
      "args": ["main.py", "--mode", "cli"],
      "cwd": "/path/to/py-xiaozhi"
    }
  }
}

Prompts to try

Speak or type these commands to py-xiaozhi to exercise the built-in MCP tools.

- "Play some jazz music"
- "Take a photo with the camera"
- "What's the weather like today?"
- "Turn the volume up to 80 percent"
- "Take a screenshot of my desktop"

Troubleshooting Py Xiaozhi

No audio input detected or microphone not found

Verify your microphone is recognized by the OS before launching. On Linux, check with arecord -l. Ensure PyAudio or sounddevice can access the device and that no other application is holding the microphone exclusively.

Python version compatibility errors at startup

py-xiaozhi supports Python 3.10–3.12. If you have 3.13 installed, create a virtual environment with an earlier version: uv venv --python 3.12 && uv sync.

GUI fails to start with PySide6 import errors

GUI mode requires the extra dependencies. Re-install with uv sync --extra gui or pip install -e '.[gui]'. On Linux, also ensure libGL is installed: sudo apt-get install libgl1.

Frequently Asked Questions about Py Xiaozhi

What is Py Xiaozhi?

Py Xiaozhi is a Model Context Protocol (MCP) server that python-based xiaozhi ai for users who want the full xiaozhi experience without owning specialized hardware. It connects AI assistants to external tools and data sources through a standardized interface.

How do I install Py Xiaozhi?

Follow the installation instructions on the Py Xiaozhi GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.

Which AI clients work with Py Xiaozhi?

Py Xiaozhi works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.

Is Py Xiaozhi free to use?

Yes, Py Xiaozhi is open source and available under the MIT license. You can use it freely in both personal and commercial projects.

Learn More About MCP Servers

Getting Started with MCP

Set up your first MCP server in minutes

MCP Setup Guide

Configure MCP in Claude, Cursor & VS Code

All MCP Tutorials

18+ hands-on guides for developers

MCP FAQ

40+ answers about Model Context Protocol

Py Xiaozhi Alternatives — Similar Cloud Services Servers

Looking for alternatives to Py Xiaozhi? Here are other popular cloud services servers you can use with Claude, Cursor, and VS Code.

Open WebUI

★ 138.2k

User-friendly AI Interface (Supports Ollama, OpenAI API, ...)

Anything LLM

★ 60.4k

The all-in-one AI productivity accelerator. On device and privacy first with no annoying setup or configuration.

LocalAI

★ 46.4k

LocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.

Nacos

★ 33.0k

an easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.

Xiaozhi ESP32

★ 26.7k

本项目为xiaozhi-esp32提供后端服务，帮助您快速搭建ESP32设备控制服务器。Backend service for xiaozhi-esp32, helps you quickly build an ESP32 device control server.

Gateway

★ 11.8k

A blazing fast AI Gateway with integrated guardrails. Route to 1,600+ LLMs, 50+ AI Guardrails with 1 fast & friendly API.

Browse More Cloud Services MCP Servers

Explore all cloud services servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.

Cloud ServicesBrowse All Servers

Quick Config Preview

{ "mcpServers": { "py-xiaozhi": { "command": "npx", "args": ["-y", "py-xiaozhi"] } } }

Add this to your claude_desktop_config.json or .cursor/mcp.json

Read the full setup guide →

Ready to use Py Xiaozhi?

Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.

33,000+ ServersFree & Open SourceStep-by-Step Guides
Explore All ServersRead Our Guides