py-xiaozhi

Overview

Py-Xiaozhi is a Python implementation of Xiaozhi AI voice assistant that provides full Xiaozhi experience without specialized hardware. It features AI voice interaction, visual multimodal capabilities, smart wake-up detection, automatic conversation mode, and MCP tool ecosystem integration. The project supports multiple interface modes including GUI (PySide6 + QML), CLI, and GPIO, with cross-platform compatibility for Windows, macOS, and Linux. The architecture includes plugin system, multiple communication protocols (WebSocket/MQTT), and various audio codecs.

Try asking AI

After installing, here are 6 things you can ask your AI assistant:

• music_play

  Play music through the music player

  Try:Play some relaxing musicTry:Play the latest hit songs
• camera_capture

  Capture images using the camera

  Try:Take a photo of the current viewTry:Capture an image for analysis
• screenshot

  Take a screenshot of the current display

  Try:Capture a screenshot of my screenTry:Take a picture of what I'm seeing
• app_control

  Control running applications

  Try:Open the web browserTry:Close the music player
• weather_query

  Get weather information for a location

  Try:What's the weather like today?Try:Check the forecast for tomorrow
• volume_control

  Adjust system volume levels

  Try:Set the volume to 50%Try:Increase the volume

Comparable tools

Installation

# Clone repository
git clone https://github.com/huangjunsen0406/py-xiaozhi.git
cd py-xiaozhi

# Install dependencies (CLI/GPIO mode)
uv sync
# or: pip install -e .

# Install with GUI support
uv sync --extra gui
# or: pip install -e '.[gui]'

# Run the application
python main.py  # GUI mode (default)
python main.py --mode cli  # CLI mode
python main.py --protocol mqtt  # MQTT protocol

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

FAQ

What are the system requirements for Py-Xiaozhi?

Python >= 3.10, microphone and speakers, stable internet connection. Compatible with Windows 10+, macOS 10.15+, and Linux.

How to add custom MCP tools to the system?

Custom tools can be added through the plugin system in the `src/plugins/mcp/tools/` directory. The project supports extending the MCP tool ecosystem with custom implementations.

Can Py-Xiaozhi work offline?

The wake word detection is based on Sherpa-ONNX for offline recognition, but some features require internet connection for cloud AI processing.

Compare py-xiaozhi with