Metadata-Version: 2.4
Name: wati-mcp
Version: 0.2.0
Summary: WhatsApp MCP Server using Wati API v3
Author: WhatsApp MCP Contributors
License: MIT License
        
        Copyright (c) 2025 Luke Harries
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: python-dotenv>=0.21.0
Requires-Dist: mcp>=1.6.0
Provides-Extra: cli
Requires-Dist: mcp[cli]>=1.6.0; extra == "cli"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# WhatsApp MCP Server with Wati API v3

This is a Model Context Protocol (MCP) server for WhatsApp using the Wati API **v3**.

Manage your WhatsApp conversations, contacts, templates, campaigns, and channels through AI assistants like Claude. Search and read messages, send texts and files, manage contacts, and automate workflows — all via MCP tools.

![WhatsApp MCP](./example-use.png)

> To get updates on this and other projects [enter your email here](https://docs.google.com/forms/d/1rTF9wMBTN0vPfzWuQa2BjfGKdKIpTbyeKxhPMcEzgyI/preview)

## What's New in v0.2.0

**Breaking change:** This release migrates from the legacy Wati v1 API to the **v3 API** (`/api/ext/v3/*`).

### Changes

- **API v3 migration** — All endpoints updated to `/api/ext/v3/*` paths
- **URL scheme** — Tenant ID no longer embedded in URL path; resolved from Bearer token
- **`WATI_TENANT_ID` is now optional** — Only needed for multi-channel setups (Channel:PhoneNumber targeting)
- **New tools:** `list_contacts`, `get_contact`, `add_contact`, `update_contacts`, `get_contact_count`, `assign_contact_teams`, `send_file_via_url`, `send_interactive` (buttons + list), `assign_operator`, `update_conversation_status`, `list_templates`, `get_template`, `send_template`, `list_campaigns`, `get_campaign`, `list_channels`
- **Removed tools:** `list_chats`, `get_chat`, `get_direct_chat_by_contact`, `get_contact_chats` (replaced by `list_contacts`/`get_contact`/`get_messages`)
- **Simplified response parsing** — v3 has standardized response schemas

### Migration Guide

1. Update `WATI_API_BASE_URL` to your Wati server (e.g. `https://live-mt-server.wati.io`)
2. `WATI_TENANT_ID` can be removed unless you use multi-channel targeting
3. Update tool calls: `send_message(recipient=...)` → `send_message(target=...)`
4. Replace `list_chats`/`get_chat` with `list_contacts`/`get_contact` + `get_messages`

## Installation

### Installing via Smithery

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

[![smithery badge](https://smithery.ai/badge/@wati-io/wati-mcp-server)](https://smithery.ai/server/@wati-io/wati-mcp-server)

### Prerequisites

- Python 3.11+
- Anthropic Claude Desktop app (or Cursor)
- UV (Python package manager), install with `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Wati API access (you'll need your authentication token)

### Steps

1. **Clone this repository**

   ```bash
   git clone https://github.com/wati-io/wati-mcp-server.git
   cd wati-mcp-server
   ```

2. **Configure the Wati API**

   Copy the example environment file and edit it with your Wati API credentials:

   ```bash
   cp .env.example .env
   # Edit .env with your Wati API credentials
   ```

   Required:
   - `WATI_API_BASE_URL`: The base URL for the Wati API (e.g. `https://live-mt-server.wati.io`)
   - `WATI_AUTH_TOKEN`: Your Wati authentication token (Bearer token from dashboard)

   Optional:
   - `WATI_TENANT_ID`: Your Wati tenant ID (only for multi-channel setups)

3. **Connect to the MCP server**

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

   ```json
   {
     "mcpServers": {
       "whatsapp": {
         "command": "{{PATH_TO_UV}}",
         "args": [
           "--directory",
           "{{PATH_TO_SRC}}/wati-mcp-server",
           "run",
           "main.py"
         ]
       }
     }
   }
   ```

   For **Claude**, save this as `claude_desktop_config.json` in:
   ```
   ~/Library/Application Support/Claude/claude_desktop_config.json
   ```

   For **Cursor**, save this as `mcp.json` in:
   ```
   ~/.cursor/mcp.json
   ```

4. **Restart Claude Desktop / Cursor**

## MCP Tools

### Contacts
- **search_contacts** — Search contacts by name or phone number
- **list_contacts** — List contacts with pagination
- **get_contact** — Get detailed contact info by phone or ID
- **add_contact** — Add a new WhatsApp contact
- **update_contacts** — Bulk-update contact custom parameters
- **get_contact_count** — Get total contact count
- **assign_contact_teams** — Assign a contact to teams

### Messages & Conversations
- **get_messages** — Get conversation messages for a contact
- **send_message** — Send a text message
- **send_file** — Send a file (image, video, document, audio) via upload
- **send_file_via_url** — Send a file by URL (no local download needed)
- **download_media** — Download media from a message
- **send_interactive** — Send interactive buttons or list messages
- **assign_operator** — Assign an operator to a conversation
- **update_conversation_status** — Update conversation status (open/solved/pending/block)

### Templates
- **list_templates** — List message templates
- **get_template** — Get template details
- **send_template** — Send template messages to recipients

### Campaigns
- **list_campaigns** — List broadcast campaigns
- **get_campaign** — Get campaign details and statistics

### Channels
- **list_channels** — List available WhatsApp channels

## Architecture

```
Claude/AI Assistant
    ↕ MCP Protocol (stdio)
Python MCP Server (FastMCP)
    ↕ HTTPS + Bearer Auth
Wati API v3
    ↕
WhatsApp Business
```

1. Claude sends requests to the Python MCP server via MCP protocol
2. The MCP server makes authenticated API calls to the Wati v3 API
3. The Wati API communicates with WhatsApp's backend
4. Data flows back through the chain to Claude

## Troubleshooting

- **Authentication errors**: Ensure your `WATI_AUTH_TOKEN` is valid and not expired
- **404 errors**: Make sure `WATI_API_BASE_URL` points to your correct Wati server
- **Rate limiting**: The Wati API has rate limits. If you hit them, wait or contact Wati support
- **Media upload failures**: Check file type support and size limits
- **Permission issues with uv**: Add it to your PATH or use the full path to the executable

For MCP integration troubleshooting, see the [MCP documentation](https://modelcontextprotocol.io/quickstart/server#claude-for-desktop-integration-issues).
