WA MCP is a TypeScript-based MCP server that exposes WhatsApp as discoverable tools, resources, and real-time events for AI agents. It supports dual backends (Baileys and Meta Cloud API) and can be deployed with Docker in a single command. The server makes 63 WhatsApp-related tools and 12 real-time events available to agents via the MCP protocol, enabling agents to manage WhatsApp connections, send messages, manage chats, and respond to real-time events without writing REST wrappers or glue code. To use it, you can run the server with Docker or locally via Node.js and connect your agent to the MCP endpoint (e.g., http://localhost:3000/mcp). Agents such as Claude Desktop, LangChain tooling, or Python adapters can auto-discover and utilize the full toolset.

Prerequisites:

• Docker (for the Docker deployment) or Node.js v22+ and Redis (for local/dev setup)
• Docker Compose (if using docker-compose.yml)
• Git

Using Docker (recommended):

1. Clone the repository and navigate to the project directory
2. Ensure an available Redis instance (or use the provided docker-compose setup that includes Redis)
3. Start the server: docker compose up
4. The MCP endpoint will be available at http://localhost:3000/mcp

Using Node.js locally (development/production):

1. Prerequisites: Node.js v22+, Redis running
2. Install dependencies: npm install
3. Development (stdio transport): cp .env.example .env # or set needed env vars npm run dev

   Connect to the stdio transport at the agent side via the MCP endpoint

4. Production (HTTP transport): npm run build npm start

Recommended environment variables (examples):

• WA_TRANSPORT: set to stdio or http (depending on transport)
• WA_REDIS_URL: Redis connection string, e.g. redis://localhost:6379
• Any other WA MCP specific configuration required by your deployment

Notes:

• The server exposes 63 WhatsApp tools across 9 domains and 12 real-time events.
• The Docker deployment brings up WA MCP + Redis in a single command.

Tips and common issues:

• If you run into port conflicts, ensure Docker Compose isn't already occupying the default port (http://localhost:3000/mcp).
• When using the stdio transport, ensure the agent environment supports reading from stdin/stdout and that the MCP endpoint matches the tool configuration in your agent.
• Environment variables such as WA_TRANSPORT and WA_REDIS_URL are commonly required; adjust per deployment (see Claude Desktop example in the README for a sample config).
• The MCP config in agents can refer to a node-based path like path/to/wa-mcp/dist/index.js if running directly with Node; in Docker deployments, use docker-based commands as shown above.
• For large-scale usage (multi-instance WhatsApp numbers), you can scale using Docker workflows or separate Node processes; the server supports multi-instance operation with appropriate Redis-backed storage.