py-xiaozhi is a Python-implemented MCP server that exposes a rich set of MCP tools and IoT capabilities designed to work with the Xiaozhi-inspired AI assistant. The server integrates a modular MCP toolkit alongside an IoT device management layer, enabling you to perform system control, scheduling, timed tasks, music playback, travel/booking search, web content search, recipe lookup, mapping, astrology tooling, and camera-based AI analysis. It also supports secure communication via WebSocket/MQTT and provides both GUI and CLI interfaces, making it suitable for embedded devices or desktop environments. Use the included MCP tools to monitor and manage applications, control devices, schedule tasks, query external services, and interact with the audio processing stack that powers wake words, voice activity detection, and speech recognition.

To run the server, start it with Python. The MCP server will expose its toolset under the configured entry point so you can invoke individual tools via the MCP interface, integrate with your home automation, or extend the tool set by adding new MCP modules under src/mcp/tools/.

Prerequisites:

• Python 3.9–3.12
• Git
• Internet access to install dependencies

Step-by-step installation:

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

2. Create a virtual environment (recommended) python -m venv venv source venv/bin/activate # On Windows use: venv\Scripts\activate

3. Install Python dependencies pip install -r requirements.txt

4. Run the MCP server (CLI or GUI)

   CLI mode

   python main.py --mode cli

   GUI mode (default)

   python main.py

5. Optional: configure protocol and other settings via command line options or the config system as described in the project documentation.

Tips and common considerations:

• Ensure your Python version matches the supported range (3.9–3.12).
• If you add new MCP tools under src/mcp/tools/, the server should pick them up as plugins; follow the existing tool architecture for compatibility.
• For offline AI features (wake word, VAD, etc.), ensure optional models (e.g., Sherpa-ONNX) are downloaded if you enable those features.
• The server supports both GUI and CLI operation; use the CLI for headless environments and the GUI for interactive use.
• If you run into dependency issues after updates, re-run the installation step to refresh requirements.
• WebSocket and MQTT are supported protocols; choose one via the CLI flag or configuration to fit your network environment.