WhatsApp Integration Hub via Wati API (MCP Server)

This repository hosts a Model Context Protocol (MCP) server engineered to bridge AI agents (like Claude) with your WhatsApp communications using the Wati API endpoint.

This infrastructure empowers agents to execute critical functions such as looking up registered contacts, accessing message logs, and initiating communications to individuals. Furthermore, it provides robust mechanisms for transmitting various media types, including static images, dynamic videos, arbitrary documents, and voice recordings.

The system establishes its connection through the official Wati gateway. Message retrieval is managed by the MCP server polling the API when necessary, and transmission to the Language Model (e.g., Claude) is strictly mediated by agent-initiated tool calls, maintaining high control over data exposure.

An illustration of potential utility when integrated with Claude:

For ongoing updates concerning this project and my other endeavors, kindly register your contact information here: Subscription Link

Deployment Guide

Automated Installation via Smithery

To deploy the WhatsApp Integration Server automatically for your Claude Desktop environment using Smithery, execute the following command in your terminal:

bash npx -y @smithery/cli install @wati-io/whatsapp-api-mcp-server --client claude

Pre-requisites Checklist

Before proceeding, ensure you have the following components ready:

• Python environment, version 3.6 or newer.
• The Anthropic Claude Desktop application (or Cursor IDE).
• The uv Python package manager. Installation command: curl -LsSf https://astral.sh/uv/install.sh | sh
• Valid credentials for the Wati API (requiring your Tenant ID and authentication token).

Sequential Setup Steps

1. Source Code Retrieval

Fetch the repository contents:

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

1. Wati API Credential Configuration

Replicate the example configuration file and populate it with your specific Wati API secrets:

bash cd whatsapp-mcp-server cp .env.example .env # Open .env and input your Wati API keys

The following environment variables must be accurately defined in the .env file: - WATI_API_BASE_URL: The primary access endpoint for the Wati service (typically "https://api.wati.io"). - WATI_TENANT_ID: Your unique tenant identifier. - WATI_AUTH_TOKEN: The requisite security token for API authorization.

1. MCP Server Connection Definition

Generate the connection configuration JSON below, ensuring placeholder values like {{PATH}} are substituted with accurate local system paths:

{ "mcpServers": { "whatsapp": { "command": "{{PATH_TO_UV}}", // Execute which uv and insert the resultant path here "args": [ "--directory", "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server", // Navigate to repo, run pwd, append "/whatsapp-mcp-server" "run", "main.py" ] } } }

Configuration File Placement: - For Claude Desktop: Save the above structure as claude_desktop_config.json within the configuration directory:

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

• For Cursor IDE: Save the structure as mcp.json in the Cursor configuration root:

  ~/.cursor/mcp.json

• Application Restart

Initiate a restart of the Claude Desktop client or the Cursor IDE. Upon relaunch, the WhatsApp integration should be visible and accessible within the available toolset.

System Architecture Summary

This solution is composed of a singular primary operational unit:

1. Python MCP Endpoint (whatsapp-mcp-server/): This component implements the standardized Model Context Protocol, functioning as an intermediary layer that translates Claude's requests into authenticated Wati API operations concerning WhatsApp data.

Data Flow via Wati API

• The intermediary MCP server orchestrates all communication with WhatsApp through the Wati API.
• Every transmission requires authentication utilizing the supplied Wati API credentials.
• The Wati API manages the underlying secure connection to the user's WhatsApp instance.
• Data retrieved proceeds back up the chain, ultimately reaching Claude.
• Outbound message transmission follows the reverse path: Claude -> MCP Server -> Wati API -> WhatsApp.

Operational Use Cases

Once the connection is established, agents gain the ability to manage WhatsApp interactions through Claude's interface, harnessing its advanced reasoning capabilities within conversational contexts.

Exposed MCP Functionalities

Claude can invoke the following specialized interfaces to manipulate WhatsApp data:

• search_contacts: Locate entities based on name or telephone number. Yields comprehensive details including identifiers, status, and creation metadata.
• list_messages: Fetch message transcripts, supporting contextual filtering.
• list_chats: Present an index of active conversations with associated metadata.
• get_chat: Retrieve detailed information for a specified conversation thread.
• get_direct_chat_by_contact: Directly identify the thread associated with a singular contact.
• get_contact_chats: Compile a list of all threads involving a specified contact.
• send_message: Dispatch standard text-based messages to a provided destination number.
• send_file: Transmit encapsulated media (images, video, raw audio, documents) to a recipient.
• send_audio_message: Specifically send audio data via WhatsApp protocols.
• download_media: Extract media content from a received message and supply the local file system path for access.
• send_interactive_buttons: Construct and dispatch messages featuring clickable response buttons.

Media Management Capabilities

The server supports bidirectional handling of diverse media formats:

Media Transmission

• Visual/Documentary Assets: Employ the send_file utility for sharing images, videos, or arbitrary file types.
• Auditory Assets: Utilize send_audio_message for sending voice clips, treated by the Wati API as standard file transmissions.

Media Acquisition

To secure a local copy of media within a message payload, invoke the download_media function, providing the filename obtained from the message metadata. The function will return the absolute filesystem path to the newly downloaded asset.

Structured Response Mechanism (Interactive Buttons)

The system fully supports the deployment of rich, interactive messages that guide user input via defined buttons:

Button Configuration Example

You are capable of deploying structured prompts with a maximum of three selectable buttons:

send_interactive_buttons( recipient="85264318721", body_text="Confirm your purchase intent now?", buttons=[ {"text": "Affirm", "id": "proceed"}, {"text": "Terminate", "id": "cancel"}, {"text": "Get Help", "id": "support"} ], header_text="Order Validation Required", footer_text="Thanks for choosing our service!", header_image="https://example.com/product.jpg" )

These structured interactions significantly improve engagement quality by offering constrained, predictable response channels over requiring open-ended textual input.

Underlying Technical Flow

1. Claude transmits operational demands to the Python MCP backend.
2. The MCP backend formulates necessary, authenticated requests to the Wati API gateway.
3. The Wati API interfaces with the operational WhatsApp infrastructure.
4. Data retrieved from WhatsApp traverses the chain backward, culminating at Claude.
5. For outbound messages, the sequence is: Claude -> MCP Service -> Wati API -> WhatsApp network.

Troubleshooting Guidelines

• Execution Permissions (uv): If uv reports permission errors during execution, explicitly reference its full path or ensure the directory containing the executable is present in the system's PATH environment variable.
• Credential Integrity: Verify that all API keys and secrets are correctly mapped within the .env configuration file.
• API Connectivity Failures: If the server fails to handshake with the Wati API, confirm the validity and active status of your Wati account credentials.

Specific API Error Resolutions

• Authentication Failures: Scrutinize the Tenant ID and Auth Token for typographical errors.
• Throttling/Rate Limiting: If the Wati API imposes restrictions on request volume, moderate your query frequency or seek escalation support from Wati.
• Media Upload Issues: Confirm that the file format is compliant with WhatsApp specifications and that the payload size adheres to imposed maximum limits.