Whatsapp

🚀 WhatsApp MCP Protocol Server

This is an MCP (Model Context Protocol) server designed to interact with WhatsApp, integrating a Go bridge and a Python MCP server to provide seamless communication and data management.

🚀 Quick Start

Download the Code

Clone the project repository using Git:

git clone https://github.com/your-username/whatsapp-mcp.git

Navigate to the WhatsApp-MCP directory:

cd whatsapp-mcp

Run the Go Bridge

Before starting the bridge, make sure you have the Go programming language environment installed. Then run the following command in the terminal:

go run bridge/main.go

Start the Python MCP Server

This server is implemented using the Flask framework. First, install the dependencies:

pip install flask requests

Then run the server:

python server/mcp_server.py

✨ Features

Data Storage

• Database Location: whatsapp-bridge/store/
• Chat History: All messages are stored chronologically, supporting fast search and retrieval.
• Index Optimization: Utilize SQLite's query optimization techniques to enhance data access efficiency.

MCP Tools

Claude can interact with WhatsApp through the following tools:

Search Functions

• search_contacts: Find contacts by name or number.
• list_messages: Retrieve messages, supporting filtering and context expansion.
• list_chats: List all available chat histories, including metadata.

Contact Operations

• get_chat: Get detailed information about a specific chat.
• get_direct_chat_by_contact: Find a direct conversation with a specified contact.
• get_contact_chats: List all chats involving a specific contact.

Message Processing

• get_last_interaction: Get the latest message with a certain contact.
• get_message_context: Get the context information of a certain message.

Sending Functions

• send_message: Send a text message to a specified number or group.
• send_file: Send files such as images, videos, and documents.
• send_audio_message: Send audio messages. Ensure the format is .ogg or install FFmpeg for format conversion.

Media Management

• download_media: Download media files from a specified message and return the local path.

📚 Documentation

Media Processing

Sending Rules

• Supported Types: Images, videos, documents, etc., can be sent via send_file.
• Audio Sending: Use the send_audio_message tool. The format should be .ogg or use FFmpeg for conversion.

Download Function

By default, only the metadata of the media is stored. To obtain the actual file, use the download_media tool, input the message_id and chat_jid to download and get the path.

🔧 Technical Details

1. Request Flow: Claude -> Python Server -> Go Bridge -> WhatsApp API
2. Data Storage: All messages are stored in an SQLite database to ensure efficient queries.
3. Device Limitations: There is a limit to the number of linked WhatsApp devices. Please clean up unused devices regularly.

💻 Usage Examples

Go Bridge Startup

package main

import (
    "fmt"
    "log"
)

func main() {
    fmt.Println("WhatsApp Bridge Started")
    // Database initialization logic
}

Python Server Execution

from flask import Flask
import requests

app = Flask(__name__)

@app.route('/api/send_message', methods=['POST'])
def send_message():
    # Handle message sending logic
    return "Message Sent"

Command Line Examples

Start the bridge:

go run bridge/main.go

Run the server:

python server/mcp_server.py

📄 License

This project is licensed under the MIT License. Please refer to the LICENSE file for details.