# Evolution API Assistant MCP server

> Operates a WhatsApp Evolution API instance to manage chats, messages, groups, contacts, and settings through an AI client.

- Repository: https://github.com/singleflo/evolution-api-mcp
- Page: https://hostedmcp.org/servers/singleflo/evolution-api-mcp
- Transport: stdio, remote
- Stars: 0
- License: MIT
- Latest version: 1.0.0

## Install

### Claude Code

```sh
claude mcp add --env EVOLUTION_INSTANCE_TOKEN=<YOUR_EVOLUTION_INSTANCE_TOKEN> --env EVOLUTION_API_URL=<EVOLUTION_API_URL> evolution-api-mcp -- uvx evolution-api-mcp
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_INSTANCE_TOKEN": "<YOUR_EVOLUTION_INSTANCE_TOKEN>",
        "EVOLUTION_API_URL": "<EVOLUTION_API_URL>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "evolution-api-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_INSTANCE_TOKEN": "<YOUR_EVOLUTION_INSTANCE_TOKEN>",
        "EVOLUTION_API_URL": "<EVOLUTION_API_URL>"
      }
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_INSTANCE_TOKEN": "<YOUR_EVOLUTION_INSTANCE_TOKEN>",
        "EVOLUTION_API_URL": "<EVOLUTION_API_URL>"
      }
    }
  }
}
```

### Codex (`~/.codex/config.toml`)

```toml
[mcp_servers.evolution-api-mcp]
command = "uvx"
args = ["evolution-api-mcp"]

[mcp_servers.evolution-api-mcp.env]
EVOLUTION_INSTANCE_TOKEN = "<YOUR_EVOLUTION_INSTANCE_TOKEN>"
EVOLUTION_API_URL = "<EVOLUTION_API_URL>"
```

### Gemini CLI (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "evolution-api-mcp": {
      "command": "uvx",
      "args": [
        "evolution-api-mcp"
      ],
      "env": {
        "EVOLUTION_INSTANCE_TOKEN": "<YOUR_EVOLUTION_INSTANCE_TOKEN>",
        "EVOLUTION_API_URL": "<EVOLUTION_API_URL>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `EVOLUTION_INSTANCE_TOKEN` | yes | yes | The token of this one instance (Evolution Manager: open the instance and copy its token). The server's global AUTHENTICATION_API_KEY is refused. The instance name and integration are discovered from the token. |
| `EVOLUTION_API_URL` | yes | no | URL of your Evolution API server (e.g. https://evolution.example.com). Evolution API 2.x is required. |
| `EVOLUTION_MCP_ALLOW` | no | no | Tools that change data the agent may call. `*` (default) allows every tool not denied; `none` makes the server read-only; or a comma list of tool names. Reads are never gated by this list. |
| `EVOLUTION_MCP_ALLOW_IRREVERSIBLE` | no | no | Tools that cannot be undone (logout_instance, delete_message_for_everyone, leave_group, delete_template, delete_chatbot, delete_openai_credential) run only when this is `yes` (also `true` or `1`). Default: no. |
| `EVOLUTION_MCP_DEFAULT_DELAY_MS` | no | no | Milliseconds of 'typing...' Evolution shows before each message is sent when a call gives no delay. Integer from 0 to 20000. Default: 1200. |
| `EVOLUTION_MCP_DENY` | no | no | Tool names the agent may never call. A value set here REPLACES the default list, which is post_status, remove_group_participants, set_webhook, set_event_channel, set_proxy, set_chatwoot_config. |
| `EVOLUTION_MCP_DOWNLOAD_DIR` | no | no | Absolute folder where download_message_media saves received files and export_chat its exports/ folders. Default: ~/Downloads/evolution-api-mcp. |
| `EVOLUTION_MCP_FILE_ROOTS` | no | no | Folders send_local_files may read: absolute paths of existing directories separated by the operating system's path separator (':' on macOS and Linux, ';' on Windows). Default: Desktop, Documents, Downloads, Pictures, Movies and Music in the home folder (those that exist) plus the download folder. |
| `EVOLUTION_MCP_MAX_WRITES_PER_MINUTE` | no | no | Maximum number of tools that change data per minute on this server; 0 turns the limit off. Integer, 0 or more. Default: 30. |
| `EVOLUTION_MCP_TIMEZONE` | no | no | IANA time zone for the times tools show and for times given without a zone, e.g. Europe/Rome. Default: the computer's zone (TZ, then /etc/localtime), else UTC. |
| `EVOLUTION_MCP_TOOLSETS` | no | no | Toolsets to enable: a comma list of instance, messaging, chats, contacts, groups, labels, profile, status, catalog, templates, settings, events, integrations, or the presets `core` and `all`. Default: `core` (messaging, chats, contacts). The --toolsets option overrides it. |

## FAQ

### What can I do with the Evolution API Assistant?

It allows you to read chats and message history, send messages and media, manage groups, contacts, labels, templates, and configure instance settings.

### What environment variables are required for a working setup?

You need `EVOLUTION_API_URL` (the base URL of your Evolution server) and `EVOLUTION_INSTANCE_TOKEN` (the token of one instance).

### Does the server support sending local files?

Yes, the local (stdio) version supports all three Evolution integrations and can send files from your disk.