Xiaozhi MCP

小智mcp

一个强大的界面，用于通过远程控制、计算、电子邮件操作、知识搜索等扩展人工智能功能。

关于

MCP（模型上下文协议）是一种允许服务器公开可由语言模型调用的工具的协议。该项目为创建和管理MCP工具提供了一个灵活的框架，支持多种传输类型（stdio、SSE、HTTP），并实现了AI模型和外部系统之间的无缝集成。

主要特点：

• 🔌 AI与外部工具之间的双向通信
• 🔄 指数回退自动重新连接
• 📊 实时数据流
• 🛠️ 易于使用的工具创建界面
• 🔒 安全的WebSocket通信
• ⚙️ 支持多种传输类型（stdio/sse/http）

如何安装

使用紫外线（推荐）

1. 安装紫外线：

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

1. 安装依赖项：

uv sync

使用pip

1. 安装依赖项：

pip install -r requirements.txt

要求：

• Python 3.10+
• websockets>=16.0
• python dotenv>=1.2.1
• mcp>=1.25.0
• 媒染剂>=2.12.5
• mcp代理>=0.11.0
• fastmcp>=2.14.3
• httpx>=0.28.1
• 融资>=1.0
• Pyyaml>=6.0.3

如何跑步

运行所有已配置的服务器

从配置文件启动所有已启用的服务器：

# Using uv
uv run python src/app.py

# Using pip
python src/app.py

运行单服务器脚本

直接运行特定的服务器脚本：

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

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

使用Docker运行

使用Docker Compose（推荐）

# 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

直接使用Docker

# 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

构建和推送Docker镜像

构建并推送到注册表：

# 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 //xiaozhi-mcp:latest
docker tag xiaozhi-mcp:1.0.0 //xiaozhi-mcp:1.0.0

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

示例-阿里云容器注册表：

# Example registry address format
REGISTRY=".cn-shanghai.personal.cr.aliyuncs.com"
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

使用提供的脚本：

# 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

使用GitHub操作（推荐）： 该项目包括一个GitHub Actions工作流，该工作流在将Docker镜像推送到主/开发分支或创建标签时自动构建和推送Docker镜像。在GitHub存储库设置中配置secrets。看 了解详情。

有关更多Docker构建和推送选项，请参阅 .

有关更多Docker部署选项，请参阅 文档/部署.md.

配置

配置文件使用YAML格式：

• mcp_config.yaml -主配置文件

配置结构

编辑 mcp_config.yaml 要配置MCP端点和服务器，请执行以下操作：

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

有关详细的配置示例，请参阅 docs/CONFIG.md.

配置加载优先级

1. MCP_CONFIG 环境变量（如果设置，直接使用-向后兼容）
2. mcp_config.yaml （默认配置文件）
3. mcp_config.json （回退、向后兼容性）

多亏了

• 感谢所有帮助塑造这个项目的贡献者
• 受到对可扩展AI功能需求的启发
• 基于MCP（模型上下文协议）规范构建

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。