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)

Install uv:

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

Install dependencies:

uv sync

Using pip

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

MCP_CONFIG environment variable (if set, used directly - backward compatibility)
mcp_config.yaml (default configuration file)
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.