AI导哈

WhatsApp集成服务器

一个用于WhatsApp集成的模型上下文协议（MCP）服务器，支持发送消息、搜索对话和访问WhatsApp历史记录。

  • by eddmann
  • Go
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 eddmann/whatsapp-mcp

使用说明

WhatsApp MCP服务器

用于WhatsApp集成的模型上下文协议（MCP）服务器。通过Claude和其他LLM发送消息、搜索对话和访问您的WhatsApp历史记录。

概述

此MCP服务器提供7个工具，通过whatsmow库与您的WhatsApp帐户进行交互：

  • list_chats -列出具有过滤、排序和分页功能的对话
  • list_消息 -使用日期范围筛选和上下文检索消息历史记录
  • 搜索消息 -使用SQLite FTS5和上下文对所有消息进行全文搜索
  • send_message -发送带有模糊名称匹配和回复/线程的文本和媒体消息
  • 下载_媒体 -将对话中的媒体文件下载到本地存储
  • get_connection_status -检查WhatsApp连接状态和数据库统计信息
  • catch_up -智能活动摘要，显示最近的聊天、问题和媒体

所有消息和聊天记录都保存到具有全文搜索功能的本地SQLite数据库中，从而可以对您的WhatsApp历史记录进行丰富的查询和分析。

先决条件

  • 码头工人

安装和设置

# Pull the image
docker pull ghcr.io/eddmann/whatsapp-mcp:latest

首次运行-WhatsApp配对

# Create directory for persistent storage
mkdir -p whatsapp-store

# Run the container (QR code will be displayed)
docker run -it --rm \
  -v "$(pwd)/whatsapp-store:/app/store" \
  ghcr.io/eddmann/whatsapp-mcp:latest

首次运行时，终端上将显示一个二维码：

  1. 在手机上打开WhatsApp
  2. 前往设置→ 链接设备→ 链接设备
  3. 扫描终端显示的二维码
  4. 等待历史同步完成（检查日志中的“历史同步持久消息计数=…”）

身份验证和数据存储

  • 会话存储：WhatsApp会话数据保存到 store/whatsapp.db 并在重新启动后持续存在
  • 消息数据库：所有消息和聊天记录都存储在 store/messages.db 使用FTS5全文搜索
  • 媒体下载：下载的媒体文件按以下方式组织 store/<chatJID>/ 目录
  • 无重新身份验证：初始配对后，服务器将使用存储的凭据自动重新连接

重要提示： 将卷装载到 /app/store 在容器重启期间持久化会话数据和消息。

Claude桌面配置

添加到配置文件中：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json

基本配置

{
  "mcpServers": {
    "whatsapp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/ABSOLUTE/PATH/TO/whatsapp-store:/app/store",
        "ghcr.io/eddmann/whatsapp-mcp:latest"
      ]
    }
  }
}

使用环境变量

{
  "mcpServers": {
    "whatsapp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/ABSOLUTE/PATH/TO/whatsapp-store:/app/store",
        "-e",
        "LOG_LEVEL=DEBUG",
        "ghcr.io/eddmann/whatsapp-mcp:latest"
      ]
    }
  }
}

可用环境变量

  • DB_DIR -SQLite数据库和下载媒体的目录-默认值： store
  • LOG_LEVEL -日志记录级别（调试、信息、警告、错误）-默认值： INFO
  • FFMPEG_PATH -用于音频转换的ffmpeg二进制文件的路径-默认值： ffmpeg

用法

让Claude使用自然语言与您的WhatsApp数据进行交互。

发送消息

"Send a message to John saying I'll be there in 10 minutes"
"Send a photo from ~/Desktop/photo.jpg to Bob"
"Send this audio recording to the Project Team group"
"Reply to that message from Sarah saying 'Sounds good!'"

收件人格式（模糊名称匹配）：

  • 联系人/组名： "John", "Bob", "Project Team" （搜索您的聊天记录）
  • 电话号码：无 + （例如。， 447123456789)
  • 完整JID： 447123456789@s.whatsapp.net 对于联系人， 123456@g.us 对于团体

如果发现一个名称有多个匹配项，系统将提示您使用完整的JID进行消歧。

消息线程：

回复特定消息以创建线程对话。您的回复中将引用原始信息。

查看对话

"Show me my recent chats"
"List my last 20 messages with John"
"Show the conversation with Dad from yesterday with context"

搜索邮件

"Search for all messages mentioning 'project deadline'"
"Find messages from Alice about the meeting"
"Search for 'birthday party' in my group chats"

媒体处理

"Download the latest photo from the Family group"
"Save that video Mick sent me yesterday"

获取活动摘要

"Catch me up on today's WhatsApp activity"
"Show me what happened in my WhatsApp groups this week"
"What questions have I been asked today?"

可用工具

工具 说明
list_chats 按最近的活动排序，列出带有消息预览的对话。仅按姓名/电话/组筛选。支持分页。
list_messages 列出对话中的消息。使用自然时间框架（今天、本周等）按联系人/组名和日期范围进行筛选。
search_messages 使用FTS5对所有邮件进行全文搜索。支持关键字、短语、布尔运算符和日期过滤器。
send_message 向联系人/组发送文本、媒体（图像/视频/音频/文档）或两者。模糊名称匹配和消息回复/线程支持。
download_media 将消息中的媒体文件（图像/视频/音频/文档）下载到按聊天组织的本地存储中。
get_connection_status 检查WhatsApp连接状态、登录状态、设备信息和数据库统计信息（聊天和消息计数）。
catch_up 智能活动摘要，显示最近消息、针对您的问题、媒体活动和关注标志的活动聊天。

许可证

MIT许可证-请参阅 许可证 详细信息文件

免责声明

本项目不隶属于WhatsApp股份有限公司或Meta Platforms，股份有限公司，也不由其背书或赞助。使用风险自负。使用此软件时，请确保遵守WhatsApp的服务条款。

鸣谢

灵感源自 拉里斯/whatsapp mcp

相关 MCP