# WhatsApp MCP Server — Chat with WhatsApp via AI Agents

> MCP server connecting Claude and AI agents to your personal WhatsApp. Search contacts, read messages, send replies and media via natural language.

## Install

Merge the JSON below into your `.mcp.json`:

## Quick Use

1. Clone: `git clone https://github.com/lharries/whatsapp-mcp`
2. Start the WhatsApp bridge:
```bash
cd whatsapp-mcp/whatsapp-bridge
go run main.go
```
3. Scan the QR code with your phone's WhatsApp
4. Add to your MCP config (`.mcp.json`):
```json
{
  "mcpServers": {
    "whatsapp": {
      "command": "uv",
      "args": ["--directory", "/path/to/whatsapp-mcp/whatsapp-mcp-server", "run", "main.py"]
    }
  }
}
```
5. Restart Claude Code / Cursor

---

## Intro

WhatsApp MCP Server connects Claude and other AI agents to your personal WhatsApp account through the Model Context Protocol. With 5,500+ GitHub stars, it lets you search contacts, read message history, and send messages or media files — all via natural language commands. The Go bridge handles WhatsApp connectivity while the Python MCP server exposes tools to your AI agent.

Best for: developers who want AI agents to interact with WhatsApp contacts. Works with: Claude Code, Claude Desktop, Cursor. Setup time: under 5 minutes.

---

## WhatsApp MCP — AI-Powered WhatsApp Integration

### Architecture

The system has two components:
1. **Go Bridge** — Handles WhatsApp Web API connectivity and authentication via QR code
2. **Python MCP Server** — Exposes WhatsApp tools to AI agents via the Model Context Protocol

All messages are stored locally in SQLite for fast search and retrieval.

### Available Tools

| Tool | Description |
|------|-------------|
| `search_contacts` | Find WhatsApp contacts by name |
| `get_messages` | Retrieve message history from any chat |
| `send_message` | Send text messages to contacts or groups |
| `send_media` | Send images, documents, and audio files |
| `list_groups` | List all WhatsApp groups |

### Prerequisites

- Go 1.19+
- Python 3.6+ with UV package manager
- Claude Desktop, Cursor, or Claude Code
- FFmpeg (optional, for audio conversion)

### Setup for Claude Desktop

Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "whatsapp": {
      "command": "uv",
      "args": ["--directory", "/path/to/whatsapp-mcp/whatsapp-mcp-server", "run", "main.py"]
    }
  }
}
```

### Safety Note

This connects to your real WhatsApp account. Always review messages before sending through AI agents.

### FAQ

**Q: What is WhatsApp MCP Server?**
A: An MCP server that connects AI agents like Claude to your personal WhatsApp account, enabling message search, reading, and sending via natural language.

**Q: Is WhatsApp MCP Server free?**
A: Yes, it's free and open source under the MIT license.

**Q: Does it require WhatsApp Business API?**
A: No, it uses the WhatsApp Web multidevice API — just scan a QR code with your personal WhatsApp.

---

## Source & Thanks

> Created by [lharries](https://github.com/lharries). Licensed under MIT.
>
> [whatsapp-mcp](https://github.com/lharries/whatsapp-mcp) — ⭐ 5,500+

Thank you for bridging WhatsApp and the MCP ecosystem.

---

<!-- ZH -->

## 快速使用

1. 克隆仓库: `git clone https://github.com/lharries/whatsapp-mcp`
2. 启动 WhatsApp 桥接:
```bash
cd whatsapp-mcp/whatsapp-bridge
go run main.go
```
3. 用手机 WhatsApp 扫描 QR 码
4. 添加到 `.mcp.json` 配置中（见英文版 JSON）
5. 重启 Claude Code / Cursor

---

## 简介

WhatsApp MCP Server 通过 Model Context Protocol 将 Claude 等 AI Agent 连接到你的个人 WhatsApp 账户。拥有 5,500+ GitHub stars，支持搜索联系人、阅读消息历史、发送文字和媒体文件——全部通过自然语言命令完成。Go 桥接处理 WhatsApp 连接，Python MCP 服务器向 AI Agent 暴露工具。

---

## WhatsApp MCP — AI 驱动的 WhatsApp 集成

### 可用工具

| 工具 | 说明 |
|------|------|
| `search_contacts` | 按名称搜索 WhatsApp 联系人 |
| `get_messages` | 获取任意聊天的消息历史 |
| `send_message` | 向联系人或群组发送文字消息 |
| `send_media` | 发送图片、文档和音频文件 |

---

## 来源与感谢

> Created by [lharries](https://github.com/lharries). Licensed under MIT.
>
> [whatsapp-mcp](https://github.com/lharries/whatsapp-mcp) — ⭐ 5,500+

---
Source: https://tokrepo.com/en/workflows/78b5fdf6-1847-4be0-ad70-0cb44ddc61df
Author: MCP Hub