📣 BOOK A FREE CALL  LINK

WhatsApp MCP: A Technical Deep Dive into AI-Powered WhatsApp Interaction

notion image
Chapter 1: Introduction to WhatsApp MCP
The Model Context Protocol (MCP) represents a significant advancement in the integration of Large Language Models (LLMs) with diverse applications and data sources.1 This open protocol establishes a standardized framework for how applications can provide contextual information and tools to AI models, enabling a more seamless and powerful interaction.1 Often likened to a universal adapter, such as USB-C, MCP offers a consistent method for AI models to connect with a variety of data sources and functionalities, thereby extending their capabilities beyond their initial training.2 At its core, MCP facilitates the sharing of contextual information, the exposure of specific tools that AI can utilize, and the construction of composable integrations that can be tailored to various use cases.4 The communication between the different components within the MCP framework – the LLM applications (hosts), the connectors within those applications (clients), and the services providing context and capabilities (servers) – is conducted using JSON-RPC 2.0 messages, a technical detail that ensures structured and reliable data exchange.4
WhatsApp MCP is a specific implementation of this broader MCP protocol, tailored to enable interaction with a user’s personal WhatsApp account.8 This implementation allows individuals to leverage the power of AI to search through and read their WhatsApp messages, including various forms of media, manage their contacts, and even send messages directly through an AI client.8 The underlying mechanism for this interaction involves a direct connection to the user’s personal WhatsApp account via the WhatsApp Web multi-device API.8 This technical approach is distinct from other methods of WhatsApp automation and focuses on empowering individual users with AI capabilities for their personal communication. By integrating AI in this manner, WhatsApp MCP can significantly enhance the user experience, unlocking possibilities for intelligent message analysis, efficient information retrieval, and the automation of certain communication tasks.12
The potential applications of WhatsApp MCP are diverse and offer compelling benefits. For instance, users can employ natural language queries through their AI assistant to search for specific details within their extensive WhatsApp conversation history.8 This capability transforms the way users can access and utilize information buried within past chats. Furthermore, AI can be used to summarize lengthy discussions or pinpoint key information within group conversations, leading to increased productivity and better information management.12 The automation of routine messaging tasks, such as sending reminders or updates to contacts or groups, also becomes feasible through simple AI commands.8 Beyond these direct applications, WhatsApp MCP can be integrated into more complex AI-driven workflows, where actions on WhatsApp can trigger events in other applications, or vice versa.15 Ultimately, this technology paves the way for highly personalized AI assistants that possess a deep understanding of a user’s communication patterns and can proactively offer relevant insights or support within the WhatsApp environment.13
Chapter 2: Technical Architecture and Components
The functionality of WhatsApp MCP relies on a carefully designed technical architecture comprising several key components. A crucial element is the Go WhatsApp Bridge, which serves as an intermediary, facilitating communication between the WhatsApp Web API and the MCP server.8 This separation allows for a modular design where each component handles specific responsibilities. The Go bridge establishes a direct connection to WhatsApp’s web API, utilizing the whatsmeow library.8 This library is instrumental in managing the intricacies of the WhatsApp communication protocol. The bridge is also responsible for handling the initial authentication process, which typically involves the user scanning a QR code displayed by the server using their WhatsApp mobile application.8 This ensures a secure link to the user’s WhatsApp account. Moreover, the Go WhatsApp Bridge manages the local storage of the user’s WhatsApp message history within a SQLite database.8 This local storage approach is a significant aspect concerning data privacy and user control. The entire Go WhatsApp Bridge is implemented using the Go programming language, known for its performance and ability to handle concurrent operations efficiently.8
The Model Context Protocol (MCP) server is another essential component, responsible for implementing the MCP standard.8 This server provides a standardized interface through which AI clients like Claude and Cursor can interact with the WhatsApp data managed by the Go bridge (in the case of the Python implementation) or directly with the WhatsApp Web API (in some TypeScript implementations).8 The MCP server exposes a set of standardized tools that abstract the complexities of the underlying WhatsApp API, allowing AI clients to perform actions such as sending messages, searching contacts, and retrieving conversation history.8 Notably, the MCP server has been implemented in both Python, which was the original implementation, and TypeScript, with ports created by other developers.8 The Python version typically relies on the uv Python package manager to handle its dependencies 8, while TypeScript implementations commonly use Node.js and the npm package manager.9 This availability in multiple programming languages offers users the flexibility to choose the implementation that best suits their technical background and development environment.
Several key libraries are fundamental to the operation of WhatsApp MCP. whatsmeow is a Go library that the Go WhatsApp Bridge utilizes for direct communication with the WhatsApp Web multi-device API.8 This library handles the intricate details of the WhatsApp protocol, providing features such as sending and receiving various types of messages (text and media), managing groups, and handling connection-related events.20 While powerful, whatsmeow does have certain limitations, including the absence of built-in support for sending broadcast list messages (a limitation also present in WhatsApp Web itself) and making calls.20 It is specifically designed to work with the multi-device API architecture of WhatsApp.8 Another important library is whatsapp-web.js, a JavaScript library used by some TypeScript-based WhatsApp MCP server implementations, such as the one found at 10, for integrating with WhatsApp Web. This library offers similar functionalities to whatsmeow, enabling message handling, contact management, and media processing.10 The choice between these libraries often depends on the preferred programming language and the specific requirements of the implementation.
The interaction within the WhatsApp MCP ecosystem follows a defined data flow. When an AI client, like Claude or Cursor, needs to interact with WhatsApp, it sends a request, formatted according to the MCP specification, to the MCP server.8 Upon receiving this request, the MCP server (in the Python implementation) communicates with the Go WhatsApp Bridge to fulfill the request. In some TypeScript implementations, the MCP server might directly interact with the WhatsApp Web API using a library like whatsapp-web.js.8 The Go bridge then uses the whatsmeow library to communicate with WhatsApp’s servers, sending and receiving data according to the WhatsApp protocol.8 If the request involves retrieving data, such as messages or contacts, the Go bridge might fetch this information from the locally stored SQLite database or, if necessary, make a request to the WhatsApp API.8 Once the data is retrieved, the Go bridge sends it back to the MCP server, which then formats it according to the MCP protocol and sends a response back to the initiating AI client.8 For actions involving sending messages or media, the process is reversed: the AI client sends the request to the MCP server, which forwards it to the Go bridge (or handles it directly in some TypeScript versions). The Go bridge then utilizes whatsmeow to send the message or media through the WhatsApp API to the intended recipient.8
Chapter 3: Setting Up Your WhatsApp MCP Environment
To begin using WhatsApp MCP, several software prerequisites must be installed on your system. These typically include the Go programming language, which is essential for running the WhatsApp Bridge.8 Python version 3.6 or higher is required if you intend to use the Python-based MCP server.8 You will also need either the Anthropic Claude Desktop application or Cursor, as these are the primary AI clients designed to integrate with MCP servers like WhatsApp MCP.8 For the Python implementation, it is recommended to install the UV Python package manager, which simplifies the management of Python dependencies.8 If you choose a TypeScript-based MCP server, you will need to have Node.js and its package manager, npm, installed.9 Optionally, FFmpeg is recommended if you plan to send audio files as playable WhatsApp voice messages and your audio files are not already in the .ogg Opus format. The MCP server can leverage FFmpeg to automatically convert other audio formats to the required format.8 Links to the official download pages for each of these software components should be readily available on their respective project websites. Understanding the purpose of each component is also beneficial; for example, Go is used for the bridge due to its performance characteristics, Python and TypeScript are used for the MCP server logic, UV and npm manage the necessary libraries, and FFmpeg handles media format conversions.8
The initial setup involves cloning the WhatsApp MCP repository from GitHub. For the primary implementation, the command is git clone https://github.com/lharries/whatsapp-mcp.git.8 If you are using a different fork, you would use the corresponding repository URL. After cloning, navigate into the newly created directory using the command cd whatsapp-mcp. Next, you need to run the WhatsApp bridge. Navigate to the whatsapp-bridge subdirectory using cd whatsapp-bridge.8 Then, execute the Go application with the command go run main.go.8 The first time you run this command, you will be prompted to scan a QR code displayed in your terminal using your WhatsApp mobile app (go to Settings, then Linked Devices, and select Link a Device).8 This step authenticates your WhatsApp account with the MCP server. It is important to note that you might need to repeat this authentication process approximately every 20 days by scanning a new QR code.8 The MCP server itself (whether Python or TypeScript) is typically launched by the AI client (Claude or Cursor) based on the configuration you will provide in the next step. While you might be able to run the Python server manually for testing purposes by navigating to the whatsapp-mcp-server directory and running python main.py, the standard integration relies on the AI client to initiate it. For TypeScript implementations, the command might be node dist/index.js after the project has been built.
For Windows users, there are specific instructions due to a dependency (go-sqlite3) used by the Go bridge. This dependency requires CGO to be enabled on Windows. First, it is recommended to install a C compiler using MSYS2. After installing MSYS2, ensure that you add the ucrt64\bin folder to your system’s PATH environment variable.8 The README file of the lharries/whatsapp-mcp repository often contains a link to a detailed step-by-step guide for this process. Before running the WhatsApp bridge, you need to execute the following commands in the whatsapp-bridge directory to enable CGO:
Bash
go env -w CGO_ENABLED=1
go run main.go
These commands ensure that the go-sqlite3 library functions correctly on the Windows operating system.8
To enable your AI client to communicate with the WhatsApp MCP server, you need to create a configuration file in a specific directory on your system. The exact filename and location depend on whether you are using Claude Desktop or Cursor.8 The configuration file is in JSON format and tells the AI client how to start the MCP server. Here are the basic JSON structures for both Python and TypeScript implementations:
Code Snippet Table 1 (Section 3): Configuration JSON for Claude Desktop (Python)
Key
Value
Example Value
mcpServers
An object containing definitions for MCP servers.
{ “mcpServers”: { “whatsapp”: { “command”: “/usr/local/bin/uv”, “args”: [ “–directory”, “/Users/carson/projects/whatsapp-mcp/whatsapp-mcp-server”, “run”, “main.py” ] } } }
whatsapp
The name you’ll use to refer to this MCP server in Claude.
whatsapp
command
The command to execute to start the MCP server.
“/usr/local/bin/uv” (output of which uv)
args
An array of arguments to pass to the command.
[“–directory”, “/path/to/whatsapp-mcp/whatsapp-mcp-server”, “run”, “main.py”]
Code Snippet Table 2 (Section 3): Configuration JSON for Cursor (Python)
Key
Value
Example Value
mcpServers
An object containing definitions for MCP servers.
{ “mcpServers”: { “whatsapp”: { “command”: “/opt/homebrew/bin/uv”, “args”: [ “–directory”, “/Users/carson/dev/whatsapp-mcp/whatsapp-mcp-server”, “run”, “main.py” ] } } }
whatsapp
The name you’ll use to refer to this MCP server in Cursor.
whatsapp
command
The command to execute to start the MCP server.
“/usr/local/bin/uv” (output of which uv)
args
An array of arguments to pass to the command.
[“–directory”, “/path/to/whatsapp-mcp/whatsapp-mcp-server”, “run”, “main.py”]
Code Snippet Table 3 (Section 3): Configuration JSON for Claude Desktop (TypeScript)
Key
Value
Example Value
mcpServers
An object containing definitions for MCP servers.
{ “mcpServers”: { “whatsapp”: { “command”: “node”, “args”: [ “/Users/carson/projects/whatsapp-mcp-ts/dist/index.js” ] } } }
whatsapp
The name you’ll use to refer to this MCP server in Claude.
whatsapp
command
The command to execute to start the MCP server.
“node”
args
An array of arguments to pass to the command.
[“/path/to/whatsapp-mcp-ts/dist/index.js”]
Code Snippet Table 4 (Section 3): Configuration JSON for Cursor (TypeScript)
Key
Value
Example Value
mcpServers
An object containing definitions for MCP servers.
{ “mcpServers”: { “whatsapp”: { “command”: “node”, “args”: [ “/Users/carson/dev/whatsapp-mcp-ts/dist/index.js” ] } } }
whatsapp
The name you’ll use to refer to this MCP server in Cursor.
whatsapp
command
The command to execute to start the MCP server.
“node”
args
An array of arguments to pass to the command.
[“/path/to/whatsapp-mcp-ts/dist/index.js”]
You need to replace the placeholder paths in these JSON structures with the actual paths on your system. For the Python server, {{PATH_TO_UV}} should be the output of the which uv command, and {{PATH_TO_SRC}} should be the absolute path to the root of your cloned whatsapp-mcp repository followed by /whatsapp-mcp-server. For the TypeScript server, {{PATH_TO_REPO}} should be the absolute path to the root of your cloned TypeScript repository (e.g., whatsapp-mcp-ts) followed by the path to the built server file (e.g., dist/index.js). Save the modified configuration file as claude_desktop_config.json in the Claude configuration directory (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows, ~/.config/Claude/ on Linux) or as mcp.json in the Cursor configuration directory (~/.cursor/ on macOS/Linux, %USERPROFILE%\.cursor\ on Windows).8 After saving the file, restart your Claude Desktop or Cursor application. You should now see WhatsApp as an available integration.8
Common installation issues can arise. If the QR code doesn’t appear when running the WhatsApp bridge, try restarting the go run main.go command. Ensure your terminal supports QR code display.8 If you have an active WhatsApp Web session, the bridge might reconnect automatically without showing a QR code.8 If you’ve reached WhatsApp’s device limit, remove a device from your phone’s WhatsApp settings.8 If messages don’t load after authentication, allow several minutes for synchronization.8 If messages are out of sync, delete the messages.db and whatsapp.db files in whatsapp-bridge/store/ and restart the bridge.8 For uv permission issues, add its directory to your PATH or use the full path in the configuration.8 Ensure both the Go bridge and the MCP server are running.8 Double-check the paths in your configuration file.9 For TypeScript, verify Node.js is installed and in your PATH.9 Check the logs of both the AI client and the MCP server for error messages.8
Chapter 4: Utilizing WhatsApp MCP Features
WhatsApp MCP offers a range of tools that enable your AI client to interact with your WhatsApp account in various ways.8 These tools follow the standardized Model Context Protocol, allowing for consistent communication. Common tools include search_contacts to find contacts, list_messages to retrieve messages (potentially with filters), list_chats to see recent conversations, get_chat for detailed chat information, get_direct_chat_by_contact to find a specific direct chat, get_contact_chats to list all chats with a contact, get_last_interaction to get the latest message, get_message_context for surrounding messages, send_message to send text, send_file for sending various file types, send_audio_message specifically for voice notes, and download_media to retrieve media files. Some implementations, particularly TypeScript versions, also include authentication-related tools like get_qr_code, check_auth_status, and logout.10 The precise set of tools available may vary slightly depending on the specific MCP server implementation you are using.
To send a message using your AI client (like Claude), you would typically use a prompt that calls the send_message tool. For example, you might instruct: “Use the send_message tool to send ‘Hello!’ to John Doe.” The AI client would then invoke the send_message tool provided by the WhatsApp MCP server, including the recipient’s identifier and the message content. Receiving messages is a passive process for the AI client. When someone sends you a WhatsApp message, the Go bridge (or the TypeScript server) receives it via the WhatsApp Web API and stores it locally in the SQLite database. When you ask the AI to perform a task involving your messages, it uses tools like list_messages or get_chat to retrieve the necessary information from this local storage. The strength of this system lies in the AI’s ability to understand your natural language requests and translate them into specific MCP tool calls. For instance, asking “What did I talk about with Jane last week?” might lead the AI to use search_contacts to find Jane’s contact ID and then list_messages with a date filter to get the relevant conversations.
You can manage your contacts and chats using several MCP tools. To search for a specific contact, you can use the search_contacts tool with a prompt like: “Use the search_contacts tool to find the contact named ‘Alice Smith’.” The server will search its local contact list and return the matching information. To get an overview of your recent conversations, use the list_chats tool with a prompt like: “Use the list_chats tool to show me my recent chats.” This will retrieve and display a list of your active chats, possibly including the chat name, last message timestamp, and a snippet of the last message. For more detailed information about a specific chat, you can use the get_chat tool, providing the chat’s unique ID. This might return details such as the participants in a group chat or the chat’s creation date.
WhatsApp MCP also allows for handling media files. To send an image, video, or document, you would typically use the send_file tool, providing the recipient’s identifier and the local file path. For example: “Use the send_file tool to send the image at /path/to/image.jpg to Jane Doe”.8 For sending audio as a playable voice note, use the send_audio_message tool. The audio file should ideally be in .ogg Opus format. If FFmpeg is configured, the server can convert other formats. Provide the recipient and file path: “Use the send_audio_message tool to send the audio file at /path/to/audio.mp3 to Group X”.8 Raw audio files can also be sent using send_file, but they won’t be playable voice notes.8 When you receive media, only metadata is initially stored.8 To download the actual media file, you need to use the download_media tool, providing the message_id and chat_jid of the message containing the media. These identifiers are usually available when the AI client lists or retrieves messages. For example: “Use the download_media tool with message ID ‘abc123xyz’ and chat JID ‘15551234567@s.whatsapp.net’ to download the media.” The server will then download the file and return its local path.8
Chapter 5: Data Storage, Privacy, and Security
All WhatsApp message history, including text, media metadata, and contact information, is stored locally on your computer within a SQLite database located in the whatsapp-bridge/store/ directory.8 This database contains tables for chats and messages, with messages being indexed for efficient searching and retrieval.8 When media files are received, only their metadata is stored initially; the actual content is downloaded on demand using the download_media tool.8 For advanced users who might want to manage their data directly, it is possible to use SQLite database browser tools to inspect or back up the messages.db and whatsapp.db files. However, direct modification of the database is strongly discouraged as it could lead to data corruption or unexpected behavior.
A significant advantage of using WhatsApp MCP is the privacy afforded by local data storage.11 Unlike cloud-based solutions, your message data remains on your personal computer, giving you greater control over your information. The system is designed such that this local data is only accessed by the LLM (like Claude or Cursor) when you explicitly initiate an action through the available MCP tools.8 This ensures that your conversations are not automatically shared with or analyzed by the AI without your direct command. The Model Context Protocol specification itself emphasizes the importance of user consent and control over data access and operations, encouraging developers to implement robust consent mechanisms.4
When considering security, it is important to understand that WhatsApp MCP relies on the WhatsApp Web API. While this is an official API, users should be mindful of the security considerations involved in linking their WhatsApp account to a desktop application. It is crucial to differentiate WhatsApp MCP from unofficial WhatsApp APIs or automation tools, which often pose higher security risks, including account bans and data breaches.24 WhatsApp MCP, especially when using well-maintained libraries like whatsmeow, aims to interact with the official API in a secure manner. Using unofficial APIs can lead to account restrictions or permanent bans by Meta.25 While WhatsApp MCP, by using the Web API through established libraries, attempts to mitigate this risk, it is not entirely immune to potential issues if misused or if WhatsApp changes its policies. As a general practice, users should always download WhatsApp MCP software from trusted sources like the official GitHub repositories and keep their software updated. Exercise caution when granting permissions to AI clients interacting with your WhatsApp data through MCP, ensuring you understand the tools being used and the actions being performed. While some forks might lack explicit security policies 30, the open-source nature of the primary lharries/whatsapp-mcp repository allows for community review of the code for potential vulnerabilities.
Table 5 (Section 5): Comparison of WhatsApp Automation Methods
Feature
WhatsApp Business Web
WhatsApp Business API
WhatsApp MCP
Automation Level
Basic (manual)
Advanced
AI-driven, customizable through MCP
Scalability
Limited
High
Depends on local resources
Cost
Free
Paid (per conversation)
Free (requires local setup and AI client)
Technical Skill Needed
None
Some
High (requires technical setup)
Security
Basic
Robust
Relies on WhatsApp Web API security
Official Support
Yes
Yes
Community-driven
Target User
Small businesses
Medium/Large businesses
Technically proficient individuals/researchers
Risk of Account Ban
Low (for manual use)
Low (if compliant)
Moderate (potential if misused)
Unofficial WhatsApp APIs and automation tools operate without authorization from Meta.24 These methods often involve reverse-engineering or using non-endorsed third-party libraries. Using them carries significant risks, including account bans and security vulnerabilities.24 Meta actively works against such tools. WhatsApp MCP, by using libraries like whatsmeow and whatsapp-web.js 8, offers a more transparent interaction with the official API, making it generally safer than completely undocumented or third-party automation tools. However, responsible use and awareness of potential policy changes by WhatsApp are still important.
Chapter 6: WhatsApp MCP in the Broader Context
The WhatsApp Business App is a free tool for small businesses, offering features like business profiles, quick replies, and labels.32 However, its automation capabilities are limited, making it suitable for businesses with smaller customer bases and primarily one-on-one interactions.34 It lacks API access for deeper integrations. The WhatsApp Business API, on the other hand, is a paid service for medium to large businesses, providing advanced automation, bulk notifications, integration with CRM systems, and the possibility of a verified business profile.32 It requires a more complex setup, often through a WhatsApp Business Solution Provider (BSP), and follows a conversation-based pricing model.34 In contrast, WhatsApp MCP is a community-driven project focused on personal use, enabling AI interaction with a user’s WhatsApp account via the WhatsApp Web API.32 It offers significant customization for technically skilled users but requires local setup and an AI client. It is free to use (excluding AI client costs) with community-based support.
Choosing the right WhatsApp automation solution depends on your technical skills, the scale of your needs (personal or business), the required level of automation, and your budget.32 WhatsApp MCP is best suited for technically inclined individuals or researchers interested in integrating AI with their personal WhatsApp communication who are comfortable with the setup process and community support.32 For businesses needing robust automation, scalability, and official support, the WhatsApp Business API is the recommended option, despite its cost and complexity.32 Small businesses with basic messaging needs can effectively use the free WhatsApp Business App.32 Users should carefully evaluate their specific requirements and technical comfort level before selecting a solution.
Chapter 7: Community, Resources, and Further Exploration
The primary sources for information and community support for WhatsApp MCP are the open-source GitHub repositories, notably the main repository by lharries and other forks like those by jlucaso1 and mario-andreschak.8 These repositories often include README files with setup instructions, issue trackers for bug reporting, and discussion sections for questions. Online communities such as the /r/mcp and /r/ClaudeAI subreddits provide platforms for users to share experiences, seek assistance, and discuss various aspects of WhatsApp MCP and its integration with AI clients.17 Projects like “Awesome MCP Servers” offer curated lists of MCP server implementations, including those for WhatsApp, which can be helpful for discovering alternatives and resources.1 The original author and other contributors actively participate in the community, and their activity on GitHub serves as a valuable resource.
Chapter 8: The main code
https://github.com/lharries/whatsapp-mcp
WhatsApp MCP Server
This is a Model Context Protocol (MCP) server for WhatsApp.
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.
It connects to your personal WhatsApp account directly via the Whatsapp web multidevice API (using the 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).
Here’s an example of what you can do when it’s connected to Claude.
WhatsApp MCP
To get updates on this and other projects I work on enter your email here

Installation

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
      2. git clone https://github.com/lharries/whatsapp-mcp.git
      cd whatsapp-mcp
  1. Run the WhatsApp bridge
      2. 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.
  1. Connect to the MCP server
      2. Copy the below json with the appropriate {{PATH}} values:
      {
      “mcpServers”: {
      }
      }
      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
  1. Restart Claude Desktop / Cursor
      2. 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
      2. We recommend using MSYS2 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.
  1. Enable CGO and run the app
      2. 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.

Architecture Overview

This application consists of two main components:
  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.
  1. 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.

Data Storage

  • All message history is stored in a SQLite database within the whatsapp-bridge/store/ directory
  • The database maintains tables for chats and messages
  • Messages are indexed for efficient searching and retrieval

Usage

Once connected, you can interact with your WhatsApp contacts through Claude, leveraging Claude’s AI capabilities in your WhatsApp conversations.

MCP Tools

Claude can access the following tools to interact with WhatsApp:
  • search_contacts: Search for contacts by name or phone number
  • list_messages: Retrieve messages with optional filters and context
  • list_chats: List available chats with metadata
  • get_chat: Get information about a specific chat
  • get_direct_chat_by_contact: Find a direct chat with a specific contact
  • get_contact_chats: List all chats involving a specific contact
  • get_last_interaction: Get the most recent message with a contact
  • get_message_context: Retrieve context around a specific message
  • send_message: Send a WhatsApp message to a specified phone number or group JID
  • send_file: Send a file (image, video, raw audio, document) to a specified recipient
  • 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)
  • download_media: Download media from a WhatsApp message and get the local file path

Media Handling Features

The MCP server supports both sending and receiving various media types:

Media Sending

You can send various media types to your WhatsApp contacts:
  • Images, Videos, Documents: Use the send_file tool to share any supported media type.
  • Voice Messages: Use the send_audio_message tool to send audio files as playable WhatsApp voice messages.
    • For optimal compatibility, audio files should be in .ogg Opus format.
    • With FFmpeg installed, the system will automatically convert other audio formats (MP3, WAV, etc.) to the required format.
    • Without FFmpeg, you can still send raw audio files using the send_file tool, but they won’t appear as playable voice messages.

Media Downloading

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.

Technical Details

  1. Claude sends requests to the Python MCP server
  1. The MCP server queries the Go bridge for WhatsApp data or directly to the SQLite database
  1. The Go accesses the WhatsApp API and keeps the SQLite database up to date
  1. Data flows back through the chain to Claude
  1. When sending messages, the request flows from Claude through the MCP server to the Go bridge and to WhatsApp

Troubleshooting

  • 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.
  • Make sure both the Go application and the Python server are running for the integration to work properly.

Authentication Issues

  • 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.
  • WhatsApp Already Logged In: If your session is already active, the Go bridge will automatically reconnect without showing a QR code.
  • 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).
  • No Messages Loading: After initial authentication, it can take several minutes for your message history to load, especially if you have many chats.
  • 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.
For additional Claude Desktop integration troubleshooting, see the MCP documentation. The documentation includes helpful tips for checking logs and resolving common issues.
For further exploration and implementation, the following resources are highly recommended:
As an open-source project, the future development of WhatsApp MCP relies on community contributions.1 Potential future advancements could include improved media handling capabilities, broader compatibility with more AI clients, and enhanced security features. Interested users are encouraged to contribute by reporting issues, submitting code changes, or participating in community discussions. The release notes for the primary repository indicate ongoing development and the addition of new functionalities, highlighting an active and evolving project.19
Conclusions
WhatsApp MCP provides a compelling approach for technically proficient individuals to integrate AI capabilities with their personal WhatsApp communication. By leveraging the Model Context Protocol and the WhatsApp Web multi-device API, it enables a range of functionalities, from intelligent message searching to automated communication workflows. The local data storage model offers significant privacy advantages, aligning with the growing user demand for data control. While the setup process requires technical expertise, the availability of implementations in both Python and TypeScript provides flexibility. However, users should be aware that WhatsApp MCP is a community-driven project and differs from the officially supported WhatsApp Business App and API, particularly in terms of support and guarantees. For those comfortable with the technical aspects and seeking a high degree of customization in their AI-powered WhatsApp interactions, WhatsApp MCP presents a powerful and versatile solution.

Works cited

  1. punkpeye/awesome-mcp-servers - GitHub, accessed May 11, 2025, https://github.com/punkpeye/awesome-mcp-servers
  1. Model context protocol (MCP) - OpenAI Agents SDK, accessed May 11, 2025, https://openai.github.io/openai-agents-python/mcp/
  1. Model Context Protocol (MCP) - Anthropic API, accessed May 11, 2025, https://docs.anthropic.com/en/docs/agents-and-tools/mcp
  1. Specification - Model Context Protocol, accessed May 11, 2025, https://modelcontextprotocol.io/specification/2025-03-26
  1. Model Context Protocol - Cursor, accessed May 11, 2025, https://docs.cursor.com/context/model-context-protocol
  1. Model Context Protocol (MCP) Guide: What It Is & How to Use It - Leanware, accessed May 11, 2025, https://www.leanware.co/insights/model-context-protocol-guide
  1. Model Context Protocol - GitHub, accessed May 11, 2025, https://github.com/modelcontextprotocol
  1. lharries/whatsapp-mcp: WhatsApp MCP server - GitHub, accessed May 11, 2025, https://github.com/lharries/whatsapp-mcp
  1. jlucaso1/whatsapp-mcp-ts: WhatsApp MCP Server (TypeScript/Baileys) - GitHub, accessed May 11, 2025, https://github.com/jlucaso1/whatsapp-mcp-ts
  1. mario-andreschak/mcp-whatsapp-web: WhatsApp MCP server - GitHub, accessed May 11, 2025, https://github.com/mario-andreschak/mcp-whatsapp-web
  1. Show HN: WhatsApp MCP Server - Hacker News, accessed May 11, 2025, https://news.ycombinator.com/item?id=43532967
  1. WhatsApp with Generative AI and MCP - Community.aws, accessed May 11, 2025, https://community.aws/content/2wpVaLAwf9rxZrkvYW97hSeCCNC/whatsapp-with-generative-ai-and-mcp
  1. Gh4stware/whatsapp-mcp: WhatsApp MCP server - GitHub, accessed May 11, 2025, https://github.com/Gh4stware/whatsapp-mcp
  1. WhatsApp MCP server - GitHub - YouTube, accessed May 11, 2025, https://www.youtube.com/watch?v=qY2UK3lU5UM
  1. How to Use WhatsApp MCP Server - Apidog, accessed May 11, 2025, https://apidog.com/blog/whatsapp-mcp-server
  1. WhatsApp MCP Integration - PraisonAI Documentation, accessed May 11, 2025, https://docs.praison.ai/mcp/whatsapp
  1. I build WhatsApp MCP in Cloud. No emulator. No business account. Scan QR code and that’s it - Reddit, accessed May 11, 2025, https://www.reddit.com/r/mcp/comments/1jqonkh/i_build_whatsapp_mcp_in_cloud_no_emulator_no/
  1. whatsapp-api ¡ GitHub Topics, accessed May 11, 2025, https://github.com/topics/whatsapp-api
  1. Releases ¡ lharries/whatsapp-mcp - GitHub, accessed May 11, 2025, https://github.com/lharries/whatsapp-mcp/releases
  1. Project - whatsmeow - Civic Tech Field Guide, accessed May 11, 2025, https://directory.civictech.guide/listing/whatsmeow
  1. I built a WhatsApp MCP in the cloud that lets AI agents send messages without emulators : r/AI_Agents - Reddit, accessed May 11, 2025, https://www.reddit.com/r/AI_Agents/comments/1jqroz2/i_built_a_whatsapp_mcp_in_the_cloud_that_lets_ai/
  1. tulir/whatsmeow: Go library for the WhatsApp web multidevice API - GitHub, accessed May 11, 2025, https://github.com/tulir/whatsmeow
  1. whatsmeow package - github.com/mohammadssalari/whatsmeow - Go Packages, accessed May 11, 2025, https://pkg.go.dev/github.com/mohammadssalari/whatsmeow
  1. Unofficial WhatsApp API: What it is and How to Use it Safely - NexBlog - Nexloo, accessed May 11, 2025, https://blog.nexloo.com/en/unofficial-whatsapp-api-what-it-is-and-how-to-use-it-safely/
  1. Avoid WhatsApp API Restrictions and Bans: Key Mistakes & How to Fix Them - ChakraHQ, accessed May 11, 2025, https://chakrahq.com/article/whatsapp-api-account-restricted-or-blocked-find-out-why-and-how-to-resolve/
  1. How WhatsApp Business API Works: Official vs Unofficial - No-Code Start-Up, accessed May 11, 2025, https://nocodestartup.io/en/how-does-the-official-vs-unofficial-whatsapp-business-api-work/?
  1. WhatsApp Web Protocol (AKA Unofficial API) - by Erwin van Ginkel, accessed May 11, 2025, https://erwinvanginkel.com/whatsapp-web-protocol-aka-unofficial-api/
  1. Using unofficial WhatsApp and leaking my personal information - Zapier Community, accessed May 11, 2025, https://community.zapier.com/troubleshooting-99/using-unofficial-whatsapp-and-leaking-my-personal-information-33440
  1. WhatsApp integration: the risks of doing it unofficially - Zenvia, accessed May 11, 2025, https://www.zenvia.com/en/blog/whatsapp-integration-risks-unofficially-integrating/
  1. Security - vibe-dev/whatsapp-mcp - GitHub, accessed May 11, 2025, https://github.com/vibe-dev/whatsapp-mcp/security
  1. The legality of using the Whatsapp API ¡ Issue #342 ¡ Rhymen/go-whatsapp - GitHub, accessed May 11, 2025, https://github.com/Rhymen/go-whatsapp/issues/342
  1. WhatsApp Business: Web vs API vs MCP - Polser, accessed May 11, 2025, https://blog.polser.io/whatsapp-business-web-vs-api-vs-mcp/
  1. What’s the difference between an unofficial WhatsApp automation tool and using the official API? - Quora, accessed May 11, 2025, https://www.quora.com/What-s-the-difference-between-an-unofficial-WhatsApp-automation-tool-and-using-the-official-API
  1. Unlocking Business Potential with WhatsApp API: A Comprehensive Guide using Apidog, accessed May 11, 2025, https://apidog.com/blog/unlocking-business-potential-with-whatsapp-api-a-comprehensive-guide/
  1. Top 20 WhatsApp API Providers: Comparative Guide (2025) - AiSensy, accessed May 11, 2025, https://m.aisensy.com/blog/whatsapp-api-providers/
  1. Luke Harries lharries - GitHub, accessed May 11, 2025, https://github.com/lharries
  1. WhatsApp MCP tutorial : r/ClaudeAI - Reddit, accessed May 11, 2025, https://www.reddit.com/r/ClaudeAI/comments/1jn69v5/whatsapp_mcp_tutorial/