WhatsApp集成工具

WhatsApp MCP🟢

使用 模型上下文协议（MCP），使人工智能助手（如克劳德）能够直接从您的桌面读取和发送WhatsApp消息。

内置：

• 桥 --Next.js+ 百利甜酒 （WhatsApp网站API）
• 服务器 python FastMCP （MCP服务器）
• 存储 --SQLite通过 better-sqlite3 （当地 data/ 文件夹）

📁 项目结构

whatsapp-mcp/
├── bridge/          # Next.js app — WhatsApp connection & REST API
│   ├── src/
│   │   ├── lib/
│   │   │   ├── whatsapp.ts      # Baileys socket, sync, message handling
│   │   │   └── database.ts      # SQLite schema & helpers
│   │   └── app/api/             # REST endpoints
│   ├── data/                    # Auto-created: auth + SQLite DB
│   └── package.json
│
└── server/          # Python MCP server — exposes tools to Claude
    ├── main.py      # FastMCP tools (send, receive, chats, contacts...)
    ├── pyproject.toml
    └── .env

✨ 特性

• 🔐 二维码登录 --扫描一次，会话自动持续
• 💬 发送和接收 通过AI助手发送消息
• 📋 聊天和联系 --浏览所有对话和联系人
• 🔍 搜索 所有聊天记录中的消息
• 🔄 完整历史同步 --首次连接时同步消息历史记录
• 🗄️ 本地SQLite存储 --所有数据都保留在您的机器上
• 🤖 MCP兼容 --适用于Claude Desktop和其他MCP客户端

🚀 入门指南

先决条件

步骤1--克隆存储库

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

第2步——设置网桥（Next.js）

该桥使用Baileys库连接到WhatsApp，并公开本地REST API。

cd bridge
npm install
npm run dev

这座桥将从 http://localhost:3000.

第一次运行时，它将创建一个 data/ 文件夹包含：

• data/auth/ --WhatsApp会话凭据
• data/whatsapp.db --包含所有消息、聊天和联系人的SQLite数据库

注： 这 data/ 文件夹被忽略。永远不要提交它——它包含你的会话密钥。

步骤3--连接WhatsApp（扫描二维码）

1. 打开 http://localhost:3000 在浏览器中
2. 点击 连接
3. 使用WhatsApp移动应用程序扫描二维码：
   • 打开WhatsApp→ 设置→ 链接设备→ 链接设备
4. 等待同步完成（第一次同步可能需要一分钟，具体取决于您的聊天记录）

连接后，状态将显示 连接 消息历史记录将开始同步到本地数据库。

步骤4——设置MCP服务器（Python）

服务器将WhatsApp功能作为MCP工具公开，Claude（或任何MCP客户端）都可以调用。

cd ../server

创建一个 .env 文件：

WHATSAPP_BRIDGE_URL=http://localhost:3000

安装依赖项并使用运行 uv:

uv sync
uv run main.py

MCP服务器将启动 http://localhost:8001.

步骤5--连接到克劳德桌面

将以下内容添加到您的Claude Desktop MCP配置文件中：

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

{
  "mcpServers": {
    "whatsapp": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/whatsapp-mcp/server",
        "main.py"
      ],
      "env": {
        "WHATSAPP_BRIDGE_URL": "http://localhost:3000"
      }
    }
  }
}

替换 /absolute/path/to/whatsapp-mcp/server 使用机器上的实际路径。

重新启动克劳德桌面。您现在应该可以在Claude中看到可用的WhatsApp工具。

🛠️ 可用的MCP工具

🌐 桥接REST API端点

网桥公开了以下端点（MCP服务器内部使用）：

⚙️ 配置

桥梁(bridge/.env.local)

# Optional: Set to 'development' to enable verbose Baileys logs
NODE_ENV=production

服务器(server/.env)

WHATSAPP_BRIDGE_URL=http://localhost:3000

🗄️ 数据库

所有数据都存储在本地 bridge/data/whatsapp.db （SQLite）。架构是由自动创建的 database.ts 首次运行时，包括：

• 消息 --包含内容、类型、发件人、时间戳的完整消息历史记录
• 聊天 --所有包含未读计数和最后一条消息时间的对话
• 联系人 --联系人JID、姓名和电话号码
• 同步状态 --跟踪上次成功的历史同步

🔒 隐私和安全

• 所有数据都已存储 本地在您的计算机上 --不会向任何外部服务器发送任何内容
• WhatsApp会话凭据存储在 bridge/data/auth/ --保护此文件夹的安全
• 网桥和MCP服务器仅通过以下方式通信 localhost
• 要完全删除会话，请运行注销或删除 bridge/data/ 文件夹

🐛 故障排除

二维码未出现

• 确保网桥在端口3000上运行
• 尝试刷新浏览器，然后再次单击“连接”

会话已过期/已注销

• 重新扫描二维码——旧的 data/auth/ 注销时自动清除文件夹

邮件未同步

• 等待初始同步完成（检查状态指示器）
• 大型帐户首次连接可能需要2-5分钟

克劳德看不到WhatsApp工具

• 验证中的绝对路径 claude_desktop_config.json
• 确保 uv 已安装并可在PATH中访问
• 配置更改后重新启动Claude Desktop

端口冲突

• 网桥默认值： 3000 --更改为 PORT=3001 npm run dev
• 服务器默认值： 8001 --更改端口 main.py 并更新您的 .env

🤝 贡献

欢迎投稿！请先打开一个问题，讨论您想更改的内容。

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/your-feature)
3. 提交您的更改(git commit -m 'Add your feature')
4. 推到分支(git push origin feature/your-feature)
5. 打开拉取请求

🙏 致谢

• 百利甜酒 -WhatsApp Web API库
• FastMCP --Python MCP框架
• 模型上下文协议 --通过Anthropic

⚠️ 免责声明： 此项目使用非官方的WhatsApp API（Baileys）。负责任地使用并遵守WhatsApp的服务条款。作者不对任何帐户禁令或滥用负责。