使用说明
WhatsApp MCP桥（安全加固）
一个安全强化的只读桥，通过模型上下文协议（MCP）将WhatsApp连接到Claude Desktop。自动同步来自选定WhatsApp群组的消息，以便Claude可以总结讨论、分析共享链接并回答有关群组对话的问题。
建筑
WhatsApp ──► Go Bridge (whatsmeow) ──► SQLite ──► Python MCP Server ──► Claude Desktop
│ │ │
├─ Unix Socket only ├─ Read-only ├─ stdio transport
├─ API Token auth │ mode (?ro) ├─ 9 read tools
├─ Group whitelist │ └─ 0 write tools
├─ HMAC-signed config │
├─ Content sanitization │
└─ Rate limiting │
安全特性
这座桥是用安全第一的方法建造的。每个设计决策都优先考虑数据保护：
| # | 功能 | 它的作用 |
|---|---|---|
| 1 | 只读 | 9个读取工具，0个发送/写入工具。Claude无法修改任何WhatsApp状态 |
| 2 | 集团白名单 | 仅存储来自明确选择的组的消息。私人聊天从不同步 |
| 3 | 域套接字 | 没有暴露的TCP端口。零网络攻击面 |
| 4 | API令牌认证 | 每个请求都需要256位随机承载令牌。持续的时间比较可防止计时攻击 |
| 5 | HMAC签名配置 | 使用HMAC-SHA256验证白名单文件的完整性。存储在macOS钥匙串中的密钥 |
| 6 | 不可变配置 | chflags uchg 防止在网桥外修改白名单 |
| 7 | 历史同步缓冲 | 消息被缓冲，直到加载白名单，防止启动时数据泄漏 |
| 8 | 内容消毒 | 在存储层剥离的提示注入模式（SYSTEM:、[INST]、ChatML、CDATA、零宽度字符） |
| 9 | 速率限制 | 下载端点上的令牌桶速率限制器（5次突发，1/秒重新填充） |
| 10 | 受限权限 | 所有敏感文件chmod 0600，目录0700 |
| 11 | 路径横向保护 | 媒体文件名已用 filepath.Base() |
| 12 | 请求大小限制 | HTTP请求体上限为1KB，通过 MaxBytesReader |
快速开始
先决条件
选项1：自动设置
bash setup-whatsapp-mcp-readonly.sh
此脚本处理一切：安装依赖关系、构建Go桥、设置Python MCP服务器和配置Claude Desktop。
选项2：手动设置
1.搭建围棋桥
cd whatsapp-bridge
go build -o whatsapp-bridge .
2.设置Python MCP服务器
cd whatsapp-mcp-server
uv venv
uv pip install "mcp[cli]>=1.6.0"
3.配置克劳德桌面
将此添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"whatsapp-readonly": {
"command": "uv",
"args": ["--directory", "/path/to/whatsapp-mcp-server", "run", "main.py"]
}
}
}
4.首轮
cd whatsapp-bridge
./whatsapp-bridge
首次运行时：
- 使用WhatsApp应用程序扫描二维码
- 选择要同步的组（交互式菜单）
- 网桥将同步消息历史记录并开始监听新消息
用法
跑步后，问克劳德这样的问题：
- “总结今天我的WhatsApp群组中发生的事情”
- “本周在[组名]中共享了哪些链接？”
- “[组名]的主要讨论主题是什么？”
- “显示[人]过去3天的消息”
- “下载昨天在[组名]中共享的图像”
MCP工具
| 工具 | 说明 |
|---|---|
list_chats |
列出所有已同步的WhatsApp聊天记录 |
list_messages |
按日期、发件人、聊天或关键字搜索/过滤邮件 |
get_chat |
通过JID获取聊天元数据 |
get_message_context |
获取周围的消息以获取上下文 |
search_contacts |
按姓名或电话号码搜索联系人 |
get_contact_chats |
获取涉及特定联系人的所有聊天记录 |
get_last_interaction |
获取联系人的最新消息 |
get_direct_chat_by_contact |
通过电话号码查找直接聊天 |
download_media |
从邮件中下载图像、视频和文档 |
管理组
随时更改同步的组：
cd whatsapp-bridge
./whatsapp-bridge --select-groups
文件结构
whatsapp-mcp-secure/
├── whatsapp-bridge/ # Go bridge (core)
│ ├── main.go # Security-hardened bridge
│ ├── go.mod
│ ├── go.sum
│ └── store/ # Runtime data (gitignored)
│ ├── whatsapp.db # WhatsApp session (0600)
│ ├── messages.db # Message store (0600)
│ ├── api_token # 256-bit auth token (0600)
│ ├── bridge.sock # Unix domain socket (0600)
│ ├── group_whitelist.json # HMAC-signed config (0600, uchg)
│ ├── group_whitelist.json.sig # HMAC signature (0600, uchg)
│ └── hmac_key # HMAC key fallback (0600)
├── whatsapp-mcp-server/ # Python MCP server
│ ├── main.py # MCP tool definitions
│ ├── whatsapp.py # Read-only data layer
│ └── pyproject.toml
├── setup-whatsapp-mcp-readonly.sh # Automated setup script
├── .gitignore
├── LICENSE
└── README.md
安全须知
- 没有数据离开你的机器。 该网桥在本地运行，在本地存储数据，并通过stdio与Claude Desktop通信。
- WhatsApp会话密钥 存储在
store/whatsapp.db拥有0600权限。小心保管这份文件。 - API令牌 首次运行时自动生成。如果泄露，请删除
store/api_token并重新启动桥。 - HMAC密钥 如果可用，则存储在macOS Keychain中，并具有基于文件的回退功能。
- 撤销访问权限，只需停止桥接并删除
store/目录。
贡献
欢迎投稿！请确保任何更改都能保持或改善安全态势。浏览安全检查表：
- 没有新的TCP/网络端点
- WhatsApp没有新的写入操作
- 所有用户输入都经过净化
- 使用限制权限创建的所有新文件
- 没有记录或打印秘密
许可证
MIT许可证-请参阅 许可证 了解详情。
