home / mcp / xiaozhi mcp server

Xiaozhi MCP Server

Exposes MCP tools via a configurable server with stdio transport for AI integration.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "botwith-xiaozhi-mcp": {
      "command": "python",
      "args": [
        "src/mcp/tools/calculator.py"
      ]
    }
  }
}

You run an MCP server to expose tools that language models can invoke, enabling bidirectional control, calculations, and data-driven actions through a configurable, transport-flexible interface. This guide shows practical steps to install, configure, and use the server with an MCP client.

How to use

You connect an MCP client to the server endpoint and load the configured tools. Start by ensuring your MCP endpoint is reachable and your servers are enabled in the configuration. Use a client or orchestration that supports MCP to initiate a session, request available tools, and invoke a tool like a calculator. Tools run locally or remotely according to their transport type, and results stream back in real time. Use the calculator tool to perform arithmetic operations during your AI workflows, or extend with additional stdio tools as defined in your configuration.

How to install

Prerequisites are Python 3.10 or newer and the libraries required by the MCP runtime.

Install the runtime via one of the supported methods.

# Using uv (Recommended) 
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

# Using pip
pip install -r requirements.txt

# Prerequisites shown by the project include:
# - Python 3.10+
# - websockets>=16.0
# - python-dotenv>=1.2.1
# - mcp>=1.25.0
# - pydantic>=2.12.5
# - mcp-proxy>=0.11.0
# - fastmcp>=2.14.3
# - httpx>=0.28.1
# - yfinance>=1.0
# - pyyaml>=6.0.3
"} ,{

Configs

Configure your MCP endpoint and servers in a YAML file named mcp_config.yaml. The example below shows a local stdio-based calculator tool that runs as a separate Python process.

mcp:
  endpoint: ws://your-endpoint-url/mcp
  token: your-token-here  # Optional
  
  servers:
    local-stdio-calculator:
      enabled: true
      type: stdio
      command: python
      args:
        - src/mcp/tools/calculator.py
```"}]} ,{

Notes and tips

The server supports multiple transport types; in this example, a local stdio tool is shown. If you later add HTTP-based servers, provide a URL in the config and ensure the command and arguments reflect how you start the remote service.

Security and deployment considerations

Keep the MCP endpoint secured with tokens if you expose it over the network. Use environment variables to inject secrets and keep your mcp_config.yaml under version control with sensitive values managed separately in production.

Troubleshooting

Connection failures to the MCP endpoint
Misconfigured server names
Missing command arguments for stdio servers

Available tools

calculator

A calculator tool implemented as a Python script exposed through MCP, enabling arithmetic operations from an AI client.