项目简介

evo-mcp 项目是一个基于 Model Context Protocol (MCP) 的网关服务器，它将 Evolution API 的功能通过 MCP 协议对外暴露。Evolution API 专注于提供 WhatsApp 相关的各种功能接口，而 evo-mcp 则作为 Evolution API 的 MCP 适配层，使得 LLM 应用可以通过标准的 MCP 协议调用 Evolution API 提供的 WhatsApp 功能，例如发送消息、管理 WhatsApp 实例、进行群组操作等。

主要功能点

MCP 服务器实现: 实现了标准的 MCP 服务器协议，可以接收和处理 MCP 客户端的请求。
Evolution API 网关: 作为 Evolution API 的客户端，将 MCP 请求转换为对 Evolution API 的调用。
WhatsApp 功能集成: 集成了 Evolution API 提供的丰富的 WhatsApp 功能，包括：
- 实例管理: 创建、连接、重启、删除和管理 WhatsApp 实例。
- 消息发送: 支持发送文本、媒体、贴纸、位置、联系人、投票、列表、按钮等多种类型的 WhatsApp 消息。
- 聊天管理: 支持检查 WhatsApp 号码、标记消息已读、存档/取消存档聊天、删除消息、获取用户/群组头像等。
- 群组管理: 支持创建群组、获取群组列表、管理群组成员、更新群组信息、获取/撤销邀请链接、修改群组设置等。
- 设置管理: 支持设置和获取 WhatsApp 实例的各种设置。
Stdio 和 SSE 传输协议: 支持 Stdio 和 Server-Sent Events (SSE) 两种传输协议，方便不同的客户端连接方式。
工具 (Tools) 注册: 注册了大量与 WhatsApp 功能相关的工具 (Tools)，例如 'send_text', 'create_group', 'fetch_profile_picture_url' 等，方便 LLM 客户端调用。
环境配置: 通过环境变量配置 Evolution API 的连接信息和 API 密钥。
Docker 支持: 提供 Dockerfile，方便用户快速部署和运行 MCP 服务器。

安装步骤

克隆仓库:

git clone https://github.com/brunonuzzi/evo-mcp.git
cd evo-mcp

构建 Docker 镜像 (可选，推荐使用 Docker 部署):

docker build --pull --rm -f 'Dockerfile' -t 'mcp-evo-gateway:latest' '.'

运行 Docker 容器 (可选，推荐使用 Docker 部署):

docker run -it --rm -p 8000:8000 mcp-evo-gateway:latest

或者，不使用 Docker 运行 (需要 Node.js 环境):

安装依赖:
```
npm install
```
运行服务器:
```
node index.js
```

服务器配置

MCP 客户端需要配置以下信息以连接到 evo-mcp 服务器。以下配置信息为 JSON 格式，请复制到 MCP 客户端的服务器配置中。

{
  "serverName": "evo-mcp-server",
  "command": "docker",
  "args": [
    "run",
    "-it",
    "--rm",
    "-p",
    "8000:8000",
    // 以下为环境变量配置，请根据实际情况替换
    "-e", "EVOLUTION_APIKEY=<你的Evolution API密钥>",
    "-e", "EVOLUTION_INSTANCE=<你的Evolution实例ID>",
    "-e", "EVOLUTION_API_BASE=<你的Evolution API Base URL，例如：localhost:8080 或 你的域名>",
    "mcp-evo-gateway:latest"
  ]
}

参数注释:

'serverName': MCP 服务器的名称，可以自定义。
'command': 启动 MCP 服务器的命令，这里使用 'docker' 命令。如果直接运行 'node index.js'，则 'command' 应为 'node'，'args' 应为 '["index.js"]'。
'args': 启动命令的参数列表。
- 'run -it --rm -p 8000:8000': Docker 运行容器的通用参数，将容器的 8000 端口映射到宿主机的 8000 端口。
- '-e EVOLUTION_APIKEY=<你的Evolution API密钥>': 设置 Evolution API 密钥环境变量，请替换 '<你的Evolution API密钥>' 为你实际的 API 密钥。
- '-e EVOLUTION_INSTANCE=<你的Evolution实例ID>': 设置 Evolution 实例 ID 环境变量，请替换 '<你的Evolution实例ID>' 为你实际的实例 ID。
- '-e EVOLUTION_API_BASE=<你的Evolution API Base URL，例如：localhost:8080 或你的域名>': 设置 Evolution API Base URL 环境变量，请替换 '<你的Evolution API Base URL>' 为你实际的 API Base URL。 例如，如果 Evolution API 运行在本地 8080 端口，则设置为 'localhost:8080'。如果 Evolution API 部署在云端，则设置为你的域名。
- '"mcp-evo-gateway:latest"': Docker 镜像名称，与构建镜像时指定的名称一致。

注意: 如果选择不使用 Docker 运行，'command' 和 'args' 配置应修改为：

{
  "serverName": "evo-mcp-server",
  "command": "node",
  "args": [
    "index.js"
  ]
}

并确保在运行 'node index.js' 前，已在终端中设置环境变量 'EVOLUTION_APIKEY', 'EVOLUTION_INSTANCE', 'EVOLUTION_API_BASE'。例如：

export EVOLUTION_APIKEY=<你的Evolution API密钥>
export EVOLUTION_INSTANCE=<你的Evolution实例ID>
export EVOLUTION_API_BASE=<你的Evolution API Base URL>
node index.js

基本使用方法

启动 MCP 服务器: 根据上述安装步骤和服务器配置启动 evo-mcp 服务器。
使用 MCP 客户端连接: 使用任何支持 MCP 协议的客户端（例如 '@modelcontextprotocol/inspector'）连接到 evo-mcp 服务器的 SSE 或 Stdio 端点。
- SSE 端点: 默认情况下，可以通过 'http://localhost:8000/sse' 访问 SSE 端点。
- Stdio 端点: 如果客户端支持 Stdio 连接，可以直接连接到服务器的 Stdio 输入输出流。
调用工具 (Tools): 在 MCP 客户端中，可以列出 evo-mcp 服务器提供的工具 (Tools)，并调用这些工具来执行 WhatsApp 相关的功能。例如，可以调用 'send_text' 工具发送文本消息，或调用 'create_group' 工具创建 WhatsApp 群组。工具的具体参数和使用方法请参考 'index.js' 文件中的 'TOOL_DEFINITIONS' 和 'toolHandlers' 部分。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息