Metadata-Version: 2.4
Name: wati-mcp-server
Version: 0.1.0
Summary: MCP Server for WATI WhatsApp Business API integration
Author-email: Jairaj Mehra <jairajmehra98@gmail.com>
Maintainer-email: Jairaj Mehra <jairajmehra98@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Jairajmehra/wati_whatsapp_mcp
Project-URL: Documentation, https://github.com/Jairajmehra/wati_whatsapp_mcp#readme
Project-URL: Repository, https://github.com/Jairajmehra/wati_whatsapp_mcp.git
Project-URL: Issues, https://github.com/Jairajmehra/wati_whatsapp_mcp/issues
Keywords: mcp,whatsapp,wati,business-api,model-context-protocol,chatbot,messaging
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: requests>=2.25.0
Requires-Dist: python-dotenv>=0.19.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Dynamic: license-file

# WATI MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides seamless integration with the WATI WhatsApp Business API. This server enables AI assistants to send messages, manage contacts, retrieve conversation data, and handle media files through WhatsApp Business accounts.

## Features

- **Message Management**: Send and receive WhatsApp messages
- **Contact Management**: Add, update, and search contacts with custom attributes
- **Template Messages**: Send pre-approved template messages and broadcasts
- **Media Handling**: Send and receive media files (images, documents, etc.)
- **Conversation History**: Retrieve message history with pagination and filtering
- **Bulk Operations**: Send messages to multiple recipients via CSV upload
- **Real-time Integration**: Works with any MCP-compatible AI assistant

## Installation

Install the package from PyPI:

```bash
pip install wati-mcp-server
```

## Quick Start

### 1. Configure Your MCP Client

Add the server to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "wati": {
      "command": "wati-mcp-server",
      "env": {
        "API_ENDPOINT": "https://live-mt-server.wati.io/YOUR_TENANT_ID",
        "ACCESS_TOKEN": "Bearer YOUR_WATI_ACCESS_TOKEN"
      }
    }
  }
}
```

### 2. Get Your WATI Credentials

1. Sign up for a [WATI account](https://www.wati.io/)
2. Get your WhatsApp Business API approved
3. Find your API endpoint and access token in the WATI dashboard
4. Replace `YOUR_TENANT_ID` and `YOUR_WATI_ACCESS_TOKEN` in the config above

### 3. Restart Claude Desktop

After updating the configuration, restart Claude Desktop completely.

## Available Tools

The server provides the following MCP tools:

### Message Operations
- `get_messages` - Retrieve WhatsApp messages for a specific number
- `send_message_to_opened_session` - Send a message to an open WhatsApp session
- `send_template_message` - Send a pre-approved template message
- `send_template_messages` - Send template messages to multiple recipients
- `send_template_messages_from_csv` - Bulk send template messages from CSV file

### Contact Management
- `get_contacts_list` - Retrieve contacts with filtering options
- `add_contact` - Add a new WhatsApp contact
- `update_contact_attributes` - Update custom attributes for a contact

### Templates and Media
- `get_message_templates` - Retrieve available message templates
- `get_media_by_filename` - Get media file details
- `send_file_to_opened_session` - Send files to WhatsApp sessions

### Utility
- `get_weather` - Demo weather function (for testing)

## Usage Examples

### Send a Template Message

```python
# The AI assistant can use this tool:
send_template_message(
    whatsapp_number=919909000282,
    template_name="welcome_message",
    broadcast_name="new_user_welcome",
    parameters=[
        {"name": "customer_name", "value": "John Doe"},
        {"name": "company_name", "value": "ACME Corp"}
    ]
)
```

### Search Contacts

```python
# Find contacts in a specific city
get_contacts_list(
    attribute='[{"name":"city","operator":"=","value":"Mumbai"}]',
    page_size=20
)
```

### Send Bulk Messages

```python
# Send to multiple recipients
send_template_messages(
    template_name="promotional_offer",
    broadcast_name="summer_sale_2024",
    receivers=[
        {
            "whatsappNumber": "919909000282",
            "customParams": [{"name": "offer_code", "value": "SUMMER25"}]
        },
        {
            "whatsappNumber": "919909000283", 
            "customParams": [{"name": "offer_code", "value": "SUMMER30"}]
        }
    ]
)
```

## Configuration

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `API_ENDPOINT` | Your WATI API endpoint URL | Yes |
| `ACCESS_TOKEN` | Your WATI API access token | Yes |

## Development

### Setting up for Development

```bash
# Clone the repository
git clone https://github.com/Jairajmehra/wati_whatsapp_mcp.git
cd wati_whatsapp_mcp

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install
```

### Running Tests

```bash
pytest
```

### Code Formatting

```bash
black wati_mcp/
flake8 wati_mcp/
mypy wati_mcp/
```

### Building for Distribution

```bash
python -m build
```

## API Reference

### WATIClient Class

The core client class that handles all API interactions:

```python
from wati_mcp.server import WATIClient

client = WATIClient(api_endpoint="...", access_token="...")
```

### Server Creation

```python
from wati_mcp.server import create_server

# Create a configured MCP server
server = create_server()
```

## Error Handling

The server includes comprehensive error handling:

- API request failures are caught and returned as structured error responses
- File operations include existence checks and proper error messages
- Environment variable validation with helpful error messages
- Structured logging for debugging and monitoring

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- **Documentation**: [GitHub Repository](https://github.com/Jairajmehra/wati_whatsapp_mcp)
- **Issues**: [GitHub Issues](https://github.com/Jairajmehra/wati_whatsapp_mcp/issues)
- **WATI Documentation**: [WATI API Docs](https://www.wati.io/developers)

## Changelog

### v0.1.0
- Initial release
- Core WhatsApp messaging functionality
- Contact management features
- Template message support
- Media file handling
- Bulk messaging capabilities

---

Built with ❤️ for the MCP ecosystem
