evolution MCP

进化MCP服务器

MCP（模型上下文协议）服务器，用于与WhatsApp Evolution API集成。

📋 描述

这个服务器提供了MCP工具，用于管理WhatsApp实例并通过Evolution API发送消息。

🚀 功能

该服务器提供以下MCP工具：

1. 创建实例

创建一个新的WhatsApp实例。

参数：

• instanceName （必填）：实例的唯一名称
• qrcode （可选）：生成二维码（默认：true）
• integration （可选）：集成类型（默认：“WHATSAPP-BAILEYS”）

示例：

{
  "instanceName": "minha_instancia",
  "qrcode": true,
  "integration": "WHATSAPP-BAILEYS"
}

2. 删除实例

删除一个现有的实例。

参数：

• instanceName （必填）：要删除的实例名称

示例：

{
  "instanceName": "minha_instancia"
}

3. 检查WhatsApp号码

验证哪些号码在WhatsApp上是有效的。

参数：

• instanceName (必填)：实例名称
• numbers （必填）：待验证的号码列表

示例：

{
  "instanceName": "minha_instancia",
  "numbers": ["5511999999999", "5511888888888"]
}

4. 发送文本

发送一条短信。

参数：

• instanceName （必填）：实例名称
• number （必填）：收件人号码
• text （必填）：消息内容

示例：

{
  "instanceName": "minha_instancia",
  "number": "5511999999999",
  "text": "Olá! Esta é uma mensagem de teste."
}

5. 发送媒体

发送媒体（图片/视频/文档/音频）。

参数：

• instanceName （必填）：实例名称
• number （必填）：收件人号码
• mediatype （必填）：媒体类型（图片、视频、文档、音频）
• media （必填）：媒体URL或Base64编码
• mimetype （必填）：MIME 类型（例如：image/png，video/mp4）
• caption （可选）：媒体字幕
• fileName （可选）：文件名

示例：

{
  "instanceName": "minha_instancia",
  "number": "5511999999999",
  "mediatype": "image",
  "media": "https://exemplo.com/imagem.png",
  "mimetype": "image/png",
  "caption": "Confira esta imagem!",
  "fileName": "imagem.png"
}

6. 获取个人资料

查找联系人的资料信息。

参数：

• instanceName （必填）：实例名称
• number （必填）：联系电话

示例：

{
  "instanceName": "minha_instancia",
  "number": "5511999999999"
}

7. 连接状态

检查实例的连接状态。

参数：

• instanceName （必填）：实例名称

示例：

{
  "instanceName": "minha_instancia"
}

8. 登出实例

登出/断开一个WhatsApp实例。

参数：

• instanceName (必填): 要断开的实例名称

示例：

{
  "instanceName": "minha_instancia"
}

🛠️ 要求

• Python 3.11.11
• Docker 和 Docker Compose
• 运行中的Evolution API
• Claude Desktop（用于使用MCP服务器）

📦 安装

使用 Docker Compose（推荐）

1. 克隆仓库：

git clone 
cd evolution_mcp

1. 复制环境变量示例文件：

copy .env.example .env

1. 编辑文件 .env 并设置您的凭据：

EVOLUTION_API_KEY=sua_api_key_aqui
EVOLUTION_BASE_URL=http://evolution-api:8080
LOG_LEVEL=INFO

1. 构建并启动容器：

docker-compose up -d --build

1. 通过编辑文件来配置Claude Desktop：

%APPDATA%\Claude\claude_desktop_config.json

添加：

{
  "mcpServers": {
    "evolution-api": {
      "command": "docker",
      "args": ["exec", "-i", "evolution-mcp", "python", "-m", "mcp_server"]
    }
  }
}

1. 重启 Claude 桌面版

使用 Conda 进行本地开发

1. 创建 Conda 环境：

conda create -n evolution_mcp python=3.11.11
conda activate evolution_mcp

1. 安装依赖项：

pip install -r requirements.txt

1. 配置环境变量：

set EVOLUTION_API_KEY=sua_api_key_aqui
set EVOLUTION_BASE_URL=http://localhost:8080
set LOG_LEVEL=DEBUG

1. 运行服务器：

python -m mcp_server

🔧 设置

环境变量

门

• 五千零二十MCP服务器端口

🐳 Docker（注：这里的“🐳”是一个表情符号，通常表示鲸鱼，但在此上下文中可能只是作为品牌或项目的标识，不直接翻译）

Dockerfile

该项目包含一个针对Python 3.11.11优化的Dockerfile。

Docker Compose

O docker-compose.yml 配置为：

• 孤立网络（evolution-network）
• 实时开发卷（./src:/app/src）
• 自动重启（restart: unless-stopped）
• 可配置的环境变量

📝 项目结构

evolution_mcp/
├── mcp_server.py          # Servidor MCP principal
├── Dockerfile             # Imagem Docker
├── docker-compose.yml     # Orquestração Docker
├── requirements.txt       # Dependências Python
├── .env.example          # Exemplo de variáveis de ambiente
├── SECURITY.md           # Guia de segurança
└── README.md             # Esta documentação

🔍 日志与调试

要启用详细日志：

set LOG_LEVEL=DEBUG

或者不 .env：

LOG_LEVEL=DEBUG

🤝 与Evolution API的集成

服务器通过HTTP请求与Evolution API进行通信，自动包含头部信息。 apikey 在所有请求中。

Evolution API中使用的终端点

• POST /instance/create - 创建实例
• DELETE /instance/delete/{instanceName} - 删除实例
• POST /chat/whatsappNumbers/{instanceName} - 核对数字
• POST /message/sendText/{instanceName} - 发送文本
• POST /message/sendMedia/{instanceName} - 发送媒体
• GET /chat/fetchProfile/{instanceName} - 搜索资料

🔌 与Claude桌面版的集成

MCP服务器旨在通过Docker与Claude Desktop一起使用：

1. 该容器以守护进程模式运行（不会自动启动服务器）
2. O Claude Desktop 通过（某种方式）连接 docker exec -i 何时需要使用这些工具
3. 通信是通过STDIO（标准输入/标准输出）进行的。

Claude桌面版的配置

Edite（人名，音译）： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "evolution-api": {
      "command": "docker",
      "args": ["exec", "-i", "evolution-mcp", "python", "-m", "mcp_server"]
    }
  }
}

重要的在使用 Claude Desktop 的工具之前，容器需要先运行起来。

🚨 错误处理

服务器处理以下类型的错误：

• HTTP错误返回Evolution API的状态码和消息
• 验证错误在发送前验证参数
• 连接错误每请求超时30秒
• 未知错误详细的日志用于调试

📄 许可证

此项目按现状提供，不作任何保证。

🆘 支持

针对以下问题：

• 进化API请查阅Evolution API的官方文档。
• MCP（Multi-Carrier Processing，多载波处理）请查阅模型上下文协议的文档。
• 这个服务器在仓库中创建一个议题（或问题）

🔄 更新

要更新服务器：

docker-compose down
docker-compose pull
docker-compose up -d

🐛 故障排除

重启循环中的容器

如果容器持续重启：

# Pare o container
docker-compose down

# Reconstrua com as mudanças
docker-compose up -d --build

# Verifique que o container está rodando
docker ps | findstr evolution-mcp

Claude Desktop 找不到工具

1. 检查容器是否正在运行： docker ps
2. 手动测试连接：

docker exec -i evolution-mcp python -m mcp_server

1. 完全重启 Claude Desktop
2. 在以下位置检查 Claude Desktop 的日志：

%APPDATA%\Claude\logs\mcp-server-evolution-api.log

API密钥错误

如果遇到身份验证错误：

1. 检查文件 .env
2. 重建容器：

docker-compose down
docker-compose up -d

手动测试工具

测试服务器是否运行：

docker exec -it evolution-mcp python -c "from mcp_server import evolution_client; print(evolution_client.base_url)"

🔒 安全

保护等级

MCP服务器具有多层安全防护：

1. STDIO（非HTTP）服务器使用stdin/stdout，不公开HTTP端口
2. Docker 隔离需要访问Docker以运行 docker exec
3. 进化API密钥所有通信都需要有效的密钥
4. 代币MCP （可选）：对MCP服务器进行额外身份验证
5. 审计日志记录记录所有操作

推荐的安全设置

对于生产环境（VPS）：

# 1. Gerar token de segurança
python -c "import secrets; print(secrets.token_urlsafe(32))"

# 2. Adicionar ao .env
echo "MCP_SERVER_TOKEN=seu_token_aqui" >> .env

# 3. Habilitar logs de auditoria
echo "ENABLE_AUDIT_LOG=true" >> .env

重要的在VPS（虚拟专用服务器）上，还需进行以下配置：

• 防火墙（UFW/iptables）
• 使用密钥的SSH（无密码）
• 对 Docker 守护进程的有限访问

📖 代表书本的符号，可直接译为“书本”或根据上下文译为“书籍”。 完整指南看看 SECURITY.md 以获取完整详情

⚠️ 重要提示

1. 确保 Evolution API 在配置的 URL 上可访问
2. 使用国际格式的数字，不要加“+”（例如：5511999999999）
3. 为了开发，使用挂载的卷进行热重载
4. Em（在音乐中通常指E音，但在此上下文中可能仅为一个音节或特定表达，无直接对应中文意义，若作为音节可保留原样或根据具体语境翻译） 生产（VPS），配置 MCP_SERVER_TOKEN 电子防火墙
5. 保管好你的钥匙，不要在Git中提交
6. 集装箱需要处于 运行中 为了连接到 Claude Desktop
7. 编辑后 claude_desktop_config.json始终重启 Claude Desktop
8. 定期监控审计日志： docker-compose logs -f | findstr AUDIT