evolution-api-mcp

Name: evolution-api-mcp
Author: singleflo

远程服务

github.com/singleflo通信协作03 周前更新

代码仓库

关于 evolution-api-mcp

用于操作单个 Evolution API v2 实例及其 WhatsApp 号码的 MCP 服务。它将消息、聊天、群组、联系人、设置和集成操作分为可配置工具集，并提供只读及不可逆操作控制。

主要功能

01发送文字和媒体消息
02读取并导出聊天记录
03管理群组和联系人
04配置实例与集成
05控制工具集和写入策略

适用场景

01查看聊天记录和送达状态
02通过 WhatsApp 发送消息或媒体
03管理群组成员和设置
04调整实例 Webhook 与聊天机器人

MCP 相关

将 Evolution API 实例操作作为 MCP 工具提供，分为 13 个可选工具集。支持本地 stdio 和托管 HTTP 接入。

配置

远程服务无需本地安装。选择你使用的客户端，复制配置或使用一键安装。

服务地址https://evolution-mcp.singleflo.com/mcp

一键复制安装命令

Claude CodeTerminalclaude mcp add --transport http singleflo-evolution-api https://evolution-mcp.singleflo.com/mcp

Cursor.cursor/mcp.json{"mcpServers":{"singleflo-evolution-api":{"type":"http","url":"https://evolution-mcp.singleflo.com/mcp"}}}在 Cursor 中打开

VS Code.vscode/mcp.json{"servers":{"singleflo-evolution-api":{"type":"http","url":"https://evolution-mcp.singleflo.com/mcp"}}}在 VS Code 中打开

Claude Desktopclaude_desktop_config.json{"mcpServers":{"singleflo-evolution-api":{"type":"http","url":"https://evolution-mcp.singleflo.com/mcp"}}}

Windsurf~/.codeium/windsurf/mcp_config.json{"mcpServers":{"singleflo-evolution-api":{"serverUrl":"https://evolution-mcp.singleflo.com/mcp"}}}

命令在终端中运行；JSON 粘贴到对应客户端的 MCP 配置后重启。需要授权的服务会在首次连接时提示登录。

安装包

pypievolution-api-mcp1.0.0stdio

工具

详细介绍

Evolution API Assistant

一个用于操作单个 Evolution API v2 实例的 MCP 服务，该实例对应一个 WhatsApp 号码：它可以读取聊天和消息历史记录、发送消息和媒体、管理群组、联系人、标签、模板和个人资料，还可以配置实例、Webhook 和聊天机器人。提供 100 个工具，每个操作对应一个工具，分为 13 个工具集，可按需启用。它只与您指定的 Evolution 服务通信，并使用该实例自己的令牌。

Evolution API Assistant 是 Persevida SL 的独立项目，与 Meta、WhatsApp 或 Evolution API 项目均无关联，也未获得其认可。

两种使用方式

本地（stdio） — uvx evolution-api-mcp 在您的机器上运行，并与您能够访问的任何 Evolution API 2.x 服务通信。它支持 Evolution 的全部三种集成方式（WHATSAPP-BAILEYS、WHATSAPP-BUSINESS、EVOLUTION），并可发送您磁盘上的文件。
托管 — https://evolution-mcp.singleflo.com/mcp 通过互联网提供服务，供 Claude.ai、ChatGPT 和 Codex 使用：无需安装，只需使用 Evolution URL 和实例令牌登录一次。公共托管服务接受集成为 WHATSAPP-BUSINESS（官方 WhatsApp Business Platform）或 WHATSAPP-BAILEYS（WhatsApp Web 会话）的实例，并且不会提供涉及机密或无法撤销的工具。请参阅下文的“托管服务”。

快速入门

通过 AI Agent 安装。 如果您已有 AI 编码助手（Claude Code、Claude Desktop、Cursor、opencode 或下方列出的任何托管服务），请将此链接粘贴到您的 Agent 中，并让它为您设置 Evolution API Assistant： https://raw.githubusercontent.com/singleflo/evolution-api-mcp/main/docs/INSTALL-WITH-YOUR-AGENT.md 此页面是为 Agent 编写的，而非面向您：它会向您询问 Evolution URL 和实例令牌，安装 uv，写入其自身宿主读取的配置文件，并验证连接。手动安装方式见下文。

1. 安装

直接运行服务：

uvx evolution-api-mcp

或将其安装到您的环境中：

uv pip install evolution-api-mcp

仍可从源代码安装以进行开发：

uv pip install git+https://github.com/singleflo/evolution-api-mcp

服务需要 Python 3.10 或更高版本。uvx 会自行获取合适的解释器。

2. 配置环境变量

正常运行只需配置两个变量：

EVOLUTION_API_URL：Evolution 服务的基础 URL，例如 https://evolution.example.com。末尾的斜杠会被忽略。
EVOLUTION_INSTANCE_TOKEN：一个实例的令牌。在 Evolution Manager 中打开实例并复制其令牌，或使用创建实例时返回的令牌。本地服务和托管服务都会拒绝服务器的全局 AUTHENTICATION_API_KEY，因为它可以控制该 Evolution 服务器上的所有实例。

实例名称及其集成会根据令牌自动识别，无需手动输入。缺少变量时，系统会在调用工具时报告，而不是在启动时报告，因此你可以在修复配置的同时让服务正常启动并列出其工具。Evolution 仅在 DATABASE_SAVE_DATA_INSTANCE=true（默认值）时解析实例令牌；设为 false 时，Evolution 会返回 401，服务也会说明这一点。

其他变量均为可选项。所有变量的空白值都视为未设置。若服务无法接受某个值，会在启动时以退出代码 2 停止，并在 stderr 上显示一条指出变量名称及其可接受值的消息。

变量	默认值	含义
`EVOLUTION_MCP_TOOLSETS`	`core`	要启用的工具集或预设（`core`、`all`），以逗号分隔。`--toolsets` 选项优先于此变量。
`EVOLUTION_MCP_ALLOW`	`*`	`*` 允许使用所有未被拒绝列表拒绝的工具；`none` 会使服务变为只读；否则，填写会更改数据的工具列表，以逗号分隔。
`EVOLUTION_MCP_DENY`	默认拒绝列表	要拒绝的工具列表，以逗号分隔。未设置时，包含“Agent 可以执行的操作”中列出的 6 个工具；如果设置了此变量，你提供的值会完全替换该列表。
`EVOLUTION_MCP_ALLOW_IRREVERSIBLE`	off	`yes`、`true` 或 `1`（不区分大小写）允许运行无法撤销的工具。`no`、`false` 和 `0` 会将其禁用。
`EVOLUTION_MCP_DEFAULT_DELAY_MS`	`1200`	发送消息前，接收方看到的“正在输入……”时长，单位为毫秒；取值范围为 `0` 到 `20000`。工具的 `delay_ms` 参数会覆盖此值。
`EVOLUTION_MCP_MAX_WRITES_PER_MINUTE`	`30`	此服务每分钟允许的更改次数；`0` 表示关闭限制。
`EVOLUTION_MCP_FILE_ROOTS`	存在的 `Desktop`、`Documents`、`Downloads`、`Pictures`、`Movies` 和 `Music` 文件夹，以及下载文件夹	`send_local_files` 可读取的文件夹，分隔方式与 `PATH` 相同（macOS 和 Linux 使用 `:`，Windows 使用 `;`）。每个路径都必须是指向现有目录的绝对路径。
`EVOLUTION_MCP_DOWNLOAD_DIR`	`~/Downloads/evolution-api-mcp`	`download_message_media` 保存文件及 `export_chat` 保存其 `exports/` 文件夹的位置。必须是绝对路径。
`EVOLUTION_MCP_TIMEZONE`	计算机的时区（先读取 `TZ`，再读取 `/etc/localtime`），否则为 `UTC`	IANA 时区（例如 `Europe/Rome`），用于工具显示时间，以及解析未指定时区的时间。`get_instance_status` 会报告此值。
`EVOLUTION_MCP_DATA_DIR`	平台的数据目录	托管服务保存数据的位置。本地服务不会在此处写入数据。

evolution-api-mcp 的命令行选项：

选项	作用
`--toolsets LIST`	与 `EVOLUTION_MCP_TOOLSETS` 相同；优先级高于该变量。
`--read-only`	拒绝所有会更改数据的工具（等同于 `EVOLUTION_MCP_ALLOW=none`）。
`--list-tools`	以 JSON 格式打印所有工具（名称、标题、工具集、类型、集成、是否仅限本地），然后退出。无需凭据。
`--list-toolsets`	以 JSON 格式打印工具集、各自的工具数量、预设和默认值，然后退出。无需凭据。
`--version`	打印版本并退出。

服务运行期间，stdout 只会输出 JSON-RPC 流；诊断信息会输出到 stderr。

工具集

每个工具都属于一个工具集。连接会启用部分工具集，且只能看到其中的工具。默认工具集是 core，包含 messaging、chats 和 contacts；all 会启用全部 13 个工具集。get_instance_status 属于 instance，但始终可用，不受工具集设置影响。

工具集	工具数	涵盖内容
`instance`	5	实例的连接状态、二维码配对、重启、退出登录和在线状态。
`messaging`	16	发送文本、媒体、语音消息、位置、联系人名片、投票、列表和按钮消息；对已发送的消息做出回应、编辑和删除。
`chats`	13	列出聊天，显示各个聊天中的最新消息，读取和搜索消息历史记录，导出包含附件的聊天，查看送达状态、已读／未读和归档状态，以及接收的媒体。
`contacts`	6	按名称或号码查找聊天，在 WhatsApp 上检查号码，查看个人资料和头像，以及屏蔽和取消屏蔽。
`groups`	17	群组详情、参与者、邀请链接、创建、设置和成员资格。
`labels`	3	WhatsApp Business 应用中的聊天标签。
`profile`	7	实例自身的个人资料名称、状态文字、头像和隐私设置。
`status`	1	发布状态更新。
`catalog`	2	WhatsApp Business 应用中的产品目录和合集。
`templates`	5	WhatsApp Business Platform 消息模板：列出、创建、编辑、删除和发送。
`settings`	4	实例行为设置和代理。
`events`	4	Webhook 和事件流（WebSocket、RabbitMQ、NATS、SQS、Kafka、Pusher）配置。
`integrations`	17	Evolution 聊天机器人（Evolution Bot、Typebot、OpenAI、Dify、Flowise、n8n、EvoAI）、其会话，以及 Chatwoot。

本地服务：EVOLUTION_MCP_TOOLSETS=messaging,chats,groups 或 --toolsets messaging,chats,groups；预设和工具集名称可以混用（core,groups）。未知名称会导致服务在启动时停止。托管服务：可在授权页面勾选工具集，重新登录即可更改。

连接能看到哪些内容，不只取决于启用的工具集。tools/list 会准确显示调用时不会被拒绝的工具：工具集已启用、实例集成支持、策略允许、未被拒绝，且对于不可逆操作，已获得授权。具体数量取决于连接：

连接	可见工具数
本地 WhatsApp Web（Baileys）实例，默认工具集和设置	35
本地 Baileys 实例，全部工具集	84
本地 Baileys 实例，全部工具集，`EVOLUTION_MCP_ALLOW_IRREVERSIBLE=yes`	89
本地 Baileys 实例，全部工具集，只读	33
托管 WhatsApp Business Platform 实例，标准策略，全部工具集	41
托管 WhatsApp Business Platform 实例，只读策略，全部工具集	22

完整列表按工具集分别列出，每个工具集各有一张表，包含各工具的类型和集成信息，见 docs/TOOLS.md。该列表由代码生成。

每种集成支持的功能

一个 Evolution 实例使用一种集成，而 Evolution 本身在某些集成上不提供某些操作。 get_instance_status 会报告实例使用的集成；如果在不支持某项操作的集成上调用工具，调用会被拒绝，并显示一条指出所需集成的消息。此表统计了每个工具集在各种集成上提供的工具数量。

工具集	工具数	Baileys	Business	Evolution
`instance`	5	5	1	1
`messaging`	16	16	10	5
`chats`	13	13	10	7
`contacts`	6	6	1	1
`groups`	17	17	0	0
`labels`	3	3	0	0
`profile`	7	7	0	0
`status`	1	1	0	0
`catalog`	2	2	0	0
`templates`	5	0	5	0
`settings`	4	4	4	4
`events`	4	4	4	4
`integrations`	17	17	17	17
全部	100	95	52	39

Baileys 是 WHATSAPP-BAILEYS，即与手机关联的 WhatsApp Web 会话。Business 是 WHATSAPP-BUSINESS，即 WhatsApp Business Platform（Cloud API）：它只能通过电话号码联系用户，没有群组、配对或已读回执，并且只能在用户最后一次发送消息后的 24 小时内发送自由格式消息；超过此期限后，只能通过已批准的模板（send_template_message）联系用户。Evolution 是 EVOLUTION，即 Evolution 渠道。各工具的详细信息请参阅 docs/TOOLS.md 和 evolution://guide 资源。

工具和资源

工具遵循几条规则，让模型能够预测其行为，也便于人员审查：

每项操作对应一个工具。读取和写入是分开的工具，不提供通用的“调用任意端点”工具。
每个工具都会声明其类型：read、write（归档聊天、添加标签、设置在线状态等私有或临时更改）、destructive（向其他人发送内容，或替换、移除内容）或 irreversible（无法通过此服务撤销：logout_instance、delete_message_for_everyone、leave_group、delete_template、delete_chatbot、delete_openai_credential）。MCP 提示（readOnlyHint、destructiveHint）根据类型生成，因此宿主的批准对话框会反映实际风险。每个工具都设置了 openWorldHint，因为它们都会对外部服务执行操作，并通过这些服务与其他人进行对话。
工具返回精简的 JSON，绝不返回原始 Evolution 数据行。绝不返回令牌、密码和密钥；读取配置时只会显示是否已设置密钥。时间戳采用服务器显示时区（EVOLUTION_MCP_TIMEZONE）的 ISO-8601 格式（托管服务上为 UTC）。超过 30,000 个字符的结果会被截断，并附上说明解决方法的提示。
调用失败时会以以下三种方式之一结束：已完成；拒绝或失败，并显示“未进行任何更改。”或“未发送任何内容。”；或者显示 UNCERTAIN，表示 Evolution 未确认某项可能已生效的更改。后一种情况会附上之后读回的状态，并提示在检查状态前不要重复调用。

资源：evolution://guide，一份 Markdown 指南，介绍聊天 ID 的格式、集成矩阵、历史记录的来源、操作节奏和安全模型；以及 evolution://recipes，其中包含常见任务的经过测试的调用序列（查看新消息、查找附件、回复、转发、导出）。

提示词：inbox（按聊天分组查看新消息）、reply（起草回复并等待批准）、find_attachment 和 export。它们的 chat 参数会从工具共用的内存联系人名称目录中补全联系人和群组名称。

聊天可通过以下方式指定：带国家代码的国际电话号码（393331234567 或 +39 333 123 4567）、其他工具返回的 chat_id（个人聊天使用 <digits>@s.whatsapp.net，群组使用 <digits>@g.us，号码被 WhatsApp 隐藏的联系人使用 <id>@lid），或联系人、群组名称。如果多个聊天使用同一名称，系统会拒绝请求并列出它们的 chat_id；发送或更改内容的工具只接受完全匹配的名称。

消息历史记录来自 Evolution 的数据库。只有当 Evolution 服务以 DATABASE_SAVE_DATA_NEW_MESSAGE=true 运行时，数据库才会保存消息（配对时同步的较早历史记录需要 DATABASE_SAVE_DATA_HISTORIC=true）；在 WhatsApp Business Platform 实例上，只有启用了 S3/MinIO 存储时才会保留收到的媒体文件。Evolution 不支持文本搜索，因此 search_messages 会自行扫描最新的 2,000 条消息；要查找更早的消息，请通过聊天或时间范围缩小搜索范围。

Agent 可以执行的操作

每次工具调用到达 Evolution 前都会经过一道关卡，而 tools/list 会隐藏关卡将拒绝的工具。关卡读取由人类管理、存储在宿主配置文件中的设置，模型无法更改这些设置：

工具集。 未启用工具集中的工具会被拒绝。
集成。 实例集成不支持的工具会被拒绝。
只读。 EVOLUTION_MCP_ALLOW=none 或 --read-only 会拒绝所有非 read 工具。
不可逆操作。 只有设置了 EVOLUTION_MCP_ALLOW_IRREVERSIBLE=yes，才会运行这 6 个不可逆工具。任何列表都无法放行它们；对于无人能够撤销的操作，仅凭逗号分隔列表中的名称绝不能放行。
拒绝列表。 EVOLUTION_MCP_DENY 指定要拒绝的工具。未设置时，默认列表为：post_status、remove_group_participants、set_webhook、set_event_channel、set_proxy、set_chatwoot_config——状态更新会发送给所有联系人，移除参与者会终止某人的成员资格，而其余四项会更改 Evolution 发送事件的位置、连接网络的方式，或接收你对话的 Chatwoot 帮助台。你设置的值会替换该列表，因此 EVOLUTION_MCP_DENY=post_status 会重新放行其余五项。
允许列表。 将 EVOLUTION_MCP_ALLOW 设置为逗号分隔列表后，只允许列表中的工具更改数据（以及所有读取工具）。

条目必须与工具名称完全匹配。名称若不是已注册工具，服务器就会在启动时停止，因此拼写错误不会悄无声息地打开关卡。先检查拒绝列表，再检查允许列表，因此同时出现在两个列表中的名称会被拒绝。读取操作不受任一列表限制。

配置	允许的操作
`EVOLUTION_MCP_ALLOW=none`	仅允许读取。此服务器不会发送或更改任何内容。
未设置	默认值。允许读取，以及所有已启用的数据更改工具，但默认拒绝列表中的 6 项和 6 个不可逆工具除外。
`EVOLUTION_MCP_ALLOW_IRREVERSIBLE=yes`	默认设置，以及实例集成支持的不可逆工具。拒绝列表不变。

仅限本地的工具。 8 个工具仅由本地服务器注册，因为它们会接收机密信息或读取你的磁盘：send_local_files、set_proxy、set_webhook、set_event_channel、create_chatbot、update_chatbot、create_openai_credential 和 set_chatwoot_config。托管服务器会注册其余 92 个工具。

发送节奏和速率限制。 每次发送都会经过一个 delay，在此期间收件人会看到“正在输入…”；默认值为 1,200 ms。每个连接每分钟最多进行 30 次更改；托管服务器还将读取限制为每分钟 120 次。一次发送多条消息的调用（send_local_files、forward_message）会将每条消息分别计为一次更改。被拒绝的调用会告知需要等待的秒数。

本地文件。 send_local_files 只会读取 EVOLUTION_MCP_FILE_ROOTS 内的文件；不会读取隐藏文件或隐藏文件夹内的文件。每个文件最多 100 MiB，每次调用最多 10 个文件、总计 300 MiB。

消息是数据。 消息中的文本、名称和说明文字由其他人编写。服务器指令会告诉模型：消息中要求发送、转发或更改内容，不代表这是你的请求。

这是此服务器的权限边界，而非令牌的权限边界。具有 shell 访问权限的 Agent 始终可以直接调用 Evolution，而实例令牌可以执行实例所有者能执行的任何操作。如果某项限制必须对所有客户端生效，就应限制该令牌能够访问的内容：为服务器提供一个仅包含它应该看到的对话的实例令牌。

WhatsApp 规则仍然适用

发送的是真实消息，接收者也是真人，而此服务无法撤回这些消息（只有 WhatsApp Web 实例可以在 WhatsApp 允许的时间范围内为所有人删除消息）。请只联系同意接收你消息的人，尊重退订请求，不要发送未经请求的消息或批量消息：违反 WhatsApp 规则的账号会被封禁，这里的任何设置都无法避免这种情况。在 WhatsApp Business Platform 实例上，WhatsApp Business Messaging Policy 适用，其中包括用户同意要求和 24 小时窗口。

Evolution API 版本

支持并经过测试的版本是 Evolution API 2.3.x。发现过程接受任何 2.x 服务，并拒绝其他版本，同时显示注明版本的消息。服务还需要 Evolution 2.3 及更高版本的 POST /verify-creds 路由，服务会利用它识别并拒绝全局 API 密钥。

托管服务：Claude.ai、ChatGPT 和 Codex

下文各节介绍的都是在你的机器上运行服务。还有另一种方式可以使用相同的工具：这些工具也通过互联网在 https://evolution-mcp.singleflo.com/mcp 上提供，Claude.ai、ChatGPT 和 Codex 可以直接访问。你无需安装任何内容，也无需在本地设置环境变量：只需在服务的同意页面上使用 Evolution 地址和实例令牌登录一次，你现有的聊天工具即可访问你的实例。其他各节中的本地配置仍完全按原样运行；两种方式的区别仅在于服务运行的位置。

同意页面会询问你的 Evolution URL、实例令牌、策略以及要启用的工具集。standard 策略允许 Agent 读取并执行操作（发送消息、管理聊天和配置）；read 策略只允许查看，不能执行其他操作。默认勾选 messaging、chats 和 contacts。你可以稍后重新登录来更改任一选项。

托管服务在连接对象和提供内容方面与本地服务有所不同：

evolution-mcp.singleflo.com 上的公共部署接受集成类型为 WHATSAPP-BUSINESS 或 WHATSAPP-BAILEYS 的实例；EVOLUTION 通道实例需要使用本地服务。未设置 EVOLUTION_REMOTE_ALLOWED_INTEGRATIONS 时，服务只接受 WHATSAPP-BUSINESS，这是代码的默认设置，也是商店列表所采用的设置；请参阅 docs/REMOTE.md。WHATSAPP-BAILEYS 实例是非官方的 WhatsApp Web 客户端：WhatsApp 的条款不涵盖以这种方式自动化个人账号，WhatsApp 也可能限制以这种方式使用的号码。由你自行选择；受支持的途径是 Business Platform。
Evolution 服务必须能通过公共地址从互联网访问；私有地址和回环地址会被拒绝。
永不可撤销的工具和 8 个仅限本地的工具始终不可用，并且默认拒绝列表始终生效。

托管服务存储的内容：你的 Evolution URL、实例名称、集成类型、策略和工具集；静态加密存储的实例令牌；仅以哈希形式保存的 OAuth 令牌；以及工具生成的文件，这些文件仅以链接形式保存在服务上，链接 15 分钟后过期。消息内容只会保存在你主动请求生成的文件中（下载的媒体和聊天导出），并通过 15 分钟后过期的链接提供；联系人姓名仅在内存中保留 10 分钟。详情请参阅 https://evolution-mcp.singleflo.com/privacy；同一域名下还提供 https://evolution-mcp.singleflo.com/terms 和 https://evolution-mcp.singleflo.com/support。

各主机的说明：Claude.ai、ChatGPT、Open WebUI 和 Mistral Le Chat 仅支持连接托管服务，各自的说明见下文。Claude Code 和 Codex 保留本地配置，并各自新增了一条托管服务的一行配置。

如果你希望自行运行托管部分，开发者指南 docs/REMOTE.md 涵盖了完整流程：本地运行、隧道和部署。

主机配置示例

以下每个示例只包含最重要的内容：两个变量。工具集默认使用 core，而访问控制会保留默认设置，除非你添加 EVOLUTION_MCP_TOOLSETS、EVOLUTION_MCP_ALLOW 或上表中的其他变量；最后一节展示了只读配置。注意引号：环境变量值是字符串。

可能被主机的工具超时限制中断的，是那些需要等待 WhatsApp 的调用：发送操作会等待其 delay（默认为 1,200 毫秒），send_chat_presence 会让调用等待最多 20 秒，download_message_media、view_message_image 和 export_chat 的每个附件都会给 Evolution 最多 300 秒，而大型上传时，send_local_files 每个文件最多可等待 600 秒。如果主机允许设置超时，示例中会相应调高；JSON 文件不支持注释，因此在此处说明。

以下每段代码都已对照对应主机的文档进行检查，文档链接列在其下方的 Source: 行中。对于支持一行命令添加配置的主机，也会提供该命令，因为它写入的条目与手动编辑文件相同。

Claude Desktop

Claude Desktop 仅提供 macOS 和 Windows 版本，并将服务配置保存在 claude_desktop_config.json 中。可通过 设置 → 开发者 → 编辑配置 找到该文件，也可以在其所在位置直接编辑：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

完全退出 Claude Desktop 并重新打开：它会在启动时读取该文件，不会重新加载。macOS 上的服务日志保存在 ~/Library/Logs/Claude/，Windows 上则保存在 %APPDATA%\Claude\logs；每个服务对应一个文件，stdio 服务会将其输出的所有内容写入其中的 stderr。

来源：https://modelcontextprotocol.io/docs/develop/connect-local-servers

Claude Code

只需一行即可添加服务。-- 用于分隔 Claude Code 自身的选项和启动服务的命令，之后的内容都会原样传递：

claude mcp add --env EVOLUTION_API_URL=https://evolution.example.com \
  --env EVOLUTION_INSTANCE_TOKEN=your-instance-token-here \
  --transport stdio evolution-api-mcp -- uvx evolution-api-mcp

注意参数顺序。--env 接受 KEY=value 对，并会持续读取，因此服务名称不能紧跟在它后面：中间至少要放置另一个选项，此处使用的是 --transport stdio，否则 CLI 会将 evolution-api-mcp 读取为另一个键值对并拒绝该命令。

--scope 决定配置条目的存放位置：local（默认值：仅当前项目，仅你可用）、project（仓库根目录下的 .mcp.json，提交后可共享）或 user（适用于所有项目）。若要手动写入，可将相同条目放在 .mcp.json 的 mcpServers 下，或写入 ~/.claude.json：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      },
      "timeout": 120000
    }
  }
}

每个服务的 timeout 是单次工具调用的墙钟时间限制，单位为毫秒，并且仅对该服务覆盖环境变量 MCP_TOOL_TIMEOUT；同样以毫秒为单位的 MCP_TIMEOUT 则限制服务启动时间。编辑后，可在 /mcp 面板中重新连接服务，或重启 Claude Code。

上面的一行命令会在你的计算机上运行服务。Claude Code 也可以使用托管服务，无需安装或设置环境变量：

claude mcp add --transport http evolution-api-mcp https://evolution-mcp.singleflo.com/mcp

首次调用工具时会启动登录流程，并进入同意页面，你可在此选择策略和工具集。使用托管方式时，访问控制由该页面决定，而非本地的 EVOLUTION_MCP_* 变量，并且不会提供不可逆工具。

来源：https://code.claude.com/docs/en/mcp

omp（oh-my-pi）

omp 会读取项目中的 .omp/mcp.json，或读取 ~/.omp/agent/mcp.json，将其中的 MCP 服务用于所有项目。${NAME} 和 ${NAME:-default} 会从启动 omp 时所在的环境中展开，因此在该环境中导出这两个变量，就能避免将令牌写入可能会提交的文件；也可以使用字面值：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "${EVOLUTION_API_URL}",
        "EVOLUTION_INSTANCE_TOKEN": "${EVOLUTION_INSTANCE_TOKEN}"
      },
      "timeout": 120000
    }
  }
}

如果变量未设置，占位符会保留为字面文本，服务随后会将该文本作为 URL 或令牌启动，因此请从同时设置了这两个变量的 shell 启动 omp。timeout 的单位为毫秒，默认值为 30 秒； OMP_MCP_TIMEOUT_MS 会覆盖所有单个服务的设置。omp 还会读取 Claude Code、Codex、Gemini CLI、 opencode、Cursor、Windsurf 和 VS Code 的 MCP 文件，因此为其中任一工具编写过的配置无需重复添加。/mcp list 会显示服务来自哪个文件，/mcp reload 会重新读取这些文件，/mcp test evolution-api-mcp 会检查连接。

来源：https://github.com/can1357/oh-my-pi/blob/main/docs/mcp-config.md

GitHub Copilot CLI

copilot mcp add 会将条目写入 ~/.copilot/mcp-config.json；-- 后面的所有内容都是用于启动服务的命令：

copilot mcp add evolution-api-mcp \
  --env EVOLUTION_API_URL=https://evolution.example.com \
  --env EVOLUTION_INSTANCE_TOKEN=your-instance-token-here \
  --timeout 120000 \
  -- uvx evolution-api-mcp

相同的条目也可以直接写成：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      },
      "tools": [
        "*"
      ]
    }
  }
}

Copilot CLI 只会将环境中的 PATH 传递给服务，因此这两个变量都必须放在这个 env 块中。tools 可设为 * 以包含所有工具，也可设为名称列表以仅公开部分工具。项目可以在 .mcp.json 或 .github/mcp.json 中配置自己的服务，但只有在首次启动时信任该文件夹后才会加载；对于不受信任的文件夹，这些配置会被静默跳过；不会读取 VS Code 的 .vscode/mcp.json。会话中的 /mcp 会列出服务及其状态。

来源：https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers

Antigravity

Antigravity 会将服务配置保存在 ~/.gemini/config/mcp_config.json 中，或保存在工作区的 .agents/mcp_config.json 中。在 IDE 中，依次打开 Agent 侧边栏顶部的 ⋯ → MCP Servers → Manage MCP Servers → View raw config；在 CLI 中，/mcp 会打开 MCP 管理器，可在其中重新加载服务并查看连接日志：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

Antigravity 2.0 使用相同格式，并会在 Settings → Customizations → Installed MCP Servers 下列出服务。对于 WhatsApp Business Platform 实例的托管服务，需使用键 serverUrl （"serverUrl": "https://evolution-mcp.singleflo.com/mcp"）：不支持其他主机的 url 和 httpUrl。权限策略中不允许使用的工具会以 Ask 模式运行，因此 Antigravity 会在每次调用前征求确认。

来源：https://antigravity.google/docs/mcp

Kiro（IDE、CLI）

Kiro 会为每个工作区读取 ~/.kiro/settings/mcp.json，并为单个工作区读取 .kiro/settings/mcp.json；如果两者都存在，则会合并配置，工作区条目优先。在 IDE 中，可通过命令面板打开配置，选项为 Kiro: Open user MCP config (JSON) 和 Kiro: Open workspace MCP config (JSON)：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

CLI kiro-cli（取代 Amazon Q Developer CLI）会写入相同的条目：

kiro-cli mcp add --name evolution-api-mcp --scope global --command uvx --args evolution-api-mcp \
  --env EVOLUTION_API_URL=https://evolution.example.com \
  --env EVOLUTION_INSTANCE_TOKEN=your-instance-token-here

Kiro 会在下一次轮次间的空闲时应用已保存的更改，无需重启。autoApprove 用于列出无需确认即可运行的工具；基于 Cline 部分所述的原因，请勿添加该项。

来源：https://kiro.dev/docs/mcp/configuration

Goose

Goose 使用 YAML 配置扩展，在 ~/.config/goose/config.yaml 的 extensions: 下添加配置；timeout 的单位为秒：

extensions:
  evolution-api-mcp:
    name: Evolution API Assistant
    type: stdio
    cmd: uvx
    args:
      - evolution-api-mcp
    envs:
      EVOLUTION_API_URL: https://evolution.example.com
      EVOLUTION_INSTANCE_TOKEN: your-instance-token-here
    enabled: true
    timeout: 300

在桌面应用中，侧边栏的 Extensions 页面提供 Add custom extension：选择 Standard IO，命令填写 uvx evolution-api-mcp，然后每次点击 Add 按钮添加一个环境变量。此链接会在 goose 中打开同一对话框，只有确认后才会安装：

goose://extension?cmd=uvx&arg=evolution-api-mcp&timeout=300&id=evolution-api-mcp&name=Evolution%20API%20Assistant&description=Operate%20one%20Evolution%20API%20WhatsApp%20instance

链接不包含环境变量，因此之后请打开扩展的设置并设置 EVOLUTION_API_URL 和 EVOLUTION_INSTANCE_TOKEN。

来源：https://goose-docs.ai/docs/getting-started/using-extensions

LM Studio

LM Studio 使用 Cursor 的 mcp.json 格式。在右侧边栏的 Program 选项卡中，点击 Install → Edit mcp.json 打开文件，然后在 mcpServers 下添加条目：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

此链接会打开 LM Studio 的安装对话框，并预先填入该条目；只有确认后才会添加：

lmstudio://add_mcp?name=evolution-api-mcp&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJldm9sdXRpb24tYXBpLW1jcCJdLCJlbnYiOnsiRVZPTFVUSU9OX0FQSV9VUkwiOiJodHRwczovL2V2b2x1dGlvbi5leGFtcGxlLmNvbSIsIkVWT0xVVElPTl9JTlNUQU5DRV9UT0tFTiI6InlvdXItaW5zdGFuY2UtdG9rZW4taGVyZSJ9fQ%3D%3D

链接中包含两个占位值，因此安装后请在 mcp.json 中编辑它们。其 config 参数是经过 Base64 编码和 URL 编码的 JSON 条目。

来源：https://lmstudio.ai/docs/app/mcp

来源：https://lmstudio.ai/docs/app/mcp/deeplink

Kilo Code

Kilo Code 将 MCP 服务保存在主配置文件中：适用于所有项目的 ~/.config/kilo/kilo.jsonc，或仅适用于一个项目的 .kilo/kilo.jsonc（或项目根目录下的 kilo.jsonc）；项目级配置的优先级更高。其结构采用 opencode 的格式，而不是其他宿主使用的 mcpServers：键名为 mcp，command 是一个数组，配置块为 environment：

{
  "mcp": {
    "evolution-api-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "evolution-api-mcp"
      ],
      "environment": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      },
      "enabled": true,
      "timeout": 120000
    }
  }
}

timeout 的单位是毫秒。其默认值为 10 秒，对于首次调用来说太短，因为此时 uvx 可能仍在下载软件包，因此示例中调高了该值。在 Windows 上，命令为 ["cmd", "/c", "uvx", "evolution-api-mcp"]。VS Code 扩展也提供 Settings → MCP → Add Server，可用于添加相同条目。

来源：https://kilo.ai/docs/automate/mcp/using-in-kilo-code

Continue

Continue 会从工作区顶层的 .continue/mcpServers/ 目录中为每个服务加载一个 YAML 文件。将以下内容保存为 .continue/mcpServers/evolution-api-mcp.yaml：

name: Evolution API Assistant
version: 0.0.1
schema: v1
mcpServers:
  - name: evolution-api-mcp
    command: uvx
    args:
      - evolution-api-mcp
    env:
      EVOLUTION_API_URL: https://evolution.example.com
      EVOLUTION_INSTANCE_TOKEN: your-instance-token-here

MCP 工具只能在 Continue 的 Agent 模式下使用；聊天和编辑模式不会调用这些工具。

来源：https://docs.continue.dev/customize/deep-dives/mcp

Qwen Code

qwen mcp add 会写入用户级配置 ~/.qwen/settings.json，除非你传入 --scope project，这会将配置写入项目中的 .qwen/settings.json：

qwen mcp add evolution-api-mcp \
  -e EVOLUTION_API_URL=https://evolution.example.com \
  -e EVOLUTION_INSTANCE_TOKEN=your-instance-token-here \
  uvx evolution-api-mcp

以下是写出的相同条目：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

env 中的值可以通过 $VAR 或 ${VAR} 引用 shell 环境变量，从而避免将令牌写入可能会提交的文件中。timeout 的单位是毫秒，默认值已为 600000。如果 Qwen Code 正在运行，请重启，然后使用 /mcp 检查服务。

来源：https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/

Amp

Amp 将本地 MCP 服务保存在 ~/.config/amp/settings.json 中，使用点分键 amp.mcpServers：

{
  "amp.mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

项目的 .amp/settings.json 中使用相同的键，可与团队共享服务，但工作区服务在运行前需要获得你的批准：运行 amp mcp approve evolution-api-mcp 即可批准，运行 amp mcp doctor 可查看仍在等待批准的服务。全局文件中的服务无需批准。在配置文件中，${VAR_NAME} 会从环境变量中展开。

来源：https://ampcode.com/docs/markdown/customize/mcp

Warp

Warp 会读取适用于所有项目的 ~/.warp/.mcp.json，以及项目根目录下的 .warp/.mcp.json。你也可以打开 Settings → Agents → MCP servers，点击 + Add 并粘贴相同的 JSON：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

命令服务必须包含 args，否则 Warp 会拒绝该条目。全局 Warp 文件中的服务会自动启动；Warp 也会读取 Claude Code 和 Codex 的 MCP 文件，但只有在启用自动启动开关后才会启动这些服务。

来源：https://docs.warp.dev/agents/capabilities/mcp

Factory Droid

droid mcp add 接受服务名称，然后将命令作为一个带引号的字符串；--type 默认为 stdio：

droid mcp add evolution-api-mcp "uvx evolution-api-mcp" \
  --env EVOLUTION_API_URL=https://evolution.example.com \
  --env EVOLUTION_INSTANCE_TOKEN=your-instance-token-here

该条目会写入适用于所有项目的 ~/.factory/mcp.json；项目的 .factory/mcp.json 是共享配置文件：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

Droid 会从 shell 环境中展开 ${NAME}，但仅限于 env（和 headers）中，不会在 command 或 args 中展开，也不支持默认值形式。因此，"EVOLUTION_INSTANCE_TOKEN": "${EVOLUTION_INSTANCE_TOKEN}" 可以避免将令牌写入已提交的文件中。在会话中使用 /mcp 可查看服务及其工具。

来源：https://docs.factory.com/harness/mcp

OpenAI Codex CLI

Codex 使用 TOML 保存 MCP 服务配置，位置为 ~/.codex/config.toml；如果你已信任某个项目，也可以使用项目中的 .codex/config.toml。表名使用下划线：mcp_servers，而不是 mcp.servers。ChatGPT 桌面应用、Codex CLI 和 IDE 扩展都会读取此文件，因此配置一次即可供三者使用。在桌面应用中，Settings → MCP servers → Add server 会写入相同的条目。

codex mcp add evolution-api-mcp \
  --env EVOLUTION_API_URL=https://evolution.example.com \
  --env EVOLUTION_INSTANCE_TOKEN=your-instance-token-here \
  -- uvx evolution-api-mcp

以下是完整的相同条目：

[mcp_servers.evolution-api-mcp]
command = "uvx"
args = ["evolution-api-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 300

[mcp_servers.evolution-api-mcp.env]
EVOLUTION_API_URL = "https://evolution.example.com"
EVOLUTION_INSTANCE_TOKEN = "your-instance-token-here"

两个超时值的单位都是秒：startup_timeout_sec 默认值为 10，tool_timeout_sec 默认值为 60。上方提高了第二个超时值，因为大文件上传或持续较久的输入指示可能超过一分钟。编辑后，在桌面应用或 IDE 扩展中点击服务器旁的 Restart；在 CLI 中，启动新会话并使用 /mcp 检查。

托管服务则通过 URL 添加，登录需要使用单独的命令：

codex mcp add evolution-api-mcp --url https://evolution-mcp.singleflo.com/mcp
codex mcp login evolution-api-mcp

codex mcp login 会引导你完成相同的 OAuth 流程，并跳转到授权页面，在那里选择策略和工具集；codex mcp logout evolution-api-mcp 会结束连接。与所有托管方式一样：始终可以读取；写入操作遵循登录时选择的策略；不可逆工具则完全不可用。

来源：https://learn.chatgpt.com/docs/extend/mcp

来源：https://developers.openai.com/codex/config-file/config-reference

ChatGPT

ChatGPT 会通过网页添加的自定义 MCP 服务连接托管服务。谁可以添加服务，由账户和工作区策略决定。

打开 ChatGPT 插件并点击加号按钮，然后选择 Add custom MCP server。
输入名称和描述，在 Connection 下选择公共端点，并输入 MCP URL https://evolution-mcp.singleflo.com/mcp，其中必须包含 /mcp 路径。
配置身份验证，查看风险警告，选择 I understand and want to continue，然后选择 Create as a plugin。ChatGPT 会启动登录流程并跳转到服务器的授权页面：输入你的 Evolution URL 和实例令牌，然后选择策略和工具集。
开始新对话，输入 @ 并选择 Evolution API Assistant 插件。

这里特意不提供本地配置片段：ChatGPT 通过公共 HTTPS 端点（或 OpenAI Secure MCP Tunnel）连接自定义 MCP 服务，因此其他章节中的 stdio 配置不适用。ChatGPT 插件目录的公开列表计划推出，但目前尚未上线。

Agent 可以执行哪些操作，在登录时就已确定：策略和工具集；无论对话中提出什么请求，都不会开放不可逆工具。

来源：https://developers.openai.com/plugins/deploy/connect-chatgpt

Claude.ai（网页、桌面端、移动端）

Claude 通过自定义连接器连接托管服务。打开 Customize → Connectors → Add custom connector，将 https://evolution-mcp.singleflo.com/mcp 粘贴为服务 URL，然后确认。在 Team 和 Enterprise 套餐中，所有者可在 Organization settings → Connectors 下添加一次；成员随后可通过 Customize → Connectors 连接。

首次使用时会启动登录流程，并跳转到授权页面：输入你的 Evolution URL 和实例令牌，然后选择策略和工具集。

点击此链接会打开相同的对话框，名称和 URL 已预先填好；请检查并确认，只有确认后才会添加：

https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Evolution%20API%20Assistant&connectorUrl=https%3A%2F%2Fevolution-mcp.singleflo.com%2Fmcp

来源：https://claude.com/docs/connectors/custom/remote-mcp

来源：https://claude.com/docs/connectors/building/directory-vs-custom

Open WebUI 和 Mistral Le Chat

这两个客户端只能连接远程 MCP 服务，因此使用托管服务 https://evolution-mcp.singleflo.com/mcp，该服务接受 WhatsApp Business Platform 和 Baileys 实例。对于 Evolution 通道实例，请在上述某个主机中运行本地服务。登录方式与“托管服务”部分所述相同：在服务的同意页面上填写 Evolution URL、实例令牌，以及策略和工具集。

Open WebUI。 管理员打开 Settings → Admin → Integrations，在 External Tool Servers 下点击 + Add Connection，将 Type 设为 MCP (Streamable HTTP)，输入 https://evolution-mcp.singleflo.com/mcp 作为 URL，并选择 OAuth 2.1 作为身份验证方式。请确保类型不是 OpenAPI：在 OpenAPI 连接中添加 MCP 条目会导致页面崩溃。在 Docker 设置中设置 WEBUI_SECRET_KEY，否则每次重新创建容器时，已保存的登录信息都会丢失。

来源：https://docs.openwebui.com/features/extensibility/mcp

Mistral Le Chat。 管理员打开 Connectors，点击 + Add Connector，切换到 Custom MCP Connector 选项卡，并填写一个不含空格或特殊字符的连接器名称（例如 EvolutionAPI）和服务器 URL https://evolution-mcp.singleflo.com/mcp。点击 Connect 即可开始登录；平台会自行检测身份验证方式。对于 Free、Pro 和 Student 方案，账户所有者就是管理员。

来源：https://docs.mistral.ai/vibe/work/connectors/mcp-connectors

opencode

将以下内容添加到项目中的 opencode.json 或 .opencode/opencode.json，或者添加到 ~/.config/opencode/opencode.json，即可让服务器在所有位置可用：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "evolution-api-mcp": {
      "type": "local",
      "enabled": true,
      "command": [
        "uvx",
        "evolution-api-mcp"
      ],
      "timeout": 120000,
      "environment": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

opencode 的配置结构与上述主机不同，如果格式不符会直接拒绝。键名是 mcp（不是 mcpServers），必须指定 type，command 是一个包含程序及其参数的数组（没有单独的 args），环境变量区块是 environment（不是 env）。

请有意设置 timeout。默认值为 5000 ms，带有输入延迟的发送操作、还会对速度较慢的 Evolution 服务运行发现流程的首次调用，或媒体下载都可能超出此限制。请将其设为 120000。

opencode 只会在启动时读取一次配置，不会热重载。编辑后请退出并重新启动。你在此处所做的任何更改，包括工具集以及允许和拒绝列表，都要到下次启动后才会生效。

来源：https://opencode.ai/docs/mcp-servers

Hermes

Hermes 使用 YAML，将服务器配置保存在 ~/.hermes/config.yaml 中的 mcp_servers: 下：

mcp_servers:
  evolution-api-mcp:
    command: /Users/you/.local/bin/uvx
    args:
      - evolution-api-mcp
    env:
      EVOLUTION_API_URL: https://evolution.example.com
      EVOLUTION_INSTANCE_TOKEN: your-instance-token-here
    timeout: 120
    connect_timeout: 60
    enabled: true

这种配置结构有三点必须注意。command 是一个字符串，只填写程序；参数则放在单独的 args 列表中，这与 opencode 将两者放在同一个数组中的方式相反。环境变量区块是 env。此外，命令必须使用绝对路径：Hermes 以桌面应用的形式运行，不会继承 shell 的 PATH，因此无法找到单独写作 uvx 的命令。

这里的两个超时值都以秒为单位，而不是毫秒：timeout 是工具调用时限，默认为 300；connect_timeout 用于限制初始连接时间，默认为 60。编辑后请使用 /reload-mcp 重新加载服务器，而不是重启。

config.yaml 中的值可以引用 ${VAR}（或 ${env:VAR}），其值先从 ~/.hermes/.env 解析，再从进程环境中解析，这样可以避免将令牌写入文件。

hermes mcp add 可以为你写入此条目（其签名为 add <name> [--url URL] [--command CMD] [--auth oauth|header] [--args ...]），但请将 --args 放在最后：它会接收剩余的 argv，因此其后的任何内容都会被纳入 args，凭据也会因此被放入其中，导致服务器启动时没有凭据。

来源：https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference

Cursor

将此内容添加到项目中的 .cursor/mcp.json，添加到 ~/.cursor/mcp.json 以便在所有位置使用此服务，或在侧边栏的 自定义 中进行配置：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

Cursor 会在 command、args、env、url 和 headers 中插入 ${env:NAME} 的值，因此 "EVOLUTION_INSTANCE_TOKEN": "${env:EVOLUTION_INSTANCE_TOKEN}" 可以避免将令牌写入可能会提交的文件。如果调用失败，可在“输出”面板的 MCP 日志下查看原因。

Cursor 也支持通过链接安装，链接的 config 参数是经过 base64 编码的 JSON 条目。此链接包含两个占位值，因此安装后请在 mcp.json 中编辑它们：

cursor://anysphere.cursor-deeplink/mcp/install?name=evolution-api-mcp&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJldm9sdXRpb24tYXBpLW1jcCJdLCJlbnYiOnsiRVZPTFVUSU9OX0FQSV9VUkwiOiJodHRwczovL2V2b2x1dGlvbi5leGFtcGxlLmNvbSIsIkVWT0xVVElPTl9JTlNUQU5DRV9UT0tFTiI6InlvdXItaW5zdGFuY2UtdG9rZW4taGVyZSJ9fQ==

要使用自己的值创建链接，请对不含换行符的条目进行编码：

printf '%s' '{"command":"uvx","args":["evolution-api-mcp"],"env":{"EVOLUTION_API_URL":"https://evolution.example.com","EVOLUTION_INSTANCE_TOKEN":"your-instance-token-here"}}' | base64 | tr -d '\n'

来源：https://cursor.com/docs/context/mcp

来源：https://cursor.com/docs/mcp/install-links

Windsurf（Devin Desktop）

Windsurf 现已更名为 Devin Desktop。其 Cascade Agent 在所有平台上都会读取一个全局文件，官方文档注明其位置如下：

macOS 和 Linux：~/.config/devin/mcp_config.json（如果设置了该变量，则位于 $XDG_CONFIG_HOME/devin/ 下）
Windows：%APPDATA%\devin\mcp_config.json

仍以 Windsurf 运行的安装会改为读取 ~/.codeium/windsurf/mcp_config.json。此条目适用于你打开的所有工作区：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

在 Cascade 面板的 ... 菜单中，点击 Open MCP config file 图标打开该文件，然后刷新服务列表。该文件会在 command、args 和 env 中插入 ${env:VAR_NAME} 和 ${file:/path/to/file} 的值，因此令牌可以存放在文件之外。此文件属于 Cascade Agent。较新的 Devin Local Agent（新标签页的默认 Agent）通过 Devin CLI 管理其服务：使用同一个用户文件，以及项目中的 .devin/mcp_config.json，并由 devin mcp add 写入。Cascade 的工具总数上限为 100 个。对于 Baileys 实例，此服务在默认工具集下显示 32 个工具，在设置 EVOLUTION_MCP_TOOLSETS=all 时显示 81 个（参见“工具集”下方的表格）。因此，当其他服务也要占用此配额时，请保留默认设置，或选择所需的工具集。

来源：https://docs.devin.ai/desktop/cascade/mcp

来源：https://docs.devin.ai/cli/extensibility/mcp/configuration

来源：https://code.visualstudio.com/docs/agents/reference/mcp-configuration

VS Code 和 GitHub Copilot

VS Code 会从多个文件读取 MCP 服务，根键取决于文件。便于跨环境使用的文件采用 mcpServers：可将工作区根目录下的 .mcp.json 与项目一同提交，或使用 ~/.copilot/mcp-config.json（如果设置了该变量，则为 $COPILOT_HOME/mcp-config.json）供所有工作区使用；GitHub Copilot CLI 也会读取同一个文件。为条目添加 "type": "stdio"：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

工作区中的 .vscode/mcp.json，以及通过 MCP: Open User Configuration 打开的用户配置文件，仍会被读取，但 VS Code 已将它们标记为弃用格式。它们的根键是 servers，而不是 mcpServers，因此在两种格式之间复制条目不会生效：

{
  "servers": {
    "evolution-api-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

命令行会将条目写入你的用户配置文件：

code --add-mcp "{\"name\":\"evolution-api-mcp\",\"command\":\"uvx\",\"args\":[\"evolution-api-mcp\"]}"

VS Code 首次启动服务时会询问你是否信任它；如果选择拒绝，服务将永远不会运行。使用 mcp.json 中的代码镜头，或通过命令面板中的 MCP: List Servers，即可启动、停止和重启服务，并查看其输出。避免在已提交的工作区文件中硬编码令牌：VS Code 提供了专门用于此目的的输入变量。

来源：https://code.visualstudio.com/docs/agent-customization/mcp-servers

Gemini CLI

自 2026-06-18 起，Gemini CLI 仅供 Gemini Code Assist Standard 和 Enterprise 用户以及付费 API 密钥用户使用；其他用户请改用 Antigravity（见上文）。它会从 settings.json 中读取 mcpServers：每个会话都读取 ~/.gemini/settings.json，或仅在对应项目中读取项目根目录下的 .gemini/settings.json；后者优先。

gemini mcp add evolution-api-mcp uvx evolution-api-mcp \
  --env EVOLUTION_API_URL=https://evolution.example.com \
  --env EVOLUTION_INSTANCE_TOKEN=your-instance-token-here \
  --scope user

相同配置的完整写法：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      },
      "timeout": 600000
    }
  }
}

timeout 是请求超时时间，单位为毫秒，默认值已是 600000，也就是 10 分钟，因此无需在此进行设置；此处列出它只是因为如果你希望更快失败，可以调低这个值。还有两个实用要点：Gemini CLI 会在启动服务前，从继承的环境变量中屏蔽所有匹配 *KEY*、*TOKEN* 或 *SECRET* 的内容，因此必须在此 env 块中命名变量，它才会传入；其中的 "$MY_VAR" 会从你的 shell 中展开。编辑后重启 CLI，然后使用 /mcp 检查服务。

来源：https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md

来源：https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/cli-reference.md

来源：https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/

Cline

Cline 的 CLI 会读取 ~/.cline/mcp.json。在 IDE 扩展中，打开 Cline 面板里的 MCP Servers 图标，转到 Configure 标签页并点击 Configure MCP Servers，即可打开扩展自己的设置 JSON。两者使用相同的 mcpServers 格式：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

请将 autoApprove 留空。此处列出的是无需询问即可运行的工具，而此服务中的确认机制不能代替在发送调用前阅读其内容。cline mcp 会打开交互式向导，可在不修改文件的情况下添加、编辑、启用和移除服务。请求超时是 MCP 设置面板中的单服务设置，而不是此文件中的配置项：如果大文件上传超时，请在那里调高超时时间，然后从同一面板重启服务。

对于通过 URL 指定地址的托管服务，配置项需要 "type": "streamableHttp"：Cline 会将没有 type 的配置项视为旧版 sse 传输方式。

来源：https://docs.cline.bot/mcp/mcp-overview

Zed

Zed 将其称为上下文服务，配置键是 context_servers，而不是 mcpServers。将配置项添加到设置文件中（打开命令面板，执行 zed: open settings file），或者让 Zed 通过 Settings → AI → MCP Servers → Add Server → Add Local Server 为你写入：

{
  "context_servers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

Settings → AI → MCP Servers 中服务名称旁的指示点会显示服务是否已启动：绿色，且悬停提示为 “Server is active”，表示 Zed 已成功连接。工具审批由 agent.tool_permissions.default 控制，默认值为 "confirm"；单个工具的规则使用键格式 mcp:evolution-api-mcp:<tool_name>，例如 mcp:evolution-api-mcp:send_text_message。

来源：https://zed.dev/docs/ai/mcp

JetBrains AI Assistant

JetBrains AI Assistant 通过对话框接收配置，而不是让你自行定位配置文件。前往 Settings | Tools | AI Assistant | Model Context Protocol (MCP)，点击 Add，选择 STDIO，然后粘贴以下 JSON 配置：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here"
      }
    }
  }
}

对话框会说明 command 和 args，并在 JSON 旁添加两个自有字段：Working directory 和 Server level，后者用于决定服务是全局可用，还是仅在当前项目中可用。点击 OK，然后点击 Apply：此时服务才会真正启动；Status 列会显示连接状态。如果此服务已添加到 Claude Desktop，则可以改用 Import from Claude 导入整个配置项，包括其中的环境变量块。

来源：https://www.jetbrains.com/help/ai-assistant/mcp.html

只读和更宽松的配置

如需让 Agent 连接到一个运行中的实例且仅进行读取，请将 EVOLUTION_MCP_ALLOW 设置为 "none"。以下是它在 Claude Desktop 中的配置示例，包含消息、聊天、联系人和群组工具集：

{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_API_URL": "https://evolution.example.com",
        "EVOLUTION_INSTANCE_TOKEN": "your-instance-token-here",
        "EVOLUTION_MCP_TOOLSETS": "messaging,chats,contacts,groups",
        "EVOLUTION_MCP_ALLOW": "none"
      }
    }
  }
}

设置为 none 后，发送工具甚至不会出现在列表中：tools/list 只显示读取工具。相反，如果要配置一个为客户答疑的助手，请保留默认工具集和设置；只有当每分钟 30 次变更太少时，才提高 EVOLUTION_MCP_MAX_WRITES_PER_MINUTE。

更新日志

各版本的变更记录见 CHANGELOG.md，我们将其保留在该文件中，而不在此重复，以免两处内容不一致。

贡献与安全

CONTRIBUTING.md 介绍开发环境设置和代码变更规则；SECURITY.md 介绍威胁模型以及如何报告漏洞。支持请求和错误报告请提交至 https://github.com/singleflo/evolution-api-mcp/issues。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

Evolution API Assistant 是 Persevida SL 的独立项目，与 Meta、WhatsApp 或 Evolution API 项目没有关联，也未获得其认可。“WhatsApp”是其所有者的商标，此处仅用于说明本软件适用的对象。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。