项目简介

该项目是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在将 Evolution API 的功能暴露给大型语言模型 (LLM) 客户端，例如 Claude Desktop。通过这个服务器，LLM 可以调用 Evolution API 提供的各种接口，实现对 WhatsApp 的自动化操作，包括消息发送、联系人和群组管理、Webhook 配置等。它充当了 LLM 与 WhatsApp 之间的一个智能连接器。

主要功能点

本 MCP 服务器通过注册一系列工具，为 LLM 提供了以下关键能力：

实例管理: 获取 Evolution API 服务器信息，创建、获取、连接、重启、注销和删除 WhatsApp 实例。
连接状态: 检查 WhatsApp 实例的连接状态（在线/离线）。
消息发送: 发送文本、图片、视频、音频（语音消息）、文件、贴纸、位置、联系人、投票、列表和按钮消息。
交互与状态: 发送消息 واکنش (reaction)，设置在线状态。
群组操作: 查找群组信息，获取群组成员列表。
聊天与联系人: 查找聊天列表，查找联系人信息。
配置管理: 获取和设置实例的 Webhook 配置和行为设置（如自动拒接电话、忽略群组等）。

安装步骤

克隆仓库:

git clone https://github.com/aiteks-ltda/mcp-evo-api.git
cd mcp-evo-api

安装依赖: 项目使用 Bun 包管理器。确保您已安装 Bun。
```
bun install
```

配置 Evolution API 凭据: 创建一个名为 '.env' 的文件，并在其中填入您的 Evolution API 服务器 URL 和 API Key。

EVOLUTION_API_URL=https://your-evolution-api-server.com
EVOLUTION_API_KEY=your-api-key-here

请将 'https://your-evolution-api-server.com' 和 'your-api-key-here' 替换为您实际的 Evolution API 地址和密钥。

构建项目 (用于生产环境或本地运行):
```
bun run build
```
这将在 'dist' 目录生成可执行的 JavaScript 文件 ('dist/main.js')。

运行服务器:

本地开发模式:
```
bun run dev
```

本地生产模式 (推荐):

bun run dist/main.js

使用 Docker Compose: 确保 Docker 已安装，并在项目根目录运行：
```
docker-compose up -d
```

使用 Docker:

docker build -t mcp-evo-api .
docker run -d -p 3000:3000 -e EVOLUTION_API_URL=yoururl -e EVOLUTION_API_KEY=yourkey --name mcp-evo-api mcp-evo-api

将 'yoururl' 和 'yourkey' 替换为您的 Evolution API 凭据。

服务器配置 (用于 MCP 客户端)

MCP 客户端（如 Claude Desktop）需要知道如何启动和连接到此服务器。您需要在客户端的配置文件中添加此 MCP 服务器的信息。配置信息通常是一个 JSON 格式的对象数组。

如果服务器运行在本地（使用 'bun run dist/main.js'），您可以在客户端配置文件中添加如下条目：

{
  "mcpServers": {
    "evo-api": {
      // 客户端用于启动服务器进程的命令
      "command": "bun", // 或者 "node", 具体取决于您的环境
      // 启动命令的参数，指向服务器的入口文件
      "args": [
        "/path/to/your/mcp-evo-api/dist/main.js" // 替换为您的项目实际路径
      ]
      // 服务器名称 (可选，如果未指定，默认为键名 "evo-api")
      // "name": "Evolution API MCP Server", 
      // 服务器版本 (可选)
      // "version": "0.1.0" 
    }
  }
}

请将 '/path/to/your/mcp-evo-api/dist/main.js' 替换为您实际构建后 'main.js' 文件的路径。

如果服务器运行在 Docker 或远程 并通过 HTTP/WebSocket 公开，您可以在客户端配置文件中添加如下条目（Docker Compose 示例）：

{
  "mcpServers": {
    "evo-api": {
      // 服务器的 URL (如果是 HTTP/WebSocket 传输)
      "url": "http://localhost:3000" // 替换为您的服务器实际地址和端口
      // 服务器名称 (可选)
      // "name": "Evolution API MCP Server", 
      // 服务器版本 (可选)
      // "version": "0.1.0"
    }
  }
}

请将 'http://localhost:3000' 替换为您 Docker 容器或远程服务器的实际可访问 URL 和端口。

基本使用方法

配置完成后，重新启动您的 MCP 客户端。客户端将检测并连接到此 MCP 服务器。连接成功后，LLM 将能够识别并调用此服务器暴露的各种 WhatsApp 自动化工具。您可以直接在与 LLM 的对话中指示它执行 WhatsApp 相关的任务，例如：“使用我的 WhatsApp 实例 [实例名称] 向 [手机号] 发送一条消息说：你好！” LLM 会根据您的指令和它识别到的工具参数，调用相应的 MCP 工具来执行操作。

关键词

信息