A WhatsApp agent that uses WhatsApp MCP server to send messages and perform other actions.

WhatsApp Agent

An Agent that interacts with WhatsApp using WhatsApp MCP server. It can perform multiple actions on the user's behalf.

🚀 Features

The Agent is connected to WhatsApp MCP server. This server provides the following tools:

• 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

⚡Quick Start

Prerequisites

• Python 3.10+
• WhatsApp MCP server
• An OpenAI API key (or compatible service like DeepSeek)
• uv

[!NOTE] To setup WhatsApp MCP server, follow the instructions in the README.

Installation

Follow these steps to set up the project on your local machine:

1. Clone the repository

   git clone https://github.com/aasherkamal216/whatsapp_agent.git
   cd whatsapp_agent
   

2. Create and activate a virtual environment

   uv venv
   # On macOS/Linux
   source .venv/bin/activate
   # On Windows
   .venv\Scripts\activate
   

3. Install dependencies

   uv sync
   

4. **Set up environm