mcp-evolution

TypeScript MCP server for Evolution API (WhatsApp) with instance pinning.

Architecture

This server implements the Model Context Protocol:

• Transport: stdio — the MCP host (Claude Desktop, Claude Code, etc.) spawns this process and speaks JSON-RPC over stdin/stdout.
• Server: uses the high-level McpServer class from the official TypeScript SDK, which handles capability negotiation and session lifecycle automatically.
• Tools: 50 tools registered via registerTool() with Zod-validated input schemas — the SDK enforces types before the handler runs.

All three connection parameters (API URL, API key, instance name) are pinned at startup via environment variables. The AI caller cannot switch instances mid-conversation.

Tools

Message

Chat

Profile

Group

Instance

Webhook

Label

Install & run via npx

EVOLUTION_API_URL=http://localhost:8080 \
EVOLUTION_API_KEY=your-key \
EVOLUTION_INSTANCE=your-instance \
npx mcp-evolution

Configuration

Copy .env.example to .env for local development.

Use with Claude Desktop / Claude Code

Add to ~/.claude/claude_desktop_config.json or project .mcp.json:

{
  "mcpServers": {
    "whatsapp": {
      "command": "npx",
      "args": ["mcp-evolution"],
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "your-evolution-api-key",
        "EVOLUTION_INSTANCE": "your-instance-name"
      }
    }
  }
}

Or point directly at the built binary if running from a local checkout:

{
  "mcpServers": {
    "whatsapp": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-evolution/dist/index.js"],
      "env": {
        "EVOLUTION_API_URL": "http://localhost:8080",
        "EVOLUTION_API_KEY": "your-evolution-api-key",
        "EVOLUTION_INSTANCE": "your-instance-name"
      }
    }
  }
}

Development

# Install dependencies
npm install

# Run in dev mode (no build step)
npm run dev

# Build TypeScript → dist/
npm run build

# Run tests
npm test

# Start from built output
npm start

Evolution API endpoints wrapped

Requires Evolution API v2.

License

MIT — see LICENSE.

Disclaimer

Community software, not affiliated with Evolution API or any WhatsApp entity.