Content
# Xiaozhi Client
[](https://badge.fury.io/js/xiaozhi-client)
[](https://codecov.io/gh/shenjingnan/xiaozhi-client)
[](https://github.com/shenjingnan/xiaozhi-client/actions)
[](https://opensource.org/licenses/MIT)
<img src="https://raw.githubusercontent.com/shenjingnan/xiaozhi-client/main/docs/images/qq-group-qrcode.jpg" alt="QQ Group" width="300"/>
Xiaozhi AI Client, primarily used for integration with MCP.
## Table of Contents
1. [Xiaozhi Client](#xiaozhi-client)
1. [Table of Contents](#table-of-contents)
2. [Features](#features)
3. [Quick Start](#quick-start)
1. [Global Installation of xiaozhi-client CLI Tool](#global-installation-of-xiaozhi-client-cli-tool)
2. [Run Directly with npx](#run-directly-with-npx)
3. [Run with Docker](#run-with-docker)
1. [Prerequisites](#prerequisites)
2. [Quick Start](#quick-start-1)
3. [Get Xiaozhi Endpoint Address](#get-xiaozhi-endpoint-address)
4. [Configure Service](#configure-service)
1. [Method 1: Configure via Web UI (Recommended)](#method-1-configure-via-web-ui-recommended)
2. [Method 2: Edit Configuration File Directly](#method-2-edit-configuration-file-directly)
5. [Common Operations](#common-operations)
6. [Troubleshooting](#troubleshooting)
4. [Available Commands](#available-commands)
5. [Multi-Endpoint Configuration](#multi-endpoint-configuration)
1. [Configuration Methods](#configuration-methods)
1. [Method 1: Single Endpoint Configuration (String)](#method-1-single-endpoint-configuration-string)
2. [Method 2: Multi-Endpoint Configuration (Array of Strings)](#method-2-multi-endpoint-configuration-array-of-strings)
2. [Manage Endpoints with Commands](#manage-endpoints-with-commands)
3. [Example Configuration](#example-configuration)
4. [Notes](#notes)
6. [ModelScope MCP Service Integration](#modelscope-mcp-service-integration)
1. [Configuration Method](#configuration-method-1)
2. [Preparation Before Use](#preparation-before-use)
3. [Notes](#notes-1)
7. [Self-Built Server JSON-RPC Message Format Specification](#self-built-server-json-rpc-message-format-specification)
1. [Message Types](#message-types)
1. [1. Request - Requires Response](#1-request---requires-response)
2. [2. Notification - No Response Required](#2-notification---no-response-required)
3. [3. Successful Response](#3-successful-response)
4. [4. Error Response](#4-error-response)
2. [Important Notes](#important-notes)
3. [Communication Sequence Diagram](#communication-sequence-diagram)
4. [Common Errors](#common-errors)
8. [Web UI Configuration Interface](#web-ui-configuration-interface)
1. [Features](#features-1)
2. [Start Web UI](#start-web-ui)
9. [Integrate as MCP Server into Other Clients](#integrate-as-mcp-server-into-other-clients)
1. [Method 1: Use stdio Mode (Recommended)](#method-1-use-stdio-mode-recommended)
2. [Method 2: Use HTTP Server Mode](#method-2-use-http-server-mode)
## Features
- Supports Xiaozhi (xiaozhi.me) official server endpoints
- Can be integrated as a standard MCP Server into clients like Cursor/Cherry Studio
- Supports configuration of multiple Xiaozhi endpoints, allowing multiple Xiaozhi devices to share a single MCP configuration
- Supports standard aggregation of multiple MCP Servers
- Allows dynamic control of MCP Server tool visibility to avoid server anomalies caused by excessive unused tools
- Supports integration of self-hosted open-source servers, allowing you to use the same RPC communication as the official Xiaozhi server or directly use standard MCP integration methods
- Supports web-based visual configuration (allows custom IP and port; you can deploy xiaozhi-client on device A and control it via the web from device B)
- Supports integration of ModelScope's remote MCP services
- Supports creating xiaozhi-client projects via templates (xiaozhi create \<my-app\> --template hello-world)
- Supports running in the background (xiaozhi start -d)
## Quick Start
### Global Installation of xiaozhi-client CLI Tool
```bash
## Install
npm i -g xiaozhi-client
## Create Project
xiaozhi create my-app --template hello-world
## Enter Project Directory
cd my-app
## Install Dependencies (mainly dependencies used in example code for MCP services)
pnpm install
## Initialize Configuration
xiaozhi config init
## Set Endpoint Address (you need to obtain this from xiaozhi.me)
xiaozhi config set mcpEndpoint "your-endpoint-url"
# Xiaozhi AI configuration MCP endpoint usage instructions: https://ccnphfhqs21z.feishu.cn/wiki/HiPEwZ37XiitnwktX13cEM5KnSb
## Run
xiaozhi start
```
### Run Directly with npx
```bash
# Create Project
npx -y xiaozhi-client create my-app --template hello-world
# Enter Project Directory
cd my-app
# Install Dependencies
pnpm install
# Initialize Configuration
npx -y xiaozhi-client config init
# Set Endpoint Address (you need to obtain this from xiaozhi.me)
npx -y xiaozhi-client config set mcpEndpoint "your-endpoint-url"
# Xiaozhi AI configuration MCP endpoint usage instructions: https://ccnphfhqs21z.feishu.cn/wiki/HiPEwZ37XiitnwktX13cEM5KnSb
# Start Service
npx -y xiaozhi-client start
```
### Run with Docker
We provide a pre-configured Docker image to quickly start the xiaozhi-client environment.
#### Prerequisites
- Docker installed
- Xiaozhi endpoint address obtained (see the "[Get Xiaozhi Endpoint Address](#get-xiaozhi-endpoint-address)" section below)
#### Quick Start
**Method 1: Use Startup Script (Recommended)**
This script will automatically perform the following actions:
- Create a working directory `~/xiaozhi-client`
- Pull the specified version of the Docker image
- Stop and remove any existing containers (if any)
- Start a new container and configure port mapping
**Basic Usage:**
> Download and run the startup script (defaults to the latest version)
```bash
curl -fsSL https://raw.githubusercontent.com/shenjingnan/xiaozhi-client/main/docker-start.sh | bash
```
> If you cannot access `Github`, you can use `Gitee` instead
```bash
curl -fsSL https://gitee.com/shenjingnan/xiaozhi-client/raw/main/docker-start.sh | bash
```
**Run with Specified Version:**
The startup script now supports flexible version specification:
```bash
# Download script
curl -fsSL https://raw.githubusercontent.com/shenjingnan/xiaozhi-client/main/docker-start.sh -o docker-start.sh
# Download script (Gitee)
curl -fsSL https://gitee.com/shenjingnan/xiaozhi-client/raw/main/docker-start.sh | bash
# Set executable permissions for the script
chmod +x docker-start.sh
# Use default version (latest)
./docker-start.sh
# Specify version via positional argument
./docker-start.sh v1.6.0
# View help information
./docker-start.sh --help
```
**Method 2: Use Docker Compose**
First, obtain the docker-compose.yml file:
```bash
# Download docker-compose.yml file
curl -O https://raw.githubusercontent.com/shenjingnan/xiaozhi-client/main/docker-compose.yml
# Download docker-compose.yml file (Gitee)
curl -O https://gitee.com/shenjingnan/xiaozhi-client/raw/main/docker-compose.yml
# Start with Docker Compose
docker-compose up -d
# View logs
docker-compose logs -f
# Stop service
docker-compose down
```
**Method 3: Manual Start**
```bash
# Create working directory (for persistent configuration files)
mkdir -p ~/xiaozhi-client
# Pull and run Docker image (run in background)
docker run -d \
--name xiaozhi-client \
-p 9999:9999 \
-p 3000:3000 \
-v ~/xiaozhi-client:/workspaces \
--restart unless-stopped \
shenjingnan/xiaozhi-client
```
**Parameter Explanation**:
- `-d`: Run in background
- `--name xiaozhi-client`: Container name
- `-p 9999:9999`: Web UI configuration interface port
- `-p 3000:3000`: HTTP Server mode port (for integration with other MCP clients)
- `-v ~/xiaozhi-client:/workspaces`: Mount local directory for persistent configuration files and data
- `--restart unless-stopped`: Container auto-restart policy
#### Get Xiaozhi Endpoint Address
Before configuring xiaozhi-client, you need to obtain the Xiaozhi endpoint address:
1. Visit [xiaozhi.me](https://xiaozhi.me) and log in
2. Go to the MCP configuration page
3. Create a new endpoint or use an existing one
4. Copy the endpoint address (format: `wss://api.xiaozhi.me/mcp/your-endpoint-id`)
For detailed configuration instructions, please refer to: [Xiaozhi AI Configuration MCP Endpoint Usage Instructions](https://ccnphfhqs21z.feishu.cn/wiki/HiPEwZ37XiitnwktX13cEM5KnSb)
#### Configure Service
After the container starts, there are two ways to configure xiaozhi-client:
##### Method 1: Configure via Web UI (Recommended)
1. Open your browser and visit: <http://localhost:9999>
2. Set your Xiaozhi endpoint address in the Web UI
3. Configure other MCP services (optional)
##### Method 2: Edit Configuration File Directly
1. After the first startup, the container will create a default configuration file in the `~/xiaozhi-client` directory. If the file does not exist, you can create it manually:
```bash
# Create configuration file
cat > ~/xiaozhi-client/xiaozhi.config.json << 'EOF'
{
"mcpEndpoint": "",
"mcpServers": {},
"modelscope": {
"apiKey": ""
},
"connection": {
"heartbeatInterval": 30000,
"heartbeatTimeout": 10000,
"reconnectInterval": 5000
},
"webUI": {
"port": 9999
}
}
EOF
```
2. Edit the configuration file to modify the `mcpEndpoint` field:
```bash
# Edit configuration file
vim ~/xiaozhi-client/xiaozhi.config.json
```
Change `mcpEndpoint` to your actual endpoint address:
```json
{
"mcpEndpoint": "wss://api.xiaozhi.me/mcp/your-actual-endpoint-id"
}
```
3. Restart the container to apply the configuration:
```bash
docker restart xiaozhi-client
```
#### Common Operations
```bash
# View logs
docker logs -f xiaozhi-client
# Stop service
docker stop xiaozhi-client
# Start service
docker start xiaozhi-client
# Restart service
docker restart xiaozhi-client
# Remove container (note: configuration files will remain in ~/xiaozhi-client)
docker rm -f xiaozhi-client
# Check service status
docker exec -it xiaozhi-client xiaozhi status
# List all MCP services
docker exec -it xiaozhi-client xiaozhi mcp list
# List all tools provided by MCP
docker exec -it xiaozhi-client xiaozhi mcp list --tools
```
#### Troubleshooting
**Issue 1: Container Startup Failure**
```bash
# Check container status
docker ps -a | grep xiaozhi-client
# View detailed error logs
docker logs xiaozhi-client
```
**Issue 2: Unable to Access Web UI (http://localhost:9999)**
- Check if the container is running: `docker ps | grep xiaozhi-client`
- Check if the port is occupied: `lsof -i :9999` (macOS/Linux) or `netstat -ano | findstr :9999` (Windows)
- Ensure firewall settings allow access to port 9999
**Issue 3: Configuration File Not Effective**
- Confirm the configuration file path: `ls -la ~/xiaozhi-client/xiaozhi.config.json`
- Check if the configuration file format is correct (JSON syntax)
- Restart the container: `docker restart xiaozhi-client`
**Issue 4: Failed to Connect to Xiaozhi Server**
- Check if the endpoint address is correct
- Ensure network connectivity is normal
- View container logs: `docker logs -f xiaozhi-client`
**Issue 5: Port Conflict**
If the default port is occupied, you can modify the port mapping:
```bash
# Start with different ports
docker run -d \
--name xiaozhi-client \
-p 8888:9999 \
-p 3001:3000 \
-v ~/xiaozhi-client:/workspaces \
--restart unless-stopped \
shenjingnan/xiaozhi-client
```
Then access <http://localhost:8888> for configuration.
## Available Commands
### Basic Commands
```bash
# View help
xiaozhi --help
# View version information
xiaozhi --version
# View detailed system information
xiaozhi --info
```
### Project Management
```bash
# Create project
xiaozhi create my-app --template hello-world
# Initialize configuration file
xiaozhi config init
# View configuration
xiaozhi config get mcpEndpoint
# Set configuration
xiaozhi config set mcpEndpoint "your-endpoint-url"
```
### Service Management
```bash
# Start service (foreground)
xiaozhi start
# Start service in background
xiaozhi start -d
# Start and open Web UI
xiaozhi start -u
# Start in MCP Server mode (for clients like Cursor)
xiaozhi start --stdio
# View service status
xiaozhi status
# Stop service
xiaozhi stop
# Restart service
xiaozhi restart
# Attach background service to foreground
xiaozhi attach
```
### MCP Management
```bash
# List all MCP services
xiaozhi mcp list
# List all MCP tools
xiaozhi mcp list --tools
# View specific service
xiaozhi mcp server calculator
```
### Endpoint Management
```bash
# List all endpoints
xiaozhi endpoint list
# Add endpoint
xiaozhi endpoint add "ws://new-server:8080"
# Remove endpoint
xiaozhi endpoint remove "ws://old-server:8080"
```
### Web UI
```bash
# Start Web configuration interface
xiaozhi ui
```
> 📖 **Detailed Usage Instructions**: See [CLI User Manual](docs/CLI.md) for complete command references and usage examples.
## Multi-Endpoint Configuration
xiaozhi-client supports connecting to multiple Xiaozhi AI endpoints simultaneously.
### Configuration Methods
In `xiaozhi.config.json`, the `mcpEndpoint` field supports two configuration methods:
#### Method 1: Single Endpoint Configuration (String)
```json
{
"mcpEndpoint": "wss://api.xiaozhi.me/mcp/your-endpoint-id"
}
```
#### Method 2: Multi-Endpoint Configuration (Array of Strings)
```json
{
"mcpEndpoint": [
"wss://api.xiaozhi.me/mcp/endpoint-1",
"wss://api.xiaozhi.me/mcp/endpoint-2",
"wss://api.xiaozhi.me/mcp/endpoint-3"
]
}
```
### Manage Endpoints with Commands
```bash
# View all currently configured endpoints
xiaozhi endpoint list
# Add a new endpoint
xiaozhi endpoint add "wss://api.xiaozhi.me/mcp/new-endpoint"
# Remove a specified endpoint
xiaozhi endpoint remove "wss://api.xiaozhi.me/mcp/old-endpoint"
# Set a single endpoint (overrides existing configuration)
xiaozhi endpoint set "wss://api.xiaozhi.me/mcp/endpoint-1"
# Or use config command to set
xiaozhi config set mcpEndpoint "wss://api.xiaozhi.me/mcp/endpoint-1"
```
### Example Configuration
```json
{
"mcpEndpoint": [
"wss://api.xiaozhi.me/mcp/305847/abc123",
"wss://api.xiaozhi.me/mcp/468832/def456"
],
"mcpServers": {
"calculator": {
"command": "node",
"args": ["./mcpServers/calculator.js"]
},
"datetime": {
"command": "node",
"args": ["./mcpServers/datetime.js"]
}
}
}
```
### Notes
- When configuring multiple endpoints, each endpoint will start an independent MCP process.
- Ensure that each endpoint's URL is valid.
- Endpoints are independent of each other; a failure in one endpoint will not affect others.
- It is recommended to configure the number of endpoints reasonably based on actual needs.
## ModelScope MCP Service Integration
xiaozhi-client now supports integration with the MCP services hosted by [ModelScope](https://www.modelscope.cn/mcp).
### Configuration Method
Add SSE type configuration in `xiaozhi.config.json` under `mcpServers`:
```json
{
"mcpServers": {
"amap-maps": {
"type": "sse",
"url": "https://mcp.api-inference.modelscope.net/caa0bd914d9b44/sse"
}
}
}
```
### Preparation Before Use
1. Obtain ModelScope API Token:
- Visit [ModelScope](https://www.modelscope.cn) and log in
- Get the API Token in your personal center
2. Configure API Token (choose one of the two methods):
**Method 1: Set in Configuration File (Recommended)**
```json
{
"modelscope": {
"apiKey": "your API Token"
}
}
```
**Method 2: Set Environment Variable**
```bash
export MODELSCOPE_API_TOKEN="your API Token"
```
3. Start the service:
```bash
xiaozhi start
```
### Notes
- ModelScope MCP services require a valid API Token to use.
- The API Token in the configuration file takes precedence over the environment variable.
- Ensure that the network can access ModelScope's service endpoints.
- SSE type services will automatically recognize and use the appropriate connection method.
## Self-Built Server JSON-RPC Message Format Specification
If you are using a self-built MCP server, please ensure compliance with the following JSON-RPC 2.0 message format specification:
### Message Types
#### 1. Request - Requires Response
```json
{
"jsonrpc": "2.0",
"method": "methodName",
"params": {},
"id": 1 // Must include id field, can be a number or string
}
```
Supported request methods:
- `initialize` - Initialize connection
- `tools/list` - Get tool list
- `tools/call` - Call tool
- `ping` - Connection test
#### 2. Notification - No Response Required
```json
{
"jsonrpc": "2.0",
"method": "methodName",
"params": {}
// Note: Cannot include id field
}
```
Supported notification methods:
- `notifications/initialized` - Notification of initialization completion
#### 3. Successful Response
```json
{
"jsonrpc": "2.0",
"result": {},
"id": 1 // Must be the same as the request's id
}
```
#### 4. Error Response
```json
{
"jsonrpc": "2.0",
"error": {
"code": -32600,
"message": "Error description"
},
"id": 1 // Must be the same as the request's id
}
```
### Important Notes
1. **Key Difference**: The only difference between requests and notifications is whether the `id` field is included.
- With `id` = Request, requires response
- Without `id` = Notification, no response required
2. **"notifications/initialized" must be sent as a notification**:
```json
// ✅ Correct
{
"jsonrpc": "2.0",
"method": "notifications/initialized"
}
// ❌ Incorrect - should not include id
{
"jsonrpc": "2.0",
"method": "notifications/initialized",
"id": 1
}
```
3. **Message Separation**: Each JSON-RPC message must end with a newline character `\n`.
4. **Communication Flow**:
1. Client sends `initialize` request
2. Server returns `initialize` response
3. Client sends `notifications/initialized` notification (no response required)
4. Subsequent queries and calls for tool lists can be made
### Communication Sequence Diagram
```mermaid
sequenceDiagram
participant Client as Xiaozhi Client
participant Server as Self-Built MCP Server
Note over Client,Server: Initialization Phase
Client->>Server: {"jsonrpc":"2.0","method":"initialize","params":{...},"id":1}
Server->>Client: {"jsonrpc":"2.0","result":{...},"id":1}
Client->>Server: {"jsonrpc":"2.0","method":"notifications/initialized"}
Note over Server: No response required for notification
Note over Client,Server: Get Tool List
Client->>Server: {"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}
Server->>Client: {"jsonrpc":"2.0","result":{"tools":[...]},"id":2}
Note over Client,Server: Call Tool
Client->>Server: {"jsonrpc":"2.0","method":"tools/call","params":{...},"id":3}
Server->>Client: {"jsonrpc":"2.0","result":{...},"id":3}
Note over Client,Server: Maintain Connection
Client->>Server: {"jsonrpc":"2.0","method":"ping","params":{},"id":4}
Server->>Client: {"jsonrpc":"2.0","result":{},"id":4}
Note over Client,Server: Error Handling Example
Client->>Server: {"jsonrpc":"2.0","method":"unknown_method","params":{},"id":5}
Server->>Client: {"jsonrpc":"2.0","error":{"code":-32601,"message":"Method not found"},"id":5}
```
### Common Errors
If you see an error like "Unknown method: notifications/initialized", it is usually because the `id` field was incorrectly included in the notification message, causing the client to recognize it as a request instead of a notification.
## Web UI Configuration Interface
xiaozhi-client provides a modern Web UI interface, making MCP service configuration more intuitive and convenient.
### Features
- 🎨 **Modern Interface**: Built with React + TypeScript + Tailwind CSS
- 🔧 **Visual Configuration**: Intuitive interface operations, no need to manually edit JSON files
- 🚀 **Real-time Connection Status**: Displays real-time connection status with Xiaozhi server
- 📦 **MCP Service Management**:
- Add/Edit/Delete MCP services
- Supports local services and SSE services
- Supports batch import of configurations
- ⚙️ **Configuration Management**:
- Edit connection parameters (heartbeat interval, timeout, etc.)
- Manage ModelScope API Key
### Start Web UI
```bash
# Start Web configuration interface
xiaozhi ui
# Or start Web UI while starting the service
xiaozhi start -u
```
After starting, visit <http://localhost:9999> for visual configuration.
## Integrate as MCP Server into Other Clients
> Requires version `1.5.0` or above
xiaozhi-client can not only be used as a client for Xiaozhi AI but also as a standard MCP Server integrated into clients like Cursor and Cherry Studio that support the MCP protocol.
The benefit of this approach is that you do not need to repeat the MCP Server configuration in multiple clients; just configure the MCP service once in `xiaozhi.config.json`, and it can be integrated into any client.
Moreover, since xiaozhi-client allows you to customize which MCP Server tools to expose, you can selectively tailor your toolset.
### Method 1: Use stdio Mode (Recommended)
Step 1: Ensure xiaozhi-client is installed globally:
```bash
npm install -g xiaozhi-client
```
Step 2: Add to the MCP configuration of the client:
```json
{
"mcpServers": {
"xiaozhi-client": {
"command": "xiaozhi",
"args": ["start", "--stdio"]
}
}
}
```
Tip: If you need to specify the configuration file location, you can use environment variables.
Configuration file search order:
1. Current working directory
2. Directory specified by `XIAOZHI_CONFIG_DIR` environment variable
```json
{
"mcpServers": {
"xiaozhi-client": {
"command": "xiaozhi",
"args": ["start", "--stdio"],
"env": {
"XIAOZHI_CONFIG_DIR": "/path/to/your/config/directory"
}
}
}
}
```
### Method 2: Use HTTP Server Mode
> If you are using xiaozhi-client in Docker, you can expose it to external clients via HTTP server mode.
Step 1: Start the xiaozhi-client HTTP Server:
```bash
# Use default port 3000
xiaozhi start -s
# Use custom port
xiaozhi start -s 8080
# Run in background
xiaozhi start -s -d
```
Step 2: Configure SSE connection in the client:
```json
{
"mcpServers": {
"xiaozhi-client": {
"type": "sse",
"url": "http://localhost:3000/sse"
}
}
}
```
