Skip to content
Back to search

whatsapp-mcp

WhatsApp MCP server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/lharries--whatsapp-mcp/badge.svg)](/listings/lharries--whatsapp-mcp)

HTML

<a href="/listings/lharries--whatsapp-mcp"><img src="/api/listings/lharries--whatsapp-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Prerequisites

- Go - Python 3.6+ - Anthropic Claude Desktop app (or Cursor) - UV (Python package manager), install with `curl -LsSf https://astral.sh/uv/install.sh | sh` - 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.

Steps

1. **Clone this repository**

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

2. **Run the WhatsApp bridge**

Navigate to the whatsapp-bridge directory and run the Go application:

   cd whatsapp-bridge
   go run main.go

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.

After approximately 20 days, you will might need to re-authenticate.

3. **Connect to the MCP server**

Copy the below json with the appropriate {{PATH}} values:

   {
     "mcpServers": {
       "whatsapp": {
         "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
         "args": [
           "--directory",
           "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // cd into the repo, run `pwd` and enter the output here + "/whatsapp-mcp-server"
           "run",
           "main.py"
         ]
       }
     }
   }

For **Claude**, save this as `claude_desktop_config.json` in your Claude Desktop configuration directory at:

   ~/Library/Application Support/Claude/claude_desktop_config.json

For **Cursor**, save this as `mcp.json` in your Cursor configuration directory at:

   ~/.cursor/mcp.json

4. **Restart Claude Desktop / Cursor**

Open Claude Desktop and you should now see WhatsApp as an available integration.

Or restart Cursor.

Windows Compatibility

If 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.

Steps to get it working:

1. **Install a C compiler** We recommend using [MSYS2](https://www.msys2.org/) to install a C compiler for Windows. After installing MSYS2, make sure to add the `ucrt64\bin` folder to your `PATH`. → A step-by-step guide is available [here](https://code.visualstudio.com/docs/cpp/config-mingw).

2. **Enable CGO and run the app**

   cd whatsapp-bridge
   go env -w CGO_ENABLED=1
   go run main.go

Without this setup, you'll likely run into errors like:

> `Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.`

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 183 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # WhatsApp MCP Server
  2. This is a Model Context Protocol (MCP) server for WhatsApp.
  3. With 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.
  4. It connects to your **personal WhatsApp account** directly via the Whatsapp web multidevice API (using the [whatsmeow](https://github.com/tulir/whatsmeow) 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).
  5. Here's an example of what you can do when it's connected to Claude.
  6. ![WhatsApp MCP](./example-use.png)
  7. > To get updates on this and other projects I work on [enter your email here](https://docs.google.com/forms/d/1rTF9wMBTN0vPfzWuQa2BjfGKdKIpTbyeKxhPMcEzgyI/preview)
  8. > *Caution:* as with many MCP servers, the WhatsApp MCP is subject to [the lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/). This means that project injection could lead to private data exfiltration.
  9. ## Installation
  10. ### Prerequisites
  11. - Go
  12. - Python 3.6+
  13. - Anthropic Claude Desktop app (or Cursor)
  14. - UV (Python package manager), install with `curl -LsSf https://astral.sh/uv/install.sh | sh`
  15. - 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.
  16. ### Steps
  17. 1. **Clone this repository**
  18. ```bash
  19. git clone https://github.com/lharries/whatsapp-mcp.git
  20. cd whatsapp-mcp
  21. ```
  22. 2. **Run the WhatsApp bridge**
  23. Navigate to the whatsapp-bridge directory and run the Go application:
  24. ```bash
  25. cd whatsapp-bridge
  26. go run main.go
  27. ```
  28. 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.
  29. After approximately 20 days, you will might need to re-authenticate.
  30. 3. **Connect to the MCP server**
  31. Copy the below json with the appropriate {{PATH}} values:
  32. ```json
  33. {
  34. "mcpServers": {
  35. "whatsapp": {
  36. "command": "{{PATH_TO_UV}}", // Run `which uv` and place the output here
  37. "args": [
  38. "--directory",
  39. "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // cd into the repo, run `pwd` and enter the output here + "/whatsapp-mcp-server"
  40. "run",
  41. "main.py"
  42. ]
  43. }
  44. }
  45. }
  46. ```
  47. For **Claude**, save this as `claude_desktop_config.json` in your Claude Desktop configuration directory at:
  48. ```
  49. ~/Library/Application Support/Claude/claude_desktop_config.json
  50. ```
  51. For **Cursor**, save this as `mcp.json` in your Cursor configuration directory at:
  52. ```
  53. ~/.cursor/mcp.json
  54. ```
  55. 4. **Restart Claude Desktop / Cursor**
  56. Open Claude Desktop and you should now see WhatsApp as an available integration.
  57. Or restart Cursor.
  58. ### Windows Compatibility
  59. If 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.
  60. #### Steps to get it working:
  61. 1. **Install a C compiler**
  62. We recommend using [MSYS2](https://www.msys2.org/) to install a C compiler for Windows. After installing MSYS2, make sure to add the `ucrt64\bin` folder to your `PATH`.
  63. → A step-by-step guide is available [here](https://code.visualstudio.com/docs/cpp/config-mingw).
  64. 2. **Enable CGO and run the app**
  65. ```bash
  66. cd whatsapp-bridge
  67. go env -w CGO_ENABLED=1
  68. go run main.go
  69. ```
  70. Without this setup, you'll likely run into errors like:
  71. > `Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.`
  72. ## Architecture Overview
  73. This application consists of two main components:
  74. 1. **Go WhatsApp Bridge** (`whatsapp-bridge/`): 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.
  75. 2. **Python MCP Server** (`whatsapp-mcp-server/`): A Python server implementing the Model Context Protocol (MCP), which provides standardized tools for Claude to interact with WhatsApp data and send/receive messages.
  76. ### Data Storage
  77. - All message history is stored in a SQLite database within the `whatsapp-bridge/store/` directory
  78. - The database maintains tables for chats and messages
  79. - Messages are indexed for efficient searching and retrieval
  80. ## Usage
  81. Once connected, you can interact with your WhatsApp contacts through Claude, leveraging Claude's AI capabilities in your WhatsApp conversations.
  82. ### MCP Tools
  83. Claude can access the following tools to interact with WhatsApp:
  84. - **search_contacts**: Search for contacts by name or phone number
  85. - **list_messages**: Retrieve messages with optional filters and context
  86. - **list_chats**: List available chats with metadata
  87. - **get_chat**: Get information about a specific chat
  88. - **get_direct_chat_by_contact**: Find a direct chat with a specific contact
  89. - **get_contact_chats**: List all chats involving a specific contact
  90. - **get_last_interaction**: Get the most recent message with a contact
  91. - **get_message_context**: Retrieve context around a specific message
  92. - **send_message**: Send a WhatsApp message to a specified phone number or group JID
  93. - **send_file**: Send a file (image, video, raw audio, document) to a specified recipient
  94. - **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)
  95. - **download_media**: Download media from a WhatsApp message and get the local file path
  96. ### Media Handling Features
  97. The MCP server supports both sending and receiving various media types:
  98. #### Media Sending
  99. You can send various media types to your WhatsApp contacts:
  100. - **Images, Videos, Documents**: Use the `send_file` tool to share any supported media type.
  101. - **Voice Messages**: Use the `send_audio_message` tool to send audio files as playable WhatsApp voice messages.
  102. - For optimal compatibility, audio files should be in `.ogg` Opus format.
  103. - With FFmpeg installed, the system will automatically convert other audio formats (MP3, WAV, etc.) to the required format.
  104. - Without FFmpeg, you can still send raw audio files using the `send_file` tool, but they won't appear as playable voice messages.
  105. #### Media Downloading
  106. By 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.
  107. ## Technical Details
  108. 1. Claude sends requests to the Python MCP server
  109. 2. The MCP server queries the Go bridge for WhatsApp data or directly to the SQLite database
  110. 3. The Go accesses the WhatsApp API and keeps the SQLite database up to date
  111. 4. Data flows back through the chain to Claude
  112. 5. When sending messages, the request flows from Claude through the MCP server to the Go bridge and to WhatsApp
  113. ## Troubleshooting
  114. - 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.
  115. - Make sure both the Go application and the Python server are running for the integration to work properly.
  116. ### Authentication Issues
  117. - **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.
  118. - **WhatsApp Already Logged In**: If your session is already active, the Go bridge will automatically reconnect without showing a QR code.
  119. - **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).
  120. - **No Messages Loading**: After initial authentication, it can take several minutes for your message history to load, especially if you have many chats.
  121. - **WhatsApp Out of Sync**: If your WhatsApp messages get out of sync with the bridge, delete both database files (`whatsapp-bridge/store/messages.db` and `whatsapp-bridge/store/whatsapp.db`) and restart the bridge to re-authenticate.
  122. For additional Claude Desktop integration troubleshooting, see the [MCP documentation](https://modelcontextprotocol.io/quickstart/server#claude-for-desktop-integration-issues). The documentation includes helpful tips for checking logs and resolving common issues.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.