Xiaozhi Client：集成MCP（微服务通信协议）的多功能AI客户端

Xiaozhi Client 多功能AI客户端，集成MCP（微服务通信协议），作为官方小智AI服务的客户端，能以标准MCP Server的形式集成到Cursor、Cherry Studio等第三方客户端，实现MCP配置的集中管理与多设备共享。Xiaozhi Client支持配置和聚合多个小智AI接入点，动态控制MCP工具的可见性，能无缝对接本地部署的开源服务端或远程ModelScope托管的MCP服务。Xiaozhi Client提供了强大的命令行工具集和现代化的Web UI界面，极大地简化了MCP服务的可视化配置与管理，避免了手动编辑JSON文件的繁琐，严格遵循JSON-RPC 2.0通信规范，明确定义了请求、通知和响应格式，便于开发者构建兼容的自建MCP服务端，支持stdio和HTTP Server两种集成模式，提供了灵活的部署方式。

• 接入小智（xiaozhi.me）官方服务器接入点

• 作为普通MCP Server集成到Cursor、Cherry Studio等客户端

• 配置多个小智接入点，实现多个小智设备共享一个MCP配置

• 通过标准方式聚合多个MCP Server

• 动态控制MCP Server工具的可见性，避免因无用工具过多导致的小智服务端异常

• 集成本地化部署的开源服务端，可使用和小智官方服务端一样的RPC通信或标准MCP集成方式

• 提供Web网页可视化配置，允许自定义IP和端口，支持跨设备控制（如部署在设备A，在设备B通过网页控制）

• 集成ModelScope的远程MCP服务

• 通过模板创建xiaozhi-client项目（命令：xiaozhi create <my-app> --template hello-world）

• 支持后台运行（命令：xiaozhi start -d）

全局安装和使用

1、安装命令行工具：npm i -g xiaozhi-client

2、创建项目：xiaozhi create my-app --template hello-world

3、进入项目目录：cd my-app

4、安装依赖（主要是示例代码中mcp服务所需依赖）：pnpm install

5、修改xiaozhi.config.json中的mcpEndpoint为你的接入点地址（需前往xiaozhi.me获取）

6、运行服务：xiaozhi start

通过npx直接运行

1、创建项目：npx -y xiaozhi-client create --template hello-world

2、进入项目目录：cd hello-world

3、安装依赖：pnpm install

4、修改xiaozhi.config.json中的mcpEndpoint为你的接入点地址（需前往xiaozhi.me获取）

5、启动服务：npx -y xiaozhi-client start

Xiaozhi Client 可用命令

• 查看帮助：xiaozhi --help

• 启动服务：xiaozhi start

• 后台启动服务：xiaozhi start --daemon

• 将后台服务转到前台运行：xiaozhi attach

• 查看服务状态：xiaozhi status

• 停止服务：xiaozhi stop

• 重启服务：xiaozhi restart

• 列出所有使用的mcp服务：xiaozhi mcp list

• 列出所有mcp所提供的tools：xiaozhi mcp list --tools

多接入点配置

xiaozhi-client支持同时连接多个小智AI接入点，配置方式有两种：

配置文件设置

• 单接入点配置（字符串）：

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

• 多接入点配置（字符串数组）：

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

命令管理接入点

• 查看当前配置的所有接入点：xiaozhi endpoint list

• 添加新的接入点：xiaozhi endpoint add wss://api.xiaozhi.me/mcp/new-endpoint

• 移除指定的接入点：xiaozhi endpoint remove wss://api.xiaozhi.me/mcp/old-endpoint

• 设置接入点（覆盖现有配置）：xiaozhi endpoint set wss://api.xiaozhi.me/mcp/endpoint-1 wss://api.xiaozhi.me/mcp/endpoint-2

示例配置

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

注意事项

• 多接入点配置时，每个接入点会启动独立的MCP进程 • 确保每个接入点的URL有效 • 接入点之间相互独立，一个接入点故障不影响其他接入点 • 建议根据实际需求合理配置接入点数量

ModelScope MCP服务集成

xiaozhi-client支持接入ModelScope托管的MCP服务，配置和使用步骤如下：

配置方式

在xiaozhi.config.json的mcpServers中添加SSE类型配置：

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

使用前准备

1、获取ModelScope API Token：

• 访问ModelScope并登录 • 在个人中心获取API Token

2、配置API Token（两种方式选其一）： • 方式一（推荐）：在配置文件中设置

{
    "modelscope": {
    "apiKey": "你的API Token"
    }
}

• 方式二：设置环境变量

export MODELSCOPE_API_TOKEN="你的API Token"

3、启动服务：xiaozhi start

注意事项

• ModelScope MCP服务需要有效的API Token才能使用

• 配置文件中的API Token优先级高于环境变量

• 确保网络能够访问ModelScope的服务端点

• SSE类型的服务会自动识别并使用相应的连接方式

自建服务端JSON-RPC消息格式规范

若使用自建的MCP服务端，需遵循JSON-RPC 2.0消息格式规范，具体如下：

消息类型

1、请求（Request）- 需要响应

{
  "jsonrpc": "2.0",
  "method": "方法名",
  "params": {},
  "id": 1 // 必须包含id字段，可以是数字或字符串
}

支持的请求方法：initialize（初始化连接）、tools/list（获取工具列表）、tools/call（调用工具）、ping（连接测试）

2、通知（Notification）- 不需要响应

{
  "jsonrpc": "2.0",
  "method": "方法名",
  "params": {}
  // 注意：不能包含id字段
}

支持的通知方法：notifications/initialized（初始化完成通知）

3、成功响应（Response）

{
  "jsonrpc": "2.0",
  "result": {},
  "id": 1 // 必须与请求的id相同
}

4、错误响应（Error）

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "错误描述"
  },
  "id": 1 // 必须与请求的id相同
}

重要注意事项

• 请求和通知的唯一区别是是否包含id字段：有id为请求，需要响应；无id为通知，不需要响

• "notifications/initialized"必须作为通知发送（不应包含id）

• 正确示例：

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

• 错误示例（包含id）：

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

• 每条JSON-RPC消息必须以换行符\n结束

通信流程

1、客户端发送initialize请求

2、服务端返回initialize响应

3、客户端发送notifications/initialized通知（无需响应）

4、后续可进行工具列表查询和调用

Web UI配置界面

xiaozhi-client提供现代化Web UI界面，方便直观配置MCP服务，主要功能包括：

• 现代化界面：基于React + TypeScript + Tailwind CSS构建

• 可视化配置：无需手动编辑JSON文件，通过界面操作完成配置

• 实时连接状态：显示与小智服务器的连接状态

• MCP服务管理：添加/编辑/删除MCP服务，支持本地服务和SSE服务，支持批量导入配置

• 配置管理：编辑连接参数（心跳间隔、超时时间等），管理ModelScope API Key

启动Web UI

运行命令：xiaozhi ui

作为MCP Server集成到其他客户端

需升级至1.5.0及以上版本，xiaozhi-client可作为标准MCP Server被Cursor、Cherry Studio等支持MCP协议的客户端集成。这样只需在xiaozhi.config.json中配置一遍MCP服务，就能在任意客户端集成，还可自定义暴露的MCP Server tools，定制工具集。

集成方式

方式一：使用stdio模式（推荐）

1、确保已全局安装xiaozhi-client：npm install -g xiaozhi-client

2、在客户端的MCP配置中添加：

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

提示：如需指定配置文件位置，可使用环境变量。配置文件的查找顺序为：当前工作目录、通过XIAOZHI_CONFIG_DIR环境变量指定的目录。示例：

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

方式二：使用HTTP Server模式

若将xiaozhi-client装在docker中，可通过http server方式暴露给外部客户端：

1、启动xiaozhi-client的HTTP Server：

• 使用默认端口3000：xiaozhi start --server • 使用自定义端口：xiaozhi start --server 8080 • 后台运行：xiaozhi start --server --daemon

2、在客户端中配置SSE连接：

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