[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"tool-lharries--whatsapp-mcp":3,"similar-lharries--whatsapp-mcp":103},{"id":4,"github_repo":5,"name":6,"description_en":7,"description_zh":8,"ai_summary_zh":8,"readme_en":9,"readme_zh":10,"quickstart_zh":11,"use_case_zh":12,"hero_image_url":13,"owner_login":14,"owner_name":15,"owner_avatar_url":16,"owner_bio":17,"owner_company":17,"owner_location":18,"owner_email":17,"owner_twitter":19,"owner_website":20,"owner_url":21,"languages":22,"stars":31,"forks":32,"last_commit_at":33,"license":34,"difficulty_score":35,"env_os":36,"env_gpu":37,"env_ram":37,"env_deps":38,"category_tags":47,"github_topics":52,"view_count":57,"oss_zip_url":17,"oss_zip_packed_at":17,"status":58,"created_at":59,"updated_at":60,"faqs":61,"releases":97},5135,"lharries\u002Fwhatsapp-mcp","whatsapp-mcp","WhatsApp MCP server","whatsapp-mcp 是一款基于模型上下文协议（MCP）的开源服务器，旨在让 AI 助手（如 Claude）安全地连接并操作你的个人 WhatsApp 账号。它解决了大语言模型无法直接访问实时通讯数据的痛点，赋予 AI 搜索历史消息、读取多媒体内容（图片、视频、音频）、管理联系人以及向个人或群组发送文本和文件的能力。\n\n这款工具特别适合开发者、AI 研究者以及希望构建个性化智能助理的极客用户。其核心技术亮点在于采用本地优先的隐私架构：通过 WhatsMeow 库直连 WhatsApp Web 多设备接口，所有聊天记录仅加密存储于本地 SQLite 数据库中。只有当你主动调用相关功能时，数据才会被发送给 AI 模型处理，从而在享受便利的同时最大限度降低隐私泄露风险。此外，它还内置了智能媒体处理能力，若系统安装 FFmpeg，可自动将普通音频转换为 WhatsApp 专用的 Opus 格式语音消息。需要注意的是，由于涉及敏感数据交互，使用时需警惕提示词注入等安全风险，建议由具备一定技术背景的用户部署和监控。","# WhatsApp MCP Server\n\nThis is a Model Context Protocol (MCP) server for WhatsApp.\n\nWith this you can search and read your personal Whatsapp messages (including images, videos, documents, and audio messages), search your contacts and send messages to either individuals or groups. You can also send media files including images, videos, documents, and audio messages.\n\nIt connects to your **personal WhatsApp account** directly via the Whatsapp web multidevice API (using the [whatsmeow](https:\u002F\u002Fgithub.com\u002Ftulir\u002Fwhatsmeow) library). All your messages are stored locally in a SQLite database and only sent to an LLM (such as Claude) when the agent accesses them through tools (which you control).\n\nHere's an example of what you can do when it's connected to Claude.\n\n![WhatsApp MCP](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flharries_whatsapp-mcp_readme_85d360848e4c.png)\n\n> To get updates on this and other projects I work on [enter your email here](https:\u002F\u002Fdocs.google.com\u002Fforms\u002Fd\u002F1rTF9wMBTN0vPfzWuQa2BjfGKdKIpTbyeKxhPMcEzgyI\u002Fpreview)\n\n> *Caution:* as with many MCP servers, the WhatsApp MCP is subject to [the lethal trifecta](https:\u002F\u002Fsimonwillison.net\u002F2025\u002FJun\u002F16\u002Fthe-lethal-trifecta\u002F). This means that project injection could lead to private data exfiltration.\n\n## Installation\n\n### Prerequisites\n\n- Go\n- Python 3.6+\n- Anthropic Claude Desktop app (or Cursor)\n- UV (Python package manager), install with `curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh | sh`\n- FFmpeg (_optional_) - Only needed for audio messages. If you want to send audio files as playable WhatsApp voice messages, they must be in `.ogg` Opus format. With FFmpeg installed, the MCP server will automatically convert non-Opus audio files. Without FFmpeg, you can still send raw audio files using the `send_file` tool.\n\n### Steps\n\n1. **Clone this repository**\n\n   ```bash\n   git clone https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp.git\n   cd whatsapp-mcp\n   ```\n\n2. **Run the WhatsApp bridge**\n\n   Navigate to the whatsapp-bridge directory and run the Go application:\n\n   ```bash\n   cd whatsapp-bridge\n   go run main.go\n   ```\n\n   The first time you run it, you will be prompted to scan a QR code. Scan the QR code with your WhatsApp mobile app to authenticate.\n\n   After approximately 20 days, you will might need to re-authenticate.\n\n3. **Connect to the MCP server**\n\n   Copy the below json with the appropriate {{PATH}} values:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"whatsapp\": {\n         \"command\": \"{{PATH_TO_UV}}\", \u002F\u002F Run `which uv` and place the output here\n         \"args\": [\n           \"--directory\",\n           \"{{PATH_TO_SRC}}\u002Fwhatsapp-mcp\u002Fwhatsapp-mcp-server\", \u002F\u002F cd into the repo, run `pwd` and enter the output here + \"\u002Fwhatsapp-mcp-server\"\n           \"run\",\n           \"main.py\"\n         ]\n       }\n     }\n   }\n   ```\n\n   For **Claude**, save this as `claude_desktop_config.json` in your Claude Desktop configuration directory at:\n\n   ```\n   ~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json\n   ```\n\n   For **Cursor**, save this as `mcp.json` in your Cursor configuration directory at:\n\n   ```\n   ~\u002F.cursor\u002Fmcp.json\n   ```\n\n4. **Restart Claude Desktop \u002F Cursor**\n\n   Open Claude Desktop and you should now see WhatsApp as an available integration.\n\n   Or restart Cursor.\n\n### Windows Compatibility\n\nIf you're running this project on Windows, be aware that `go-sqlite3` requires **CGO to be enabled** in order to compile and work properly. By default, **CGO is disabled on Windows**, so you need to explicitly enable it and have a C compiler installed.\n\n#### Steps to get it working:\n\n1. **Install a C compiler**  \n   We recommend using [MSYS2](https:\u002F\u002Fwww.msys2.org\u002F) to install a C compiler for Windows. After installing MSYS2, make sure to add the `ucrt64\\bin` folder to your `PATH`.  \n   → A step-by-step guide is available [here](https:\u002F\u002Fcode.visualstudio.com\u002Fdocs\u002Fcpp\u002Fconfig-mingw).\n\n2. **Enable CGO and run the app**\n\n   ```bash\n   cd whatsapp-bridge\n   go env -w CGO_ENABLED=1\n   go run main.go\n   ```\n\nWithout this setup, you'll likely run into errors like:\n\n> `Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.`\n\n## Architecture Overview\n\nThis application consists of two main components:\n\n1. **Go WhatsApp Bridge** (`whatsapp-bridge\u002F`): A Go application that connects to WhatsApp's web API, handles authentication via QR code, and stores message history in SQLite. It serves as the bridge between WhatsApp and the MCP server.\n\n2. **Python MCP Server** (`whatsapp-mcp-server\u002F`): A Python server implementing the Model Context Protocol (MCP), which provides standardized tools for Claude to interact with WhatsApp data and send\u002Freceive messages.\n\n### Data Storage\n\n- All message history is stored in a SQLite database within the `whatsapp-bridge\u002Fstore\u002F` directory\n- The database maintains tables for chats and messages\n- Messages are indexed for efficient searching and retrieval\n\n## Usage\n\nOnce connected, you can interact with your WhatsApp contacts through Claude, leveraging Claude's AI capabilities in your WhatsApp conversations.\n\n### MCP Tools\n\nClaude can access the following tools to interact with WhatsApp:\n\n- **search_contacts**: Search for contacts by name or phone number\n- **list_messages**: Retrieve messages with optional filters and context\n- **list_chats**: List available chats with metadata\n- **get_chat**: Get information about a specific chat\n- **get_direct_chat_by_contact**: Find a direct chat with a specific contact\n- **get_contact_chats**: List all chats involving a specific contact\n- **get_last_interaction**: Get the most recent message with a contact\n- **get_message_context**: Retrieve context around a specific message\n- **send_message**: Send a WhatsApp message to a specified phone number or group JID\n- **send_file**: Send a file (image, video, raw audio, document) to a specified recipient\n- **send_audio_message**: Send an audio file as a WhatsApp voice message (requires the file to be an .ogg opus file or ffmpeg must be installed)\n- **download_media**: Download media from a WhatsApp message and get the local file path\n\n### Media Handling Features\n\nThe MCP server supports both sending and receiving various media types:\n\n#### Media Sending\n\nYou can send various media types to your WhatsApp contacts:\n\n- **Images, Videos, Documents**: Use the `send_file` tool to share any supported media type.\n- **Voice Messages**: Use the `send_audio_message` tool to send audio files as playable WhatsApp voice messages.\n  - For optimal compatibility, audio files should be in `.ogg` Opus format.\n  - With FFmpeg installed, the system will automatically convert other audio formats (MP3, WAV, etc.) to the required format.\n  - Without FFmpeg, you can still send raw audio files using the `send_file` tool, but they won't appear as playable voice messages.\n\n#### Media Downloading\n\nBy default, just the metadata of the media is stored in the local database. The message will indicate that media was sent. To access this media you need to use the download_media tool which takes the `message_id` and `chat_jid` (which are shown when printing messages containing the meda), this downloads the media and then returns the file path which can be then opened or passed to another tool.\n\n## Technical Details\n\n1. Claude sends requests to the Python MCP server\n2. The MCP server queries the Go bridge for WhatsApp data or directly to the SQLite database\n3. The Go accesses the WhatsApp API and keeps the SQLite database up to date\n4. Data flows back through the chain to Claude\n5. When sending messages, the request flows from Claude through the MCP server to the Go bridge and to WhatsApp\n\n## Troubleshooting\n\n- If you encounter permission issues when running uv, you may need to add it to your PATH or use the full path to the executable.\n- Make sure both the Go application and the Python server are running for the integration to work properly.\n\n### Authentication Issues\n\n- **QR Code Not Displaying**: If the QR code doesn't appear, try restarting the authentication script. If issues persist, check if your terminal supports displaying QR codes.\n- **WhatsApp Already Logged In**: If your session is already active, the Go bridge will automatically reconnect without showing a QR code.\n- **Device Limit Reached**: WhatsApp limits the number of linked devices. If you reach this limit, you'll need to remove an existing device from WhatsApp on your phone (Settings > Linked Devices).\n- **No Messages Loading**: After initial authentication, it can take several minutes for your message history to load, especially if you have many chats.\n- **WhatsApp Out of Sync**: If your WhatsApp messages get out of sync with the bridge, delete both database files (`whatsapp-bridge\u002Fstore\u002Fmessages.db` and `whatsapp-bridge\u002Fstore\u002Fwhatsapp.db`) and restart the bridge to re-authenticate.\n\nFor additional Claude Desktop integration troubleshooting, see the [MCP documentation](https:\u002F\u002Fmodelcontextprotocol.io\u002Fquickstart\u002Fserver#claude-for-desktop-integration-issues). The documentation includes helpful tips for checking logs and resolving common issues.\n","# WhatsApp MCP 服务器\n\n这是一个用于 WhatsApp 的模型上下文协议 (MCP) 服务器。\n\n通过它，你可以搜索和阅读自己的 WhatsApp 消息（包括图片、视频、文档和语音消息），搜索联系人，并向个人或群组发送消息。你还可以发送媒体文件，包括图片、视频、文档和语音消息。\n\n它通过 WhatsApp Web 多设备 API 直接连接到你的 **个人 WhatsApp 账号**（使用 [whatsmeow](https:\u002F\u002Fgithub.com\u002Ftulir\u002Fwhatsmeow) 库）。所有消息都会本地存储在 SQLite 数据库中，只有当代理通过工具访问它们时（由你控制）才会被发送到 LLM（例如 Claude）。\n\n以下是连接到 Claude 后可以实现的一个示例。\n\n![WhatsApp MCP](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flharries_whatsapp-mcp_readme_85d360848e4c.png)\n\n> 如需获取此项目及其他我正在开发的项目的更新，请在此处输入您的电子邮箱：[点击此处](https:\u002F\u002Fdocs.google.com\u002Fforms\u002Fd\u002F1rTF9wMBTN0vPfzWuQa2BjfGKdKIpTbyeKxhPMcEzgyI\u002Fpreview)\n\n> *注意:* 与许多 MCP 服务器一样，WhatsApp MCP 也受到 [致命三重奏](https:\u002F\u002Fsimonwillison.net\u002F2025\u002FJun\u002F16\u002Fthe-lethal-trifecta\u002F) 的影响。这意味着项目注入可能导致私人数据外泄。\n\n## 安装\n\n### 先决条件\n\n- Go\n- Python 3.6+\n- Anthropic Claude Desktop 应用程序（或 Cursor）\n- UV（Python 包管理器），可通过 `curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh | sh` 进行安装\n- FFmpeg（可选）——仅在处理语音消息时需要。如果你想将音频文件作为可播放的 WhatsApp 语音消息发送，它们必须是 `.ogg` Opus 格式。如果已安装 FFmpeg，MCP 服务器会自动将非 Opus 格式的音频文件转换为 Opus 格式。如果没有 FFmpeg，你仍然可以使用 `send_file` 工具发送原始音频文件。\n\n### 步骤\n\n1. **克隆此仓库**\n\n   ```bash\n   git clone https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp.git\n   cd whatsapp-mcp\n   ```\n\n2. **运行 WhatsApp 桥接程序**\n\n   导航到 `whatsapp-bridge` 目录并运行 Go 应用程序：\n\n   ```bash\n   cd whatsapp-bridge\n   go run main.go\n   ```\n\n   第一次运行时，系统会提示你扫描一个二维码。请使用你的 WhatsApp 手机应用扫描该二维码以完成身份验证。\n\n   大约 20 天后，你可能需要重新进行身份验证。\n\n3. **连接到 MCP 服务器**\n\n   复制以下 JSON 文件，并将其中的 {{PATH}} 替换为正确的路径：\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"whatsapp\": {\n         \"command\": \"{{PATH_TO_UV}}\", \u002F\u002F 运行 `which uv` 并将输出结果填入此处\n         \"args\": [\n           \"--directory\",\n           \"{{PATH_TO_SRC}}\u002Fwhatsapp-mcp\u002Fwhatsapp-mcp-server\", \u002F\u002F 进入仓库目录，运行 `pwd` 并将输出结果加上 `\u002Fwhatsapp-mcp-server` 填入此处\n           \"run\",\n           \"main.py\"\n         ]\n       }\n     }\n   }\n   ```\n\n   对于 **Claude**，将其保存为 `claude_desktop_config.json`，放置于 Claude Desktop 的配置目录中：\n\n   ```\n   ~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json\n   ```\n\n   对于 **Cursor**，将其保存为 `mcp.json`，放置于 Cursor 的配置目录中：\n\n   ```\n   ~\u002F.cursor\u002Fmcp.json\n   ```\n\n4. **重启 Claude Desktop \u002F Cursor**\n\n   打开 Claude Desktop，你应该会看到 WhatsApp 已作为可用集成出现。\n\n   或者重启 Cursor。\n\n### Windows 兼容性\n\n如果你在 Windows 上运行该项目，请注意，`go-sqlite3` 需要 **启用 CGO** 才能正确编译和运行。默认情况下，**Windows 上的 CGO 是禁用的**，因此你需要显式地启用它，并安装 C 编译器。\n\n#### 使其实现的步骤：\n\n1. **安装 C 编译器**  \n   我们建议使用 [MSYS2](https:\u002F\u002Fwww.msys2.org\u002F) 来为 Windows 安装 C 编译器。安装 MSYS2 后，确保将 `ucrt64\\bin` 文件夹添加到你的 `PATH` 中。  \n   → 详细指南请参阅 [这里](https:\u002F\u002Fcode.visualstudio.com\u002Fdocs\u002Fcpp\u002Fconfig-mingw)。\n\n2. **启用 CGO 并运行应用程序**\n\n   ```bash\n   cd whatsapp-bridge\n   go env -w CGO_ENABLED=1\n   go run main.go\n   ```\n\n如果不进行上述设置，你很可能会遇到类似以下错误：\n\n> `Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.`\n\n## 架构概述\n\n本应用由两个主要组件组成：\n\n1. **Go WhatsApp 桥接程序** (`whatsapp-bridge\u002F`)：一个 Go 应用程序，用于连接 WhatsApp 的 Web API，通过二维码处理身份验证，并将消息历史存储在 SQLite 数据库中。它是 WhatsApp 和 MCP 服务器之间的桥梁。\n\n2. **Python MCP 服务器** (`whatsapp-mcp-server\u002F`)：一个 Python 服务器，实现了模型上下文协议 (MCP)，为 Claude 提供了与 WhatsApp 数据交互以及收发消息的标准工具。\n\n### 数据存储\n\n- 所有消息历史都存储在 `whatsapp-bridge\u002Fstore\u002F` 目录下的 SQLite 数据库中。\n- 数据库维护着聊天和消息表。\n- 消息被索引，以便高效地进行搜索和检索。\n\n## 使用方法\n\n连接完成后，你可以通过 Claude 与你的 WhatsApp 联系人互动，利用 Claude 的 AI 功能来辅助你的 WhatsApp 对话。\n\n### MCP 工具\n\nClaude 可以使用以下工具与 WhatsApp 交互：\n\n- **search_contacts**: 按姓名或电话号码搜索联系人。\n- **list_messages**: 获取消息，可选择性地添加筛选条件和上下文。\n- **list_chats**: 列出可用的聊天记录及其元数据。\n- **get_chat**: 获取特定聊天的信息。\n- **get_direct_chat_by_contact**: 查找与特定联系人的直接聊天。\n- **get_contact_chats**: 列出涉及特定联系人的所有聊天。\n- **get_last_interaction**: 获取与联系人的最近一条消息。\n- **get_message_context**: 检索特定消息周围的上下文。\n- **send_message**: 向指定的电话号码或群组 JID 发送 WhatsApp 消息。\n- **send_file**: 向指定收件人发送文件（图片、视频、原始音频、文档）。\n- **send_audio_message**: 将音频文件作为 WhatsApp 语音消息发送（要求文件为 .ogg opus 格式，或已安装 FFmpeg）。\n- **download_media**: 下载 WhatsApp 消息中的媒体，并获取本地文件路径。\n\n### 媒体处理功能\n\nMCP 服务器支持发送和接收多种媒体类型：\n\n#### 发送媒体\n\n您可以向 WhatsApp 联系人发送各种媒体类型：\n\n- **图片、视频、文档**：使用 `send_file` 工具即可分享任何受支持的媒体类型。\n- **语音消息**：使用 `send_audio_message` 工具可将音频文件作为可播放的 WhatsApp 语音消息发送。\n  - 为获得最佳兼容性，音频文件应采用 `.ogg` Opus 格式。\n  - 如果已安装 FFmpeg，系统会自动将其他音频格式（如 MP3、WAV 等）转换为所需格式。\n  - 若未安装 FFmpeg，您仍可使用 `send_file` 工具发送原始音频文件，但这些文件不会以可播放的语音消息形式显示。\n\n#### 下载媒体\n\n默认情况下，本地数据库仅存储媒体的元数据。消息中会提示已发送媒体。要访问该媒体，您需要使用 `download_media` 工具，传入 `message_id` 和 `chat_jid`（在打印包含媒体的消息时会显示）。此工具会下载媒体，并返回文件路径，随后您可以打开该文件或将其传递给其他工具。\n\n## 技术细节\n\n1. Claude 向 Python MCP 服务器发送请求。\n2. MCP 服务器查询 Go 桥接程序以获取 WhatsApp 数据，或直接访问 SQLite 数据库。\n3. Go 桥接程序访问 WhatsApp API，并保持 SQLite 数据库的最新状态。\n4. 数据沿链条反向回传至 Claude。\n5. 发送消息时，请求从 Claude 经由 MCP 服务器传递至 Go 桥接程序，最终发送到 WhatsApp。\n\n## 故障排除\n\n- 如果运行 uv 时遇到权限问题，可能需要将其添加到 PATH 环境变量中，或使用可执行文件的完整路径。\n- 请确保 Go 应用程序和 Python 服务器均处于运行状态，以便集成正常工作。\n\n### 认证问题\n\n- **二维码未显示**：若二维码未出现，请尝试重启认证脚本。如果问题仍然存在，请检查您的终端是否支持显示二维码。\n- **WhatsApp 已登录**：如果您的会话已处于活动状态，Go 桥接程序将自动重新连接，而不会显示二维码。\n- **设备数量已达上限**：WhatsApp 对可关联的设备数量有限制。若达到上限，您需要在手机端的 WhatsApp 设置中移除一台现有设备（设置 > 已链接的设备）。\n- **无法加载消息**：首次认证后，消息历史可能需要数分钟才能加载完毕，尤其是在聊天记录较多的情况下。\n- **WhatsApp 与桥接程序不同步**：若 WhatsApp 消息与桥接程序不同步，请删除两个数据库文件（`whatsapp-bridge\u002Fstore\u002Fmessages.db` 和 `whatsapp-bridge\u002Fstore\u002Fwhatsapp.db`），然后重启桥接程序以重新进行认证。\n\n有关 Claude Desktop 集成的更多故障排除信息，请参阅 [MCP 文档](https:\u002F\u002Fmodelcontextprotocol.io\u002Fquickstart\u002Fserver#claude-for-desktop-integration-issues)。该文档提供了查看日志和解决常见问题的实用建议。","# WhatsApp MCP 快速上手指南\n\nWhatsApp MCP 是一个基于 Model Context Protocol (MCP) 的服务器，允许 AI 助手（如 Claude 或 Cursor）直接读取和发送你的个人 WhatsApp 消息、搜索联系人以及处理多媒体文件。所有数据存储在本地 SQLite 数据库中，确保隐私可控。\n\n## 环境准备\n\n在开始之前，请确保你的系统满足以下要求：\n\n*   **操作系统**: macOS, Linux 或 Windows (Windows 需额外配置，见下文说明)。\n*   **Go 语言环境**: 用于运行 WhatsApp 桥接服务。\n*   **Python 3.6+**: 用于运行 MCP 服务器。\n*   **UV 包管理器**: Python 依赖管理工具。\n    *   安装命令：`curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh | sh`\n    *   *国内加速提示*：如果上述脚本下载缓慢，可尝试手动下载二进制文件或使用国内镜像源配置 pip\u002Fuv。\n*   **FFmpeg (可选)**: 仅当你需要发送可播放的 WhatsApp 语音消息（.ogg Opus 格式）时需要。若未安装，仍可发送原始音频文件。\n*   **客户端**: Anthropic Claude Desktop 应用 或 Cursor 编辑器。\n\n> **注意 (Windows 用户)**:\n> Windows 默认禁用 CGO，而 `go-sqlite3` 需要它。你需要：\n> 1. 安装 C 编译器（推荐 [MSYS2](https:\u002F\u002Fwww.msys2.org\u002F) 并添加 `ucrt64\\bin` 到 PATH）。\n> 2. 在运行桥接服务前执行：`go env -w CGO_ENABLED=1`。\n\n## 安装步骤\n\n### 1. 克隆项目仓库\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp.git\ncd whatsapp-mcp\n```\n\n### 2. 运行 WhatsApp 桥接服务 (Go)\n\n进入桥接目录并启动服务。首次运行时会生成二维码，请使用手机 WhatsApp 扫描以完成认证。\n\n```bash\ncd whatsapp-bridge\ngo run main.go\n```\n\n*认证后，消息历史将同步至本地 `whatsapp-bridge\u002Fstore\u002F` 目录下的 SQLite 数据库。会话有效期约为 20 天，过期需重新扫码。*\n\n### 3. 配置 MCP 服务器\n\n获取 `uv` 和项目源码的绝对路径：\n*   运行 `which uv` 获取 UV 路径。\n*   在项目根目录运行 `pwd`，并在结果后追加 `\u002Fwhatsapp-mcp-server` 获取服务器路径。\n\n根据你的客户端，创建或编辑配置文件：\n\n#### 选项 A: Claude Desktop\n编辑文件 `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json` (macOS) 或对应 Windows 路径：\n\n```json\n{\n  \"mcpServers\": {\n    \"whatsapp\": {\n      \"command\": \"{{PATH_TO_UV}}\", \n      \"args\": [\n        \"--directory\",\n        \"{{PATH_TO_SRC}}\u002Fwhatsapp-mcp\u002Fwhatsapp-mcp-server\",\n        \"run\",\n        \"main.py\"\n      ]\n    }\n  }\n}\n```\n*(请将 `{{PATH_TO_UV}}` 和 `{{PATH_TO_SRC}}` 替换为实际路径)*\n\n#### 选项 B: Cursor\n编辑文件 `~\u002F.cursor\u002Fmcp.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"whatsapp\": {\n      \"command\": \"{{PATH_TO_UV}}\",\n      \"args\": [\n        \"--directory\",\n        \"{{PATH_TO_SRC}}\u002Fwhatsapp-mcp\u002Fwhatsapp-mcp-server\",\n        \"run\",\n        \"main.py\"\n      ]\n    }\n  }\n}\n```\n\n### 4. 重启客户端\n\n完全关闭并重新启动 Claude Desktop 或 Cursor。连接成功后，你将看到 WhatsApp 集成已就绪。\n\n## 基本使用\n\n配置完成后，你可以在聊天窗口中直接让 AI 操作 WhatsApp。以下是几个最简单的使用示例：\n\n**1. 搜索联系人**\n> \"帮我搜索名字叫 'Alice' 的联系人。\"\n> *(底层调用 `search_contacts` 工具)*\n\n**2. 查看最近消息**\n> \"列出我和 'Alice' 最近的 5 条消息。\"\n> *(底层调用 `list_messages` 或 `get_last_interaction` 工具)*\n\n**3. 发送文本消息**\n> \"给 'Alice' 发一条消息：'今晚八点开会，请准时参加。'\"\n> *(底层调用 `send_message` 工具)*\n\n**4. 发送图片**\n> \"把桌面上的 `report.png` 发送给 '项目组' 群组。\"\n> *(底层调用 `send_file` 工具)*\n\n**5. 下载媒体文件**\n> \"下载刚才那条消息里的视频文件到本地。\"\n> *(底层调用 `download_media` 工具，返回本地文件路径)*\n\n通过以上工具，你可以充分利用 AI 的能力来管理和交互你的 WhatsApp 对话。","一位远程团队的项目经理需要快速从分散的 WhatsApp 群聊和私聊中，提取上周关于“服务器故障”的讨论细节、相关截图及负责人联系方式，以撰写事故复盘报告。\n\n### 没有 whatsapp-mcp 时\n- **人工检索效率极低**：需要在手机或桌面端逐个打开数十个会话，手动滚动屏幕查找关键词，耗时数小时且容易遗漏重要信息。\n- **多媒体内容难以整合**：找到的故障截图和语音留言散落在不同对话中，必须手动下载、重命名并整理到文档，流程繁琐易出错。\n- **上下文关联断裂**：难以快速理清事件的时间线和涉及人员，往往需要反复切换窗口对比消息，导致报告逻辑不连贯。\n- **即时响应能力差**：在撰写报告过程中若需向特定成员核实细节，必须中断写作去查找联系人并发送询问消息，打断心流。\n\n### 使用 whatsapp-mcp 后\n- **自然语言一键搜索**：直接向连接的 AI 助手（如 Claude）提问“上周关于服务器故障的所有消息”，whatsapp-mcp 即刻检索本地数据库并汇总所有相关文本。\n- **多媒体自动提取**：AI 能直接读取并展示相关的故障截图和文档，甚至将语音消息转为文字摘要，无需手动下载即可嵌入报告。\n- **智能脉络梳理**：whatsapp-mcp 协助 AI 按时间线重组消息，自动识别关键决策点和责任人，生成结构清晰的事故经过草稿。\n- **闭环协作执行**：在确认报告细节时，可直接指令 AI 通过 whatsapp-mcp 向特定群组或个人发送核实消息或补充文件，全程无需切换应用。\n\nwhatsapp-mcp 将原本割裂、手动的即时通讯数据转化为可被 AI 直接理解和操作的上下文，把数小时的信息搜集工作压缩至分钟级。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Flharries_whatsapp-mcp_85d36084.png","lharries","Luke Harries","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Flharries_e6457c50.jpg",null,"London","lukeharries_","http:\u002F\u002Fharries.co\u002F","https:\u002F\u002Fgithub.com\u002Flharries",[23,27],{"name":24,"color":25,"percentage":26},"Go","#00ADD8",51.2,{"name":28,"color":29,"percentage":30},"Python","#3572A5",48.8,5492,971,"2026-04-07T09:03:09","MIT",4,"Linux, macOS, Windows","未说明",{"notes":39,"python":40,"dependencies":41},"1. Windows 用户必须安装 C 编译器（推荐 MSYS2）并显式启用 CGO (CGO_ENABLED=1) 才能编译 go-sqlite3。\n2. 需要预先安装 Anthropic Claude Desktop 或 Cursor 编辑器以运行 MCP 服务。\n3. 首次运行 Go 桥接程序时需使用手机 WhatsApp 扫描二维码进行身份验证。\n4. FFmpeg 为可选依赖，若需将普通音频文件自动转换为 WhatsApp 可播放的语音消息（.ogg Opus 格式）则必须安装；否则仅能发送原始音频文件。","3.6+",[42,43,44,45,46],"Go (语言环境)","UV (Python 包管理器)","whatsmeow (Go 库，用于 WhatsApp Web API)","go-sqlite3 (Go 库)","FFmpeg (可选，用于音频转换)",[48,49,50,51],"开发框架","Agent","插件","图像",[53,54,55,56],"ai","mcp","whatsapp","whatsapp-api",2,"ready","2026-03-27T02:49:30.150509","2026-04-08T01:10:08.290602",[62,67,72,77,82,87,92],{"id":63,"question_zh":64,"answer_zh":65,"source_url":66},23301,"如何在 Windows 上运行此工具？","Windows 用户可以使用 Conda 设置虚拟环境，并在其中安装 Go、Python 和 UV。如果遇到具体问题，可以参考社区提供的视频教程（https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=GjrN5ne-t4I）或查看相关的 Pull Request（PR #11）以获取详细的解决步骤。该工具并非专为 Mac\u002FLinux 设计，但可能需要额外的配置步骤。","https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fissues\u002F4",{"id":68,"question_zh":69,"answer_zh":70,"source_url":71},23302,"为什么发送消息时会报错 'unsupported API version' 或 HTTP 500？","这通常是由于端口冲突引起的。请检查您的 Docker 容器或其他服务是否占用了 MCP 服务器所需的端口。确保没有其他进程在同一个端口上运行，重启相关服务后通常可以解决问题。","https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fissues\u002F120",{"id":73,"question_zh":74,"answer_zh":75,"source_url":76},23303,"遇到 'Client outdated' 或 'Timeout waiting for QR code scan' 错误怎么办？","此错误表明 WhatsApp 客户端版本过旧或连接超时。请参考 Issue #94 中的讨论线程获取最新修复方案。通常需要更新底层的 WhatsApp Web 客户端库或重新扫描 QR 码以建立新会话。","https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fissues\u002F99",{"id":78,"question_zh":79,"answer_zh":80,"source_url":81},23304,"出现 'HTTPConnectionPool... Connection refused' 错误如何解决？","该错误表示无法连接到本地服务器（localhost:8080）。请确保后端服务（如 go script 或桥接服务）正在后台运行。如果服务未启动，API 请求将被拒绝。检查服务日志确认其是否成功启动并监听正确端口。","https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fissues\u002F13",{"id":83,"question_zh":84,"answer_zh":85,"source_url":86},23305,"该工具支持 WhatsApp 群组消息吗？","是的，最新版本已实现了对 WhatsApp 群组的支持。请下载并更新到最新版本即可正常使用群组消息功能。","https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fissues\u002F5",{"id":88,"question_zh":89,"answer_zh":90,"source_url":91},23306,"在 Cursor 编辑器中配置 MCP 后无法获得响应怎么办？","首先确保服务器脚本（如 main.go）已在后台持续运行，而不仅仅是一次性执行。如果问题依旧，可能是配置路径或端口问题，建议参考 Windows 安装教程视频（https:\u002F\u002Fyoutu.be\u002FGjrN5ne-t4I）核对配置步骤，并检查是否存在与其他 Issue（如 Issue #8）类似的已知问题。","https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fissues\u002F7",{"id":93,"question_zh":94,"answer_zh":95,"source_url":96},23307,"使用此工具是否存在安全风险？","是的，存在潜在风险。该工具将消息存储在本地 SQLite 数据库中，如果在同一台机器上运行不受信任的代码或 MCP 服务器，可能会导致消息泄露。开发者需注意，此工具打破了 WhatsApp 端到端加密的保护环境。建议仅在可信环境中运行，并了解相关的 MCP 安全指南（如 OWASP MCP Security Cheat Sheet）。","https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fissues\u002F42",[98],{"id":99,"version":100,"summary_zh":101,"released_at":102},138765,"v0.0.1","v0.0.1 现在包括对群聊的更好支持；发送和接收包括音频、视频和图片在内的媒体文件；以及更完善的 Windows 指南。\n\n请按照自述文件中的说明开始使用。\n\n## 变更内容\n* @lharries 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F6 中增加了对群聊的支持\n* 文档：@eltociear 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F12 中更新了 README.md\n* 文档：@aastroza 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F11 中向 README 添加了 Windows 兼容性说明\n* @alain-sv 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F22 中更新了 README.md\n* @lharries 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F30 中改进了日期处理\n* 功能：@lharries 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F31 中实现了发送文件和音频消息的功能\n* 修复：@cs4alhaider 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F32 中修正了 README.md 中的拼写错误\n* 功能：@lharries 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F34 中实现了对群聊中传入媒体（图片、音频、视频、文档）的处理，并显示发消息者的姓名\n\n## 新贡献者\n* @lharries 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F6 中做出了首次贡献\n* @eltociear 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F12 中做出了首次贡献\n* @aastroza 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F11 中做出了首次贡献\n* @alain-sv 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F22 中做出了首次贡献\n* @cs4alhaider 在 https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fpull\u002F32 中做出了首次贡献\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Flharries\u002Fwhatsapp-mcp\u002Fcommits\u002F0.0.1","2025-04-06T16:56:27",[104,114,122,131,139,147],{"id":105,"name":106,"github_repo":107,"description_zh":108,"stars":109,"difficulty_score":110,"last_commit_at":111,"category_tags":112,"status":58},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[49,48,51,113],"数据工具",{"id":115,"name":116,"github_repo":117,"description_zh":118,"stars":119,"difficulty_score":110,"last_commit_at":120,"category_tags":121,"status":58},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[48,51,49],{"id":123,"name":124,"github_repo":125,"description_zh":126,"stars":127,"difficulty_score":57,"last_commit_at":128,"category_tags":129,"status":58},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",143909,"2026-04-07T11:33:18",[48,49,130],"语言模型",{"id":132,"name":133,"github_repo":134,"description_zh":135,"stars":136,"difficulty_score":57,"last_commit_at":137,"category_tags":138,"status":58},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[48,51,49],{"id":140,"name":141,"github_repo":142,"description_zh":143,"stars":144,"difficulty_score":57,"last_commit_at":145,"category_tags":146,"status":58},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[50,48],{"id":148,"name":149,"github_repo":150,"description_zh":151,"stars":152,"difficulty_score":110,"last_commit_at":153,"category_tags":154,"status":58},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[130,51,49,48]]