使用说明

EvoAPI MCP

该项目通过FastMCP（模型上下文协议）实现了先进的通信接口，允许自动发送WhatsApp消息，媒体管理和群组对话语义分析。

📋 索引

功能
要求
安装
配置
使用
API 参考
解决问题
贡献
许可证

🚀 功能

📱 WhatsApp 通讯

✅ 向群组和个人联系人发送消息
✅ 完整的媒体支持（图像，视频，音频，文档，PDF）
✅ 自动压缩视频和音频
✅ 组列表和管理

🤖 智能分析

✅ 自动对话编目
✅ 在信件中搜索语义
✅ 沟通模式分析
✅ 提取群组见解

🔧 MCP 集成

✅ 兼容com克劳德桌面e Web
✅ 通过协议stdio接口
✅ 自动暴露的工具

📋 要求

操作系统

Windows 10/11、macOS 10.15+、ou Linux Ubuntu 18.04+

必要的软件

python：3.8优
转码：用于媒体处理
Node.js16+（适用于某些集成）

Python 依赖关系

requests>=2.28.0
mcp>=0.5.0
fastapi>=0.100.0
uvicorn>=0.23.0
python-dotenv>=1.0.0

🛠 安装

1. 克隆仓库

git clone https://github.com/sandovalmedeiros/mcp_evoapi.git
cd mcp_evoapi

2. Python 环境配置

# Criar ambiente virtual
python -m venv venv

# Ativar ambiente virtual
# Windows
venv\Scripts\activate
# macOS/Linux
source venv/bin/activate

# Instalar dependências
pip install -r requirements.txt

3. 安装 FFmpeg

视窗

# Via Chocolatey
choco install ffmpeg

# Via Winget
winget install FFmpeg

macOS

# Via Homebrew
brew install ffmpeg

Linux（Ubuntu/Debian）

sudo apt update
sudo apt install ffmpeg

4. 安装检查

# Verificar Python
python --version

# Verificar FFmpeg
ffmpeg -version

# Verificar dependências
pip list

⚙️ 配置

1. 环境变量

复制示例文件并设置您的凭据：

cp .env.example .env

编辑文件 .env:

# Configurações da EVO API
EVO_API_URL=http://localhost:3000
EVO_API_TOKEN=seu_token_aqui
EVO_INSTANCE_NAME=sua_instancia

# Configurações do Serviço de Análise
SEMANTIC_API_URL=http://localhost:8000
SEMANTIC_API_TOKEN=seu_token_semantico

# Configurações de Upload
MAX_FILE_SIZE=160MB
TEMP_DIR=./temp

# Configurações de Compressão
DEFAULT_VIDEO_CRF=28
DEFAULT_VIDEO_RESOLUTION=720p
DEFAULT_AUDIO_BITRATE=128k

# Configurações de Debug
DEBUG=false
LOG_LEVEL=INFO

2. Claude 桌面设置

创建或编辑 Claude Desktop 配置文件：

视窗

本地化： %APPDATA%\Claude\claude_desktop_config.json

macOS

本地化： ~/Library/Application Support/Claude/claude_desktop_config.json

Linux

本地化： ~/.config/claude/claude_desktop_config.json

文件内容 claude_desktop_config.json:

{
  "mcpServers": {
    "evoapi_mcp": {
      "command": "python",
      "args": [
        "/caminho/completo/para/mcp_evoapi/evoapi_mcp.py"
      ],
      "env": {
        "PYTHONPATH": "/caminho/completo/para/mcp_evoapi",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  },
  "toolGroups": {
    "whatsapp": {
      "tools": [
        "send_message_to_group",
        "send_message_to_phone",
        "get_groups",
        "get_group_messages"
      ]
    },
    "media": {
      "tools": [
        "send_image",
        "send_video",
        "send_audio",
        "send_document",
        "send_pdf"
      ]
    },
    "analysis": {
      "tools": [
        "catalogar_qas",
        "buscar_qas"
      ]
    }
  }
}

3. Claude Web 设置

对于 Claude Web，配置 MCP 桥梁：

# Instalar bridge MCP
npm install -g @anthropic/mcp-bridge

# Executar bridge
mcp-bridge --config claude_desktop_config.json --port 3001

然后，在 Claude Web 中，添加该工具：

网址： http://localhost:3001
Tipo:MCP桥
设置：从 JSON 文件导入

4. EVO API 设置

确保设置了 EVO API：

# Verificar status da API
curl -X GET "http://localhost:3000/instance/status" \
  -H "Authorization: Bearer seu_token_aqui"

# Testar conexão WhatsApp
curl -X GET "http://localhost:3000/instance/connect" \
  -H "Authorization: Bearer seu_token_aqui"

🚀 使用

直接执行

git clone https://github.com/sandovalmedeiros/mcp_evoapi.git
cd mcp_evoapi
python evoapi_mcp.py

Claude 的实例

向组发送消息

Envie a mensagem "Olá pessoal!" para o grupo "Família"

发送带字幕的图像

Envie a imagem "foto.jpg" para o contato +5511999999999 com a legenda "Confira esta foto!"

搜索群组消息

Busque as mensagens do grupo "Trabalho" entre 01/01/2024 e 31/01/2024

语义分析

Catalogue as perguntas e respostas do grupo "Suporte" do último mês e depois busque por "problema de login"

📚 API 参考

消息

`send_message_to_group(group_id: str, message: str)`

向组发送文本消息。

参数：

group_id：我会做WhatsApp的
message消息文本

`send_message_to_phone(cellphone: str, message: str)`

向联系人发送文本消息。

参数：

cellphone：数字没有格式+55xxxxxxxxxxx
message消息文本

媒体

`send_image(recipient: str, image_path: str, caption: str = "")`

发送带有可选字幕的图像。

`send_video(recipient: str, video_path: str, caption: str = "", crf: int = 28, resolution: str = None, bitrate: str = None)`

以自动压缩方式发送视频。

压缩参数：

crf恒定速率因子（18-51，较低=质量更好）
resolution分辨率（720p、1080p等）
bitrate：分类位数（1M、2M等）

`send_audio(recipient: str, audio_path: str, caption: str = "")`

使用自动压缩发送音频。

`send_document(recipient: str, document_path: str, caption: str = "")`

发送通用文件。

`send_pdf(recipient: str, pdf_path: str, caption: str = "")`

发送PDF文件。

团体

`get_groups()`

列出所有可用组。

返回：

[
  {
    "id": "grupo_id",
    "name": "Nome do Grupo",
    "participants": 25
  }
]

`get_group_messages(group_id: str, start_date: str, end_date: str)`

从特定时间段的组中检索邮件。

参数：

start_date开始日期（YYY-MM-DD）
end_date电影日期（YYY-MM-DD）

语义分析

`catalogar_qas(group_id: str, start_date: str, end_date: str)`

发送消息进行分析和编目。

`buscar_qas(consulta: str, top_k: int = 3)`

对已编目信件进行语义搜索。

🔧 解决问题

常见问题

1. 错误 “找不到 FFmpeg”

# Verificar instalação
which ffmpeg  # macOS/Linux
where ffmpeg  # Windows

# Adicionar ao PATH se necessário
export PATH=$PATH:/usr/local/bin  # macOS/Linux

2. 许可错误

# Dar permissão de execução
chmod +x evoapi_mcp.py

# Verificar proprietário
ls -la evoapi_mcp.py

3. 依赖关系错误

# Reinstalar dependências
pip install --force-reinstall -r requirements.txt

# Verificar versões
pip show mcp requests fastapi

4. 连接问题

# Testar conectividade
curl -X GET http://localhost:3000/health
curl -X GET http://localhost:8000/health

# Verificar portas em uso
netstat -tulpn | grep :3000
netstat -tulpn | grep :8000

日志和调试

要启用详细日志：

# Definir nível de log
export LOG_LEVEL=DEBUG

# Executar com verbose
python evoapi_mcp.py --verbose

# Verificar logs
tail -f logs/evoapi_mcp.log

配置文件

检查 Claude 桌面配置

# Validar JSON
python -m json.tool claude_desktop_config.json

# Verificar sintaxe
cat claude_desktop_config.json | jq .

检查环境变量

# Listar variáveis
printenv | grep EVO
printenv | grep SEMANTIC

# Testar carregamento
python -c "from dotenv import load_dotenv; load_dotenv(); import os; print(os.getenv('EVO_API_URL'))"

🤝 贡献

如何贡献

分叉仓库
克隆您的本地副本
创建一个分支用于您的功能（git checkout -b feature/AmazingFeature)
提交变化（git commit -m 'Add some AmazingFeature')
推 a分支(git push origin feature/AmazingFeature)
打开 um拉取请求

代码模式

使用 PEP 8 Python 格式
添加 文档字符串 对于所有函数
Inclusia 单位测试 新功能
保持 兼容性 com Python 3.8+

Reportar漏洞

使用 GitHub 问题模板，包括：

问题详细描述
要播放的步骤
Ambiente（操作系统、Python版本等）
相关日志

📄 许可证

这个项目是根据麻省理工学院许可证授权的 - 查看文件许可证为了细节。

📞 支持

文档: 项目 Wiki
问题: GitHub问题
讨论: GitHub讨论

🙏 致谢

特别感谢 Sandeco Macedo教授 提供基础课程和宝贵的教学，使这个项目成为可能。

🎓 桑德科·马塞多教授频道: 油管

使用说明

EvoAPI MCP

📋 索引

🚀 功能

📱 WhatsApp 通讯

🤖 智能分析

🔧 MCP 集成

📋 要求

操作系统

必要的软件

Python 依赖关系

🛠 安装

1. 克隆仓库

2. Python 环境配置

3. 安装 FFmpeg

视窗

macOS

Linux（Ubuntu/Debian）

4. 安装检查

⚙️ 配置

1. 环境变量

2. Claude 桌面设置

视窗

macOS

Linux

3. Claude Web 设置

4. EVO API 设置

🚀 使用

直接执行

Claude 的实例

向组发送消息

发送带字幕的图像

搜索群组消息

语义分析

📚 API 参考

消息

send_message_to_group(group_id: str, message: str)

send_message_to_phone(cellphone: str, message: str)

媒体

send_image(recipient: str, image_path: str, caption: str = "")

send_video(recipient: str, video_path: str, caption: str = "", crf: int = 28, resolution: str = None, bitrate: str = None)

send_audio(recipient: str, audio_path: str, caption: str = "")

send_document(recipient: str, document_path: str, caption: str = "")

send_pdf(recipient: str, pdf_path: str, caption: str = "")

团体

get_groups()

get_group_messages(group_id: str, start_date: str, end_date: str)

语义分析

catalogar_qas(group_id: str, start_date: str, end_date: str)

buscar_qas(consulta: str, top_k: int = 3)

🔧 解决问题

常见问题

1. 错误 “找不到 FFmpeg”

2. 许可错误

3. 依赖关系错误

4. 连接问题

日志和调试

配置文件

检查 Claude 桌面配置

检查环境变量

🤝 贡献

如何贡献

代码模式

Reportar漏洞

📄 许可证

📞 支持

🙏 致谢

相关 MCP

语言服务协议MCP

语言服务器工具

媒体管理协议服务器

代码库语义搜索工具

任务编排服务器

Plex AI管理助手

`send_message_to_group(group_id: str, message: str)`

`send_message_to_phone(cellphone: str, message: str)`

`send_image(recipient: str, image_path: str, caption: str = "")`

`send_video(recipient: str, video_path: str, caption: str = "", crf: int = 28, resolution: str = None, bitrate: str = None)`

`send_audio(recipient: str, audio_path: str, caption: str = "")`

`send_document(recipient: str, document_path: str, caption: str = "")`

`send_pdf(recipient: str, pdf_path: str, caption: str = "")`

`get_groups()`

`get_group_messages(group_id: str, start_date: str, end_date: str)`

`catalogar_qas(group_id: str, start_date: str, end_date: str)`

`buscar_qas(consulta: str, top_k: int = 3)`