WhatsApp MCP服务器（Types/Baileys）
](https://smithery.ai/server/@jlucaso1/whatsapp-mcp-ts)
这是WhatsApp的模型上下文协议（MCP）服务器，使用TypeScript构建，并使用 @whiskeysockets/baileys 图书馆。
它允许您将个人WhatsApp帐户连接到AI代理（如Anthropic Claude通过其桌面应用程序或Cursor），使其能够：
- 搜索您的个人WhatsApp消息。
- 搜索您的联系人（个人，而不是组）。
- 列出您最近的聊天记录。
- 检索特定聊天的消息历史记录。
- 向个人或团体发送消息。
它直接连接到您的 个人WhatsApp帐户 使用WhatsApp Web多设备API。您的所有消息和身份验证详细信息都已存储 本地 在SQLite数据库中(./data/)以及身份验证缓存(./auth_info/).只有当连接的AI代理明确使用提供的MCP工具（您通过代理的接口控制）时，数据才会发送到它。
*（可选：考虑添加类似于此处参考示例的屏幕截图或GIF）*
示例
用户： 在whatsapp中向“Meu amo”发送一条whatsapp消息，说“Te amo”
______________________________________________________________________
助理： 好的，我需要先找到联系人。 *使用工具： whatsapp.search_contacts*
{
"query": "Meu amor"
}______________________________________________________________________
工具结果：
[
{
"jid": "5599xxxxxx@s.whatsapp.net",
"name": "Meu Amor"
}
]______________________________________________________________________
助理： 找到了联系人。现在发送消息。 *使用工具： whatsapp.send_message*
{
"recipient": "5599xxxxxx@s.whatsapp.net",
"message": "Te amo"
}______________________________________________________________________
工具结果：
Message sent successfully to 5599xxxxxx@s.whatsapp.net (ID: XXXXXXXXXXX).关键功能（MCP工具）
服务器向连接的AI代理公开以下工具：
search_contacts：按姓名或电话号码部分（JID）搜索联系人。list_messages：检索特定聊天的消息历史记录，并进行分页。list_chats：列出您的聊天记录，可按活动或名称排序，可过滤，分页，可选择包括最后一条消息的详细信息。get_chat：获取特定聊天的详细信息。get_message_context：检索在特定消息ID前后立即发送的消息以获取上下文。send_message：向指定的收件人JID（用户或组）发送短信。
安装
通过Smithery安装
通过以下方式自动安装克劳德桌面版WhatsApp MCP服务器 史密瑟里:
npx -y @smithery/cli install @jlucaso1/whatsapp-mcp-ts --client claude先决条件
- Node.js： 版本23.10.0或更高版本（如中所述
package.json).您可以通过以下方式检查您的版本node -v.（具有初始typescript和sqlite内置支持） - npm （或yarn/pnpm）：通常随Node.js一起提供。
- AI客户端： Anthropic Claude Desktop应用程序、Cursor、Cline或Roo Code（或其他兼容MCP的客户端）。
步骤
- 克隆此存储库：
git clone whatsapp-mcp-ts
cd whatsapp-mcp-ts- 安装依赖项：
npm install
# or yarn install / pnpm install- 首次运行服务器：
使用 node 直接运行主脚本。
node src/main.ts- 第一次运行它时，它可能会使用以下命令生成一个二维码链接 quickchart.io 并尝试在默认浏览器中打开它。 - 使用您的WhatsApp移动应用程序扫描此二维码（设置>链接设备>链接设备）。 - 身份验证凭据将保存在本地 auth_info/ 目录（git忽略了这一点）。 - 消息将开始同步并存储在 ./data/whatsapp.db。这可能需要一些时间，具体取决于您的历史记录大小。检查 wa-logs.txt 以及用于进度的控制台输出。 - 保持此终端窗口运行。同步后，您可以关闭。
AI客户端配置
你需要告诉你的AI客户端如何启动这个MCP服务器。
- 准备配置JSON：
复制以下JSON结构。你需要更换 {{PATH_TO_REPO}} 随着 绝对路径 转到克隆此存储库的目录。
{
"mcpServers": {
"whatsapp": {
"command": "node",
"args": [
"{{PATH_TO_REPO}}/src/main.ts"
],
"timeout": 15, // Optional: Adjust startup timeout if needed
"disabled": false
}
}
}- 获取绝对路径： 导航到 whatsapp-mcp-ts 在终端中打开目录并运行 pwd。使用此输出 {{PATH_TO_REPO}}.
- 保存配置文件：
- 对于 克劳德桌面： 将JSON另存为 claude_desktop_config.json 在其配置目录中： - macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json （可能的路径，如果需要，请验证） - Linux： ~/.config/Claude/claude_desktop_config.json （可能的路径，如果需要，请验证） - 对于 光标： 将JSON另存为 mcp.json 在其配置目录中： - ~/.cursor/mcp.json
- 重新启动克劳德桌面/光标：
关闭并重新打开AI客户端。它现在应该可以检测到“whatsapp”MCP服务器，并允许您使用其工具。
用法
服务器运行后（通过手动方式 node src/main.ts 或者由AI客户端通过配置文件启动）并连接到您的AI客户端，您可以通过代理的聊天界面与您的WhatsApp数据进行交互。让它搜索联系人、列出最近的聊天记录、阅读消息或发送消息。
架构概述
此应用程序是一个Node.js进程，它：
- 用途
@whiskeysockets/baileys连接到WhatsApp Web API，处理身份验证和实时事件。 - 将WhatsApp聊天记录和消息本地存储在SQLite数据库中(
./data/whatsapp.db)使用node:sqlite. - 使用以下命令运行MCP服务器
@modelcontextprotocol/sdk它通过标准输入/输出（stdio）监听来自AI客户端的请求。 - 提供查询本地SQLite数据库或使用Baileys套接字发送消息的MCP工具。
- 用途
pino用于记录活动(wa-logs.txt对于WhatsApp事件，mcp-logs.txt用于MCP服务器活动）。
数据存储和隐私
- 身份验证： 您的WhatsApp连接凭据存储在本地
./auth_info/目录。 - 消息和聊天： 您的消息历史记录和聊天元数据存储在本地
./data/whatsapp.dbSQLite文件。 - 本地数据： 两者
auth_info/和data/包含在.gitignore以防止意外犯罪。 将这些目录视为敏感目录。 - LLM互动： 仅当AI代理主动使用所提供的MCP工具之一时（例如。，
list_messages,send_message).服务器本身不会主动将您的数据发送到其他任何地方。
技术细节
- 语言： TypeScript
- 运行时间： Node.js（>=v23.10.0）
- WhatsApp API：
@whiskeysockets/baileys - MCP-SDK：
@modelcontextprotocol/sdk - 数据库：
node:sqlite（捆绑SQLite） - 登录中：
pino - 架构验证：
zod（用于MCP工具输入）
故障排除
- 二维码问题：
- 如果二维码链接没有自动打开，请检查控制台输出 quickchart.io URL并手动打开。 - 确保您使用手机的WhatsApp应用程序及时扫描二维码。
- 身份验证失败/注销：
- 如果连接以 DisconnectReason.loggedOut 错误，您需要重新进行身份验证。停止服务器，删除 ./auth_info/ 目录，然后重新启动服务器(node src/main.ts)获取新的二维码。
- 消息同步问题：
- 初始同步可能需要时间。检查 wa-logs.txt 为了活动。 - 如果消息似乎不同步或丢失，您可能需要完全重置。停止服务器，删除 两者 ./auth_info/ 和 ./data/ 目录，然后重新启动服务器以重新验证和同步历史记录。
- MCP连接问题（Claude/Cursor）：
- 仔细检查 command 和 args （尤其是 {{PATH_TO_REPO}})在你的 claude_desktop_config.json 或 mcp.json。确保路径绝对正确。 - 验证Node.js是否已正确安装并位于系统的PATH中。 - 检查AI客户端的日志，查看是否存在与启动MCP服务器相关的错误。 - 检查此服务器的日志(mcp-logs.txt)用于MCP相关错误。
- 发送消息时出错：
- 确保接收者JID正确（例如。， number@s.whatsapp.net 对于用户来说， groupid@g.us 团体）。 - 检查 wa-logs.txt Baileys的具体错误。
- 一般问题： 检查两者
wa-logs.txt和mcp-logs.txt查看详细的错误消息。
有关MCP集成的更多问题，请参阅 MCP官方文件.
鸣谢
- https://github.com/lharries/whatsapp-mcp执行与此代码库相同的操作，但使用go和python。
许可证
此项目根据ISC许可证获得许可（请参阅 package.json).