Xiaozhi Client: MCP Server Aggregator for Cursor and XiaoZhi AI

Xiaozhi Client is a versatile AI utility built on the Model Context Protocol. It connects to the official XiaoZhi AI service while simultaneously functioning as a standard MCP server. You can integrate it with Cursor, Cherry Studio, or any other MCP-compatible environment to centralize all your configurations in one place and share them across different devices.

The client gives you total control over tool visibility, allowing you to aggregate multiple MCP servers into a single interface. You can switch between locally hosted backends and remote ModelScope MCP services with ease. The stack includes a modern Web UI and a robust CLI, eliminating the need for manual JSON editing.

• Connect to official xiaozhi.me service endpoints.
• Operate as a dedicated MCP server within Cursor or Cherry Studio.
• Sync a single MCP configuration across multiple XiaoZhi devices.
• Consolidate several MCP servers using standardized protocols.
• Toggle tool visibility to maintain stable service performance.
• Integrate local open-source servers via RPC or standard MCP.
• Use a web-based visual configuration tool with custom IP and port settings.
• Access remote ModelScope MCP service support.
• Rapid project setup: xiaozhi create <my-app> --template hello-world.
• Background execution via daemon mode: xiaozhi start -d.

Global Installation

1. Install the CLI tool:
   npm i -g xiaozhi-client

2. Initialize a new project:
   xiaozhi create my-app --template hello-world

3. Navigate to the project directory:
   cd my-app

4. Install the necessary dependencies for the example MCP servers:
   pnpm install

5. Edit the xiaozhi.config.json file and set the mcpEndpoint to the value provided by xiaozhi.me.

6. Launch the service:
   xiaozhi start

Run Directly with npx

1. Create your project:
   npx -y xiaozhi-client create --template hello-world

2. Enter the new directory:
   cd hello-world

3. Install dependencies:
   pnpm install

4. Add your mcpEndpoint to xiaozhi.config.json.

5. Launch the client:
   npx -y xiaozhi-client start

Available Commands

• Display help: xiaozhi --help
• Start the service: xiaozhi start
• Run as a background daemon: xiaozhi start --daemon
• Move the daemon to the foreground: xiaozhi attach
• Check current status: xiaozhi status
• Stop the service: xiaozhi stop
• Restart the service: xiaozhi restart
• List active MCP services: xiaozhi mcp list
• List all tools across all services: xiaozhi mcp list --tools

Multiple Endpoint Configuration

Xiaozhi Client can communicate with several XiaoZhi AI endpoints simultaneously.

Configuration File Method

For a single endpoint:

{
  "mcpEndpoint": "wss://api.xiaozhi.me/mcp/your-endpoint-id"
}

For multiple endpoints:

{
  "mcpEndpoint": [
    "wss://api.xiaozhi.me/mcp/endpoint-1",
    "wss://api.xiaozhi.me/mcp/endpoint-2",
    "wss://api.xiaozhi.me/mcp/endpoint-3"
  ]
}

Command Line Management

• View current endpoints: xiaozhi endpoint list
• Add a new endpoint: xiaozhi endpoint add wss://api.xiaozhi.me/mcp/new-endpoint
• Remove an existing endpoint: xiaozhi endpoint remove wss://api.xiaozhi.me/mcp/old-endpoint
• Replace all endpoints: xiaozhi endpoint set wss://... endpoint-2

Complete Configuration Example

{
  "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"]
    }
  }
}

Every endpoint initializes an independent MCP process. This ensures that a failure in one endpoint does not affect the others. It is recommended to keep this list concise to maintain optimal performance.

ModelScope MCP Integration

Xiaozhi Client is compatible with MCP services hosted on the ModelScope platform.

To integrate, add an SSE entry to your xiaozhi.config.json:

{
  "mcpServers": {
    "amap-maps": {
      "type": "sse",
      "url": "https://mcp.api-inference.modelscope.net/caa0bd914d9b44/sse"
    }
  }
}

Prerequisites

1. Obtain a ModelScope API Token from your account dashboard.

2. Configure the token using one of these two methods:

   Option A (Config File):

   { "modelscope": { "apiKey": "your-token-here" } }

   Option B (Environment Variable):

   export MODELSCOPE_API_TOKEN="your-token-here"

3. Launch the service with xiaozhi start. Note that the token in the configuration file takes precedence over the environment variable.

Self-Hosted Server: JSON-RPC Specification

If you are developing a custom MCP backend, ensure it follows the JSON-RPC 2.0 standard.

Message Formats

Standard Request (requires a response):

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {},
  "id": 1
}

Currently supported methods include: initialize, tools/list, tools/call, and ping.

Notification (requires no response):

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

Notifications must not include an id field.

Success Response:

{
  "jsonrpc": "2.0",
  "result": {},
  "id": 1
}

Error Response:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid Request"
  },
  "id": 1
}

All JSON-RPC messages must be terminated with a newline character (\n).

Standard Interaction Flow

1. The client sends an initialize request.
2. The server responds to the initialize request.
3. The client sends a notifications/initialized message (without an id).
4. The system then proceeds to list and execute tools.

Web UI

The client includes a dedicated Web UI for visual management.

• Developed using React, TypeScript, and Tailwind CSS.
• Manage MCP services without manually editing JSON files.
• View real-time connection status for XiaoZhi servers.
• Add, update, or remove local and SSE MCP services.
• Import configurations in bulk.
• Fine-tune heartbeat intervals, connection timeouts, and ModelScope API keys.

To open the interface, run:

xiaozhi ui

Integrating as an MCP Server

Starting with version 1.5.0, Xiaozhi Client can function as a standard MCP server for other tools like Cursor or Cherry Studio. Once configured in xiaozhi.config.json, all connected clients will access the same toolset, and you can define exactly which tools are exposed.

Method 1: stdio Mode (Recommended)

1. Install the client globally:

   npm install -g xiaozhi-client

2. Add the following to your AI client's MCP configuration:

   { "mcpServers": { "xiaozhi-client": { "command": "xiaozhi", "args": ["start", "--stdio"] } } }

3. To use a custom configuration path, set the XIAOZHI_CONFIG_DIR environment variable:

   { "mcpServers": { "xiaozhi-client": { "command": "xiaozhi", "args": ["start", "--stdio"], "env": { "XIAOZHI_CONFIG_DIR": "/path/to/your/config/directory" } } } }

Method 2: HTTP Server Mode

This mode is ideal for Docker deployments.

Launch the HTTP server:

• On the default port (3000): xiaozhi start --server
• On a specific port: xiaozhi start --server 8080
• As a background process: xiaozhi start --server --daemon

Then, connect via SSE in your chosen client:

{
  "mcpServers": {
    "xiaozhi-client": {
      "type": "sse",
      "url": "http://localhost:3000/sse"
    }
  }
}