Skip to content

mcp2xiaozhi — connecting AI protocols to open-source hardware

mcp2xiaozhi

Bridge any MCP server (stdio / SSE / StreamableHTTP) to a Xiaozhi server over WebSocket.

PyPI Python License: MIT CI

The Xiaozhi server acts as an MCP client over a WebSocket: it sends JSON-RPC tool calls as text frames and expects JSON-RPC replies. mcp2xiaozhi receives those frames and relays them — at the protocol level — to your MCP server, wherever it runs and whatever transport it speaks.

                 JSON-RPC over WebSocket (text frames)
   ┌──────────────────────┐   wss://…    ┌──────────────────────┐
   │   Xiaozhi server     │ ◄──────────► │   mcp2xiaozhi bridge │
   │  (acts as MCP client)│              └──────────┬───────────┘
   └──────────────────────┘                          │  JSON-RPC
                              ┌──────────────────────┴───────────────┐
                              │   stdio        │   SSE   │   HTTP    │
                              ▼                ▼         ▼           ▼
                         local process    remote server          remote server

Features

  • 🔄 Three transports, one bridge — stdio, sse, streamablehttp (http), all native, no mcp-proxy subprocess.
  • 🧱 Protocol-level relay — frames parsed as JSONRPCMessage (wrapped in the SDK's SessionMessage), validated, re-serialized. Malformed frames are dropped, not fatal.
  • 🔁 Automatic reconnection — exponential backoff with jitter; clean closes distinguished from abnormal ones.
  • 🗂️ Multi-server — run one bridge or every server in your config; each server gets its own endpoint.
  • 🖥️ Cross-platform — UTF-8 console handling on Windows, graceful SIGINT/SIGTERM shutdown.
  • 📦 Real package — PyPI, CLI, type hints, 42 tests, CI, uv-managed.

Install

uv tool install mcp2xiaozhi
# or, in a project:
uv add mcp2xiaozhi

pip install mcp2xiaozhi

Next steps