How to Create a WhatsApp Bot for Free With MCP Servers

Looking to automate WhatsApp messaging without paying for the Business API? This comprehensive guide shows you how to build a powerful WhatsApp bot using the lharries WhatsApp MCP server – completely free. Perfect for developers, businesses, and tech enthusiasts who want to leverage AI capabilities in their WhatsApp interactions.

WhatsApp has evolved into the world’s leading messaging platform with over 2 billion users. Whether you’re running a business or managing personal communications, automating WhatsApp interactions can save countless hours and enhance your messaging capabilities.

The exciting news? You don’t need to pay for expensive WhatsApp Business API services to create your own automated bot. In this step-by-step guide, I’ll walk you through creating a free WhatsApp bot using the Model Context Protocol (MCP) server developed by Luke Harries, available on GitHub.

What Is a WhatsApp MCP Server?

The Model Context Protocol (MCP) server for WhatsApp functions as a bridge between your WhatsApp account and AI models like Claude. Unlike traditional WhatsApp automation that requires the paid Business API, this approach connects directly to your personal WhatsApp account through the WhatsApp Web multi-device API.

Key Benefits of Using This MCP Server

• 100% Free: No subscription fees or API costs
• Message History Access: Search and read your WhatsApp messages, including media files
• Contact Management: Search contacts and manage conversations
• Media Capabilities: Send and receive images, videos, documents, and audio messages
• AI Integration: Leverage powerful AI capabilities through Claude or other compatible models
• Data Privacy: All messages remain stored locally in a SQLite database
• Open Source: Community-supported development and improvements

Prerequisites Before You Begin

Before diving into the setup, make sure you have:

• A smartphone with WhatsApp installed
• A computer (macOS, Linux, or Windows) for hosting the server
• Git installed on your machine
• Go programming language installed
• Python 3.6 or higher
• Claude Desktop app or Cursor (for AI integration)
• UV Python package manager
• FFmpeg (optional, but recommended for audio message capabilities)

Step-by-Step Guide to Creating Your WhatsApp Bot

Step 1: Clone the Repository

First, let’s get the code from GitHub:

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

Step 2: Set Up the WhatsApp Bridge

The WhatsApp bridge is a Go application that connects to WhatsApp’s web API and stores message history in SQLite:

cd whatsapp-bridge
go run main.go

When you run this for the first time, you’ll see a QR code in your terminal. Open WhatsApp on your phone, go to Settings > Linked Devices, and scan this QR code to authenticate.

Note: This authentication typically remains valid for about 20 days, after which you’ll need to re-authenticate.

Step 3: Configure the MCP Server Connection

You’ll need to create a configuration file to connect your AI assistant to the MCP server:

For Claude Desktop users:

1. Create a file named claude_desktop_config.json in your Claude Desktop configuration directory:
   • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
2. Add the following JSON content (replace the path values with your actual paths):

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

To find the correct paths:

• For {{PATH_TO_UV}}: Run which uv in your terminal
• For {{PATH_TO_SRC}}: Navigate to the repository directory and run pwd

For Cursor users:

1. Save the same JSON content as mcp.json in ~/.cursor/mcp.json

Step 4: Start Using Your WhatsApp Bot

1. Restart Claude Desktop or Cursor
2. You should now see WhatsApp as an available integration
3. Start interacting with your WhatsApp contacts through the AI assistant

Special Instructions for Windows Users

Windows users need to take extra steps due to SQLite dependencies:

1. Install a C compiler:
   • We recommend using MSYS2
   • Add the ucrt64\bin folder to your PATH
2. Enable CGO and run the application:

cd whatsapp-bridge
go env -w CGO_ENABLED=1
go run main.go

Without this setup, you’ll encounter errors related to CGO being disabled.

Understanding the Architecture

The WhatsApp MCP server consists of two main components:

1. Go WhatsApp Bridge: Handles the direct connection to WhatsApp’s web API, manages authentication, and stores all message history in a SQLite database.
2. Python MCP Server: Implements the Model Context Protocol, providing standardized tools for AI models to interact with your WhatsApp data.

This architecture ensures:

• Your WhatsApp messages are stored locally
• Data is only sent to AI models when explicitly requested through tools
• You maintain control over what information is shared

What Can Your WhatsApp Bot Do?

Once set up, your WhatsApp bot can perform a wide range of powerful functions:

Messaging and Chat Management

• Send text messages to individuals or groups
• Search through message history with filters and context
• List available chats with detailed metadata
• Find specific conversations by contact or group
• Get context around specific messages

Media Handling

• Send various media types:
  • Images in common formats (JPG, PNG, etc.)
  • Videos
  • Documents and files
  • Voice messages (with FFmpeg support)
• Download and process media from WhatsApp messages

Contact Management

• Search contacts by name or phone number
• List chats involving specific contacts
• Get information about your most recent interactions

Advanced Interactions

By integrating with Claude or other AI assistants, you can:

• Analyze conversation sentiment
• Generate appropriate responses based on message history
• Extract key information from conversations
• Schedule messages through custom scripts
• Create custom workflows for specific business needs

Implementing Common Bot Scenarios

Let’s look at some practical examples of how to implement common bot functionalities using the MCP server tools.

Example 1: Creating an Auto-Responder

When you’re busy, you might want the bot to automatically respond to incoming messages:

# This would be implemented through Claude or your chosen AI interface
def auto_responder(message):
    # Check if the message is new and needs a response
    if is_new_message(message):
        # Generate appropriate response based on message content
        response = generate_response(message.text)
        
        # Send the response
        send_message(message.chat_jid, response)

The MCP server provides the send_message tool that Claude can use to send responses to specific contacts or groups.

Example 2: Media Sharing Bot

A bot that can share requested files or information:

# Example of how Claude would process a request for files
def media_sharing_bot(message):
    if "send me the presentation" in message.text.lower():
        # Use the send_file tool
        send_file(
            message.chat_jid,
            "/path/to/presentation.pdf",
            "Quarterly Results.pdf",
            "Here's the presentation you requested"
        )
    elif "voice memo" in message.text.lower():
        # Use the send_audio_message tool for voice messages
        send_audio_message(
            message.chat_jid,
            "/path/to/audio.ogg",
            "Here's the audio note you requested"
        )

Example 3: Customer Support Assistant

A bot that helps triage customer inquiries:

# Example of how Claude would process customer support requests
def support_assistant(message):
    # Analyze the message content
    issue_type = analyze_issue(message.text)
    
    if issue_type == "technical":
        response = "I see you're having a technical issue. Let me check our knowledge base..."
        # Search knowledge base and provide relevant information
    elif issue_type == "billing":
        response = "For billing questions, I'll need to check your account details..."
        # Look up account information
    else:
        response = "Thank you for contacting support. How can I help you today?"
    
    send_message(message.chat_jid, response)

Advanced Configuration and Customization

Customizing Message Handling

The MCP server stores messages in a SQLite database, allowing you to implement custom logic for handling different message types or responding to specific patterns.

Setting Up Automated Workflows

You can create automated workflows by combining the MCP tools with custom scripts:

1. Scheduled Messages: Use cron jobs or scheduling libraries to trigger messages at specific times
2. Event-Based Responses: Set up triggers for specific events or keywords
3. Integration with Other Services: Connect your WhatsApp bot to other APIs or services

Enhancing with AI Capabilities

The true power of this setup comes from combining WhatsApp access with AI capabilities:

• Natural Language Understanding: Parse and understand complex requests
• Context-Aware Responses: Generate responses based on conversation history
• Language Translation: Communicate with contacts in different languages
• Sentiment Analysis: Gauge the tone and mood of conversations

Troubleshooting Common Issues

Authentication Problems

If you encounter issues with QR code authentication:

1. QR Code Not Displaying: Ensure your terminal supports displaying QR codes. Try resizing the terminal window or using a different terminal emulator.
2. Device Limit Reached: WhatsApp limits the number of linked devices. Remove unused devices from WhatsApp on your phone (Settings > Linked Devices).
3. Session Expired: If your session expires, simply restart the WhatsApp bridge and scan the QR code again.

Database Synchronization Issues

If your messages aren’t syncing properly:

1. Clear Databases and Reconnect:

# Stop the WhatsApp bridge
# Delete the database files
rm whatsapp-bridge/store/messages.db
rm whatsapp-bridge/store/whatsapp.db
# Restart the bridge
cd whatsapp-bridge
go run main.go

2. Check Database Permissions: Ensure your user account has read/write permissions for the database files.

Connection Problems

If Claude or Cursor can’t connect to the MCP server:

1. Verify Paths: Double-check that all paths in your configuration file are correct
2. Check Logs: Look for error messages in the terminal where the Go application is running
3. Restart Components: Sometimes a simple restart of both the bridge and the AI application resolves connection issues

Media Handling Issues

If you’re having trouble with media files:

1. FFmpeg Installation: For audio message conversion, ensure FFmpeg is properly installed and in your PATH
2. File Paths: Use absolute paths when sending files to avoid any path resolution issues
3. Supported Formats: Ensure you’re using media formats that WhatsApp supports

Best Practices for WhatsApp Bots

To ensure your bot operates effectively and ethically:

1. Respect Privacy: Only use the bot for your own WhatsApp account or with explicit permission
2. Avoid Spamming: Don’t use the bot to send unsolicited bulk messages
3. Secure Your Data: Since the system stores messages locally, ensure your computer is secure
4. Regular Backups: Back up your SQLite databases to prevent data loss
5. Monitor Performance: Regularly check logs and database size to ensure optimal performance
6. Stay Within Limits: Be aware of WhatsApp’s rate limits to prevent temporary blocks

Technical Limitations and Considerations

While this MCP server provides powerful capabilities, there are some limitations to be aware of:

• Authentication Duration: You’ll need to re-authenticate approximately every 20 days
• WhatsApp Policy Compliance: Using automation tools may violate WhatsApp’s terms of service in some contexts
• Resource Usage: The bridge and database can use significant disk space with large message histories
• Media Storage: By default, only media metadata is stored; downloading media files requires an additional step
• Platform Dependence: Changes to WhatsApp’s Web API could potentially affect functionality

Conclusion

I hope you liked my approach for whatsapp bot automation as this approach represents a significant advancement in personal WhatsApp automation, allowing individuals and small businesses to leverage sophisticated bot capabilities that were previously available only to enterprises with substantial resources.

Start experimenting with your WhatsApp bot today and discover how it can transform your messaging workflow and communication efficiency. All for Free!

FAQs

Q: Is using an MCP server for WhatsApp against WhatsApp’s terms of service?

A: WhatsApp’s terms don’t explicitly allow or forbid this type of integration for personal use. However, they do restrict automated bulk messaging and commercial use without their official Business API. Use this solution responsibly and be aware of potential policy changes.

Q: Will my personal WhatsApp account be at risk of being banned?

A: When used responsibly for personal automation without spamming or abusive behavior, most users don’t experience issues. However, any automation carries some risk, so use with caution.

Q: Do I need to keep my computer running for the bot to work?

A: Yes, the WhatsApp bridge needs to be running for the bot to function. Consider setting it up on a server or always-on computer for continuous operation.

Q: Can this access my existing WhatsApp message history?

A: Yes, after initial authentication, the system will download and index your existing messages, making them searchable and accessible through the MCP tools.

Q: Is my WhatsApp data secure with this setup?

A: All your WhatsApp data is stored locally in SQLite databases on your machine. Messages are only shared with AI models when explicitly requested through the MCP tools, giving you control over your data.

Q: Can I use this with WhatsApp Business accounts?

A: Yes, this solution works with both personal and business WhatsApp accounts, as long as they support WhatsApp Web.

Q: How much technical knowledge do I need to set this up?

A: This setup requires basic familiarity with command-line interfaces, Git, and software installation. While not extremely complex, it’s more technical than typical consumer software.

Q: Can I extend the functionality beyond what’s described here?

A: Absolutely! Since the project is open source, you can modify the code to add custom features or integrate with other systems. The GitHub repository welcomes contributions and improvements.