使用说明

WhatsApp MCP服务器

这是WhatsApp的模型上下文协议（MCP）服务器。

通过此功能，您可以搜索和阅读您的个人Whatsapp消息（包括图像、视频、文档和音频消息），搜索您的联系人，并向个人或组发送消息。您还可以发送媒体文件，包括图像、视频、文档和音频消息。

它连接到您的 个人WhatsApp帐户 直接通过Whatsapp网络多设备API（使用怎么回事图书馆）。您的所有消息都存储在本地SQLite数据库中，只有当代理通过您控制的工具访问它们时，才会发送给LLM（如Claude）。

这里有一个例子，说明当它连接到克劳德时你可以做什么。

获取我参与的此项目和其他项目的更新在此处输入您的电子邮件

注意： 与许多MCP服务器一样，WhatsApp MCP受致命的三联征这意味着项目注入可能会导致私人数据泄露。

安装

先决条件

去
Python 3.10+
用于stdio模式的Anthropic Claude Desktop应用程序（或Cursor），或用于HTTP模式的任何MCP客户端
UV（Python包管理器），安装时使用 curl -LsSf https://astral.sh/uv/install.sh | sh
FFmpeg(可选的)-仅用于音频消息。如果你想将音频文件作为可播放的WhatsApp语音消息发送，它们必须在 .ogg Opus格式。安装FFmpeg后，MCP服务器将自动转换非Opus音频文件。没有FFmpeg，您仍然可以使用 send_file 工具。
MySQL(可选的)-默认情况下，系统使用SQLite。为了更好地处理大型消息历史记录，您可以配置MySQL。

步骤

克隆此存储库

git clone https://github.com/lharries/whatsapp-mcp.git
cd whatsapp-mcp

配置WhatsApp网桥 （可选）

WhatsApp网桥可以通过以下环境变量进行配置 whatsapp-bridge/.env。如果此文件不存在，请创建它：

cd whatsapp-bridge
cp .env.example .env  # If example exists, or create new file

关键配置选项：

# Device name that appears in WhatsApp > Linked Devices
DEVICE_NAME=WhatsApp MCP Server

# Database engine: 'sqlite' (default) or 'mysql'
DB_ENGINE=sqlite

# MySQL settings (only if DB_ENGINE=mysql)
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASS=your_password
DB_NAME=whatsapp_bridge

# REST API port for the Go bridge
API_PORT=9095

# MCP Server mode: 'stdio' (default for Claude Desktop) or 'streamable' (for HTTP access)
MCP_MODE=stdio

# MCP Server HTTP settings (only if MCP_MODE=streamable)
MCP_HOST=0.0.0.0
MCP_PORT=9096

数据库设置:

数据库 （默认）：无需额外设置。数据库文件是在中自动创建的 whatsapp-bridge/store/.
MySQL：使用提供的SQL架构创建数据库和表：
```
mysql -u root -p < whatsapp-bridge/etc/mysql.sql
```

运行WhatsApp桥

导航到whatsapp桥目录并运行Go应用程序：
```
cd whatsapp-bridge
go run main.go
```
第一次运行它时，系统会提示您扫描二维码。使用WhatsApp移动应用程序扫描二维码进行身份验证。

大约20天后，您可能需要重新进行身份验证。
连接到MCP服务器

MCP服务器支持两种操作模式：

标准模式 （默认值-适用于克劳德桌面/光标）

将以下json与相应的{{PATH}}值一起复制：
```
{
  "mcpServers": {
    "whatsapp": {
      "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // cd into the repo, run `pwd` and enter the output here + "/whatsapp-mcp-server"
        "run",
        "main.py"
      ]
    }
  }
}
```
对于 克劳德，将此另存为 claude_desktop_config.json 在您的Claude Desktop配置目录中：
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
对于光标，将此另存为 mcp.json 在Cursor配置目录中：
```
~/.cursor/mcp.json
```
或者重新启动Cursor。

流式HTTP模式 （用于自定义集成）

要将MCP服务器作为可从任何MCP客户端访问的HTTP端点运行，请执行以下操作：
1. 集 MCP_MODE=streamable 在 whatsapp-bridge/.env
2. 可选配置 MCP_HOST 和 MCP_PORT （默认值：0.0.0.0:9096）
3. 启动WhatsApp网桥和MCP服务器：
```
# Terminal 1: Start WhatsApp bridge
cd whatsapp-bridge
go run main.go

# Terminal 2: Start MCP server in HTTP mode
cd whatsapp-mcp-server
uv run main.py
```
4. MCP服务器将在 http://localhost:9096 （或您配置的主机/端口）
5. 将您的MCP客户端连接到此HTTP端点
重新启动克劳德桌面/光标

打开克劳德桌面，你现在应该看到WhatsApp是一个可用的集成。

或者重新启动Cursor。

Windows兼容性

如果您在Windows上运行此项目，请注意 go-sqlite3 需要 CGO将启用 以便编译和正常工作。默认情况下， CGO在Windows上已禁用，因此您需要显式启用它并安装C编译器。

使其工作的步骤：

安装C编译器
我们建议使用 Msys 2 安装适用于Windows的C编译器。安装MSYS2后，请确保添加 ucrt64\bin 文件夹到您的 PATH.
→ 提供分步指南这里.

启用CGO并运行应用程序

cd whatsapp-bridge
go env -w CGO_ENABLED=1
go run main.go

如果没有此设置，您可能会遇到以下错误：

Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.

架构概述

此应用程序由三个主要部分组成：

去WhatsApp桥 (whatsapp-bridge/)：Go应用程序，连接到WhatsApp的web API，通过二维码处理身份验证，并存储消息历史记录。它是WhatsApp和MCP服务器之间的桥梁，并为消息操作提供REST API。
Python MCP服务器 (whatsapp-mcp-server/)：实现模型上下文协议（MCP）的Python服务器，该协议为Claude（或其他MCP客户端）提供了与WhatsApp数据交互和发送/接收消息的标准化工具。支持stdio模式（用于Claude Desktop/Cursor）和HTTP模式（用于自定义集成）。
WhatsApp代理 (whatsapp-agent/)：一个自主代理，监控传入的WhatsApp消息，并使用GPT-4自动响应，可访问MCP工具。代理可以搜索网络（通过Tavily），访问对话历史记录，向联系人发送消息，并处理多步骤任务。

数据存储

消息历史记录可以存储在以下任一位置 数据库 （默认）或 MySQL （通过配置 .env)
SQLite：存储在中的数据库文件 whatsapp-bridge/store/ 目录
MySQL：集中式数据库，在处理大量消息历史时具有更好的性能
数据库维护聊天表(di_chats)和消息(ft_messages)
邮件被编入索引，以便高效搜索和检索

用法

连接后，您可以通过Claude与您的WhatsApp联系人进行交互，在您的WhatsApp对话中利用Claude的人工智能功能。

MCP工具

Claude可以访问以下工具与WhatsApp进行交互：

search_contacts：按姓名或电话号码搜索联系人
list_消息：使用可选筛选器和上下文检索邮件
list_chats：列出带有元数据的可用聊天记录
get_chat：获取特定聊天的信息
get_direct_chat_by_contact：查找与特定联系人的直接聊天
get_contact_chats：列出涉及特定联系人的所有聊天记录
get_last_交互：获取联系人的最新消息
get_message_context：检索特定消息的上下文
send_message：向指定的电话号码或组JID发送WhatsApp消息
send_file：将文件（图像、视频、原始音频、文档）发送给指定的收件人
send_audio_消息：将音频文件作为WhatsApp语音消息发送（要求文件为.ogg opus文件或必须安装ffmpeg）
下载_媒体：从WhatsApp消息下载媒体并获取本地文件路径或base64编码内容

媒体处理功能

MCP服务器支持发送和接收各种媒体类型：

媒体发送

您可以向WhatsApp联系人发送各种媒体类型：

图像、视频、文档：使用 send_file 共享任何支持的媒体类型的工具。
语音信息：使用 send_audio_message 该工具将音频文件作为可播放的WhatsApp语音消息发送。
- 为了获得最佳兼容性，音频文件应位于 .ogg Opus格式。
- 安装FFmpeg后，系统将自动将其他音频格式（MP3、WAV等）转换为所需的格式。
- 没有FFmpeg，您仍然可以使用 send_file 工具，但它们不会显示为可播放的语音消息。

媒体下载

默认情况下，只有媒体的元数据存储在本地数据库中。该消息将指示媒体已发送。要访问此媒体，您需要使用 download_media 工具：

参数:
- message_id：邮件的ID（在列出带有媒体的邮件时显示）
- chat_jid：可选-聊天JID（如果未提供，则自动检测）
- return_base64：可选布尔值（默认值：false）
  - false：返回下载媒体的本地文件路径
  - true：以base64编码字符串的形式返回媒体内容（对于直接集成API或嵌入响应非常有用）

使用示例:

# Get file path
download_media(message_id="ABC123...")
# Returns: {"success": true, "file_path": "/path/to/file.jpg"}

# Get base64 content
download_media(message_id="ABC123...", return_base64=true)
# Returns: {"success": true, "base64_content": "iVBORw0KGgo..."}

备注WhatsApp的媒体文件将在大约30天后过期。只有最近的媒体可以从WhatsApp的服务器下载。

WhatsApp代理

WhatsApp Agent是一个自动助理，可以监控您收到的WhatsApp消息，并使用GPT-4自动响应，可以访问所有MCP工具。

特性

自主消息处理：持续监控新收到的消息并生成智能响应
图像分析：自动检测和处理发送到WhatsApp的图像，提供详细描述，回答有关图像的问题，或从中提取信息（由GPT-4o Vision提供支持）
多工具访问：可以使用所有WhatsApp MCP工具（搜索联系人、发送消息、获取对话上下文等）
Web搜索集成：与Tavily集成，用于实时网络搜索，用当前信息回答问题
浏览器自动化：可选的Playwright集成，用于高级网络抓取、屏幕截图和交互式浏览器任务
多语言支持：自动检测并以对话语言进行响应
联系人消息转发：可以代表您向通讯簿中的其他联系人发送消息
会话上下文：维护以前消息（最多100条消息）的上下文，以便进行连贯的对话

配置

在根目录中配置代理 .env 文件：

# OpenAI Configuration
OPENAI_API_KEY=sk-your-openai-api-key

# Tavily Search (optional but recommended for web searches)
TAVILY=yes  # Set to 'yes' to enable web search capabilities
TAVILY_CMD=@modelcontextprotocol/server-tavily
TAVILY_API_KEY=tvly-your-tavily-api-key  # Get free key at tavily.com

# Playwright (optional - for browser automation and web scraping)
PLAYWRIGHT=yes  # Set to 'yes' to enable browser automation
PLAYWRIGHT_CMD=@executeautomation/playwright-mcp-server

# MCP Mode (should match your MCP server configuration)
MCP_MODE=streamable  # or 'stdio'
MCP_HOST=0.0.0.0
MCP_PORT=9096

运行代理

确保WhatsApp网桥和MCP服务器都在运行，然后启动代理：

# Activate the virtual environment
source venv/bin/activate

# Run the agent
python whatsapp-agent/agent.py

代理人将：

连接到MCP服务器（WhatsApp和可选的Tavily）
开始监视新的传入消息
使用GPT-4处理每条消息
自动生成并发送响应

代理能力

该代理旨在：

回答问题 需要时使用对话上下文和网络搜索
分析图像：当您发送图像时，代理可以描述它看到的内容，回答有关图像的问题，提取文本，识别对象等
向联系人发送消息当你说“告诉胡安……”或“派玛丽亚……”时，它会：
1. 按姓名搜索联系人
2. 向他们发送您指定的消息
3. 向您确认发送的内容
提供最新信息：自动在网络上搜索新闻、天气、股票价格等。
保持自然对话：根据上下文调整语言和语调
处理媒体：可以处理图像、视频和音频消息（通过MCP工具）

交互示例

You: "What's the weather like in Madrid today?"
Agent: [Searches web via Tavily] "Today in Madrid it's partly cloudy with temperatures..."

You: [Sends an image of a receipt]
Agent: [Analyzes image with GPT-4o Vision] "I can see a receipt from Mercadona for 45.67€. The items include..."

You: [Sends a photo] "What do you see in this image?"
Agent: [Analyzes image] "This appears to be a photo of... with... in the background..."

You: "Tell Juan we're meeting at 5pm tomorrow"
Agent: [Searches contact "Juan", sends message] "I've sent Juan: 'We're meeting at 5pm tomorrow'"

You: "What did Maria say yesterday?"
Agent: [Retrieves conversation context] "Yesterday Maria said..."

重要说明

代理处理消息 自动地 -它将响应所有传入消息
邮件标记为已处理，以避免重复响应
代理需要一个OpenAI API密钥，并使用：
- GPT-4涡轮增压器 仅用于文本消息
- GPT-4o 用于包含图像的消息（启用视觉功能）
Tavily集成是可选的，但建议用于当前的信息查询
代理尊重对话上下文和语言偏好
图像处理要求消息是最新的（WhatsApp媒体在约30天后过期）

技术细节

Claude向Python MCP服务器发送请求
MCP服务器向Go桥查询WhatsApp数据或直接查询数据库
Go桥接器访问WhatsApp API并使数据库保持最新
数据通过链流回克劳德
发送消息时，请求从Claude通过MCP服务器流向Go桥和WhatsApp
WhatsApp代理独立运行，监控数据库中的新消息，并使用MCP服务器进行处理和响应

故障排除

如果在运行uv时遇到权限问题，可能需要将其添加到PATH中或使用可执行文件的完整路径。
确保Go应用程序和Python服务器都在运行，以便集成正常工作。

身份验证问题

二维码未显示：如果二维码没有出现，请尝试重新启动身份验证脚本。如果问题仍然存在，请检查您的终端是否支持显示二维码。
WhatsApp已登录：如果您的会话已处于活动状态，Go桥将自动重新连接，而不会显示二维码。
已达到设备限制WhatsApp限制了链接设备的数量。如果达到此限制，您需要从手机上的WhatsApp中删除现有设备（设置>链接设备）。
未加载邮件：初始身份验证后，可能需要几分钟才能加载您的消息历史记录，特别是如果您有很多聊天记录。
WhatsApp不同步：如果您的WhatsApp消息与网桥不同步，请删除这两个数据库文件(whatsapp-bridge/store/messages.db 和 whatsapp-bridge/store/whatsapp.db)并重新启动网桥以重新进行身份验证。

有关其他Claude Desktop集成故障排除，请参阅 MCP文件。该文档包括检查日志和解决常见问题的有用提示。

WhatsApp消息管理服务器

使用说明

WhatsApp MCP服务器

安装

先决条件

步骤

标准模式（默认值-适用于克劳德桌面/光标）

流式HTTP模式（用于自定义集成）

Windows兼容性

使其工作的步骤：

架构概述

数据存储

用法

MCP工具

媒体处理功能

媒体发送

媒体下载

WhatsApp代理

特性

配置

运行代理

代理能力

交互示例

重要说明

技术细节

故障排除

身份验证问题

使用说明

WhatsApp MCP服务器

安装

先决条件

步骤

标准模式 （默认值-适用于克劳德桌面/光标）

流式HTTP模式 （用于自定义集成）

Windows兼容性

使其工作的步骤：

架构概述

数据存储

用法

MCP工具

媒体处理功能

媒体发送

媒体下载

WhatsApp代理

特性

配置

运行代理

代理能力

交互示例

重要说明

技术细节

故障排除

身份验证问题

相关 MCP

DuckDuckGo 搜索 MCP 服务器

图表生成MCP服务器

AI开发助手

必应中文搜索MCP服务器

PostgreSQL管理服务器

网页内容获取工具

标准模式（默认值-适用于克劳德桌面/光标）

流式HTTP模式（用于自定义集成）