WAHA MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with WhatsApp through the WAHA (WhatsApp HTTP API) platform.

Features

• Chat Management: Get overview of recent WhatsApp chats
• Message Operations: Retrieve, send, and mark messages as read
• MCP Resources: Access WhatsApp data as context-aware resources with caching
• MCP Integration: Full compatibility with MCP clients (stdio transport)

Installation

1. Clone this repository

2. Install dependencies:

npm install

3. Configure your WAHA API connection:

cp .env.example .env

Then edit `.env` with your WAHA instance details.

Configuration

Required environment variables in `.env`:

• `WAHA_BASE_URL`: Your WAHA server URL (e.g., `http://localhost:3000`)
• `WAHA_API_KEY`: Your WAHA API key for authentication
• `WAHA_SESSION`: WhatsApp session name (default: `default`)

Development

Build the project

npm run build

Run in development mode with auto-reload

npm run dev

Test with MCP Inspector

The MCP Inspector is a web-based tool to test your MCP server interactively:

npm run inspector

This will:

1. Start the WAHA MCP server

2. Launch the MCP Inspector web UI

3. Open your browser automatically

Use the inspector to:

• Test all tools interactively
• View tool schemas
• See request/response data
• Debug tool calls

Run in production

npm start

Usage with Claude Desktop

Add this to your Claude Desktop MCP configuration:

Windows:

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\path\\to\\waha\\dist\\index.js"],
      "env": {
        "WAHA_BASE_URL": "http://localhost:3000",
        "WAHA_API_KEY": "your-api-key-here",
        "WAHA_SESSION": "default"
      }
    }
  }
}

Mac/Linux:

{
  "mcpServers": {
    "waha": {
      "command": "node",
      "args": ["/absolute/path/to/waha-mcp-server/dist/index.js"],
      "env": {
        "WAHA_BASE_URL": "http://localhost:3000",
        "WAHA_API_KEY": "your-api-key-here",
        "WAHA_SESSION": "default"
      }
    }
  }
}

> Note: Windows users should use double backslashes (`\\`) in paths.

Available Tools

Chat Management

Messaging

Groups

Contacts

Presence

MCP Resources

In addition to tools, the server exposes MCP Resources for context-aware data access:

Available Resources

• `waha://chats/overview` - Recent chats with last message previews
• `waha://chat/{chatId}/messages` - Message history from a specific chat

Resources support query parameters for filtering and pagination. Data is cached for 5 minutes for performance.

Project Structure

waha-mcp-server/
├── src/
│   ├── index.ts              # Server entry point
│   ├── config.ts             # Configuration management
│   ├── types/                # TypeScript type definitions
│   ├── tools/                # MCP tool implementations
│   ├── resources/            # MCP resource implementations
│   │   ├── base/             # Base resource class
│   │   ├── implementations/  # Concrete resources
│   │   ├── cache/            # LRU caching layer
│   │   └── manager/          # Resource registry
│   └── client/               # WAHA API client
├── dist/                     # Built JavaScript output
├── .env                      # Your configuration (not in git)
├── .env.example              # Configuration template
├── package.json
└── tsconfig.json

Chat ID Format

WhatsApp chat IDs have specific formats:

• Individual chats: `@c.us` (e.g., `1234567890@c.us`)
• Group chats: `@g.us` (e.g., `123456789012345678@g.us`)

You can get chat IDs by using the `waha_get_chats` tool first.

License

ISC