xiaozhi-mcp

A powerful interface for extending AI capabilities through remote control, calculations, email operations, knowledge search, and more.

About

MCP (Model Context Protocol) is a protocol that allows servers to expose tools that can be invoked by language models. This project provides a flexible framework for creating and managing MCP tools, supporting multiple transport types (stdio, SSE, HTTP) and enabling seamless integration between AI models and external systems.

Key Features:

• 🔌 Bidirectional communication between AI and external tools

• 🔄 Automatic reconnection with exponential backoff

• 📊 Real-time data streaming

• 🛠️ Easy-to-use tool creation interface

• 🔒 Secure WebSocket communication

• ⚙️ Multiple transport types support (stdio/sse/http)

How to Install

Using uv (Recommended)

1. Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install dependencies:

uv sync

Using pip

1. Install dependencies:

pip install -r requirements.txt

Requirements:

• 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

How to Run

Run All Configured Servers

Start all enabled servers from the configuration file:

# Using uv
uv run python src/app.py

# Using pip
python src/app.py

Run a Single Server Script

Run a specific server script directly:

# Using uv
uv run python src/app.py src/mcp/tools/calculator.py

# Using pip
python src/app.py src/mcp/tools/calculator.py

Run with Docker

Using Docker Compose (Recommended)

# Copy example docker-compose file
cp docker/docker-compose.example.yml docker-compose.yml

# Start the service (from project root)
docker-compose -f docker-compose.yml up -d

# View logs
docker-compose -f docker-compose.yml logs -f

# Stop the service
docker-compose -f docker-compose.yml down

# Rebuild after code changes
docker-compose -f docker-compose.yml build && docker-compose -f docker-compose.yml up -d

Using Docker directly

# Build the image (from project root)
docker build -f docker/Dockerfile -t xiaozhi-mcp .

# Run the container
docker run -d --name xiaozhi-mcp \
  -v $(pwd)/mcp_config.yaml:/app/mcp_config.yaml:ro \
  xiaozhi-mcp

Building and Pushing Docker Images

Build and push to registry:

# Build image with version tag (from project root)
docker build -f docker/Dockerfile -t xiaozhi-mcp:1.0.0 -t xiaozhi-mcp:latest .

# Tag for registry (replace with your registry address)
docker tag xiaozhi-mcp:latest <registry>/<namespace>/xiaozhi-mcp:latest
docker tag xiaozhi-mcp:1.0.0 <registry>/<namespace>/xiaozhi-mcp:1.0.0

# Push to registry
docker push <registry>/<namespace>/xiaozhi-mcp:latest
docker push <registry>/<namespace>/xiaozhi-mcp:1.0.0

Example - Aliyun Container Registry:

# Example registry address format
REGISTRY="<your-registry>.cn-shanghai.personal.cr.aliyuncs.com"
NAMESPACE="<your-namespace>"

# Build and tag (from project root)
docker build -f docker/Dockerfile -t xiaozhi-mcp:1.0.0 -t xiaozhi-mcp:latest .
docker tag xiaozhi-mcp:latest ${REGISTRY}/${NAMESPACE}/xiaozhi-mcp:latest
docker tag xiaozhi-mcp:1.0.0 ${REGISTRY}/${NAMESPACE}/xiaozhi-mcp:1.0.0

# Push
docker push ${REGISTRY}/${NAMESPACE}/xiaozhi-mcp:latest
docker push ${REGISTRY}/${NAMESPACE}/xiaozhi-mcp:1.0.0

Using the provided script:

# Use the build-and-push.sh script (from project root)
# Script will automatically use docker/Dockerfile and docker/.env
./docker/build-and-push.sh 1.0.0

Using GitHub Actions (Recommended): The project includes a GitHub Actions workflow that automatically builds and pushes Docker images on push to main/dev branches or when tags are created. Configure secrets in your GitHub repository settings. See .github/workflows/README.md for details.

For more Docker build and push options, see docs/DOCKER_BUILD_PUSH.md.

For more Docker deployment options, see docs/DEPLOYMENT.md.

Configs

Configuration files use YAML format:

• mcp_config.yaml - Main configuration file

Configuration Structure

Edit mcp_config.yaml to configure your MCP endpoint and servers:

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

For detailed configuration examples, see docs/CONFIG.md.

Config Loading Priority

1. MCP_CONFIG environment variable (if set, used directly - backward compatibility)

2. mcp_config.yaml (default configuration file)

3. mcp_config.json (fallback, backward compatibility)

Thanks To

• Thanks to all contributors who have helped shape this project

• Inspired by the need for extensible AI capabilities

• Built on top of the MCP (Model Context Protocol) specification

License

This project is licensed under the MIT License - see the LICENSE file for details.