personal-whatsapp-mcp
The project is a personalized and enhanced version of the WhatsApp MCP Server, incorporating additional automation features for improved usability and functionality. It allows integration with AI assistants to manage WhatsApp messages and communications, featuring automatic startup and authentication processes.
Gopal Shivapuja's Enhanced WhatsApp MCP Server
This repository is a personalized and enhanced version of the WhatsApp MCP Server by Luke Harries. It includes additional automation scripts for easy setup, automatic startup, self-monitoring, and automatic QR code authentication, tailored and maintained by Gopal Shivapuja.
Credits:
- Original project: WhatsApp MCP Server by Luke Harries
- Enhancements, automation, and personalization: Gopal Shivapuja
What This Does
This WhatsApp MCP Server allows you to:
- Connect your WhatsApp account to AI assistants like Claude
- Search and read your WhatsApp messages from your AI assistant
- Send messages and media through WhatsApp via your AI assistant
- Automatically handle keeping the service running
Enhanced Features (by Gopal Shivapuja)
This version adds several improvements to the original project:
- Automatic Startup: The WhatsApp bridge starts automatically when your system boots
- Daily Self-Check: The system checks once per day if the service is running and restarts it if needed
- QR Code Authentication: When your session expires (typically after 20+ days), the system automatically shows a QR code for re-authentication
- System Notifications: You get notified when action is required
- Comprehensive Logging: All activities are properly logged for easy troubleshooting
- Automated Setup: Dependency checking and automatic Python package installation
Installation
Prerequisites
- macOS (the automation scripts are designed for macOS)
- Go
- Python 3.6+
- Either UV or pip Python package manager (the setup script will check and use whichever is available)
- FFmpeg (optional) - Only needed for sending voice messages
Step-by-Step Installation
-
Clone this repository
git clone https://github.com/gopalshivapuja/personal-whatsapp-mcp.git cd personal-whatsapp-mcp
-
Run the WhatsApp bridge for initial setup
cd whatsapp-bridge go run main.go
Scan the QR code with your WhatsApp mobile app to authenticate.
-
Run the automation setup script
cd .. bash automation/setup.sh
This will:
- Check for all required dependencies (Go, Python, etc.)
- Install Python requirements automatically if UV or pip is available
- Create launch agents to run the service at system startup
- Set up a daily watchdog to check if the service is running
- Configure automatic QR code display when re-authentication is needed
- Start the WhatsApp bridge immediately
-
Connect to Claude or another AI assistant
Copy this JSON configuration, replacing the paths as needed:
{ "mcpServers": { "whatsapp": { "command": "/path/to/uv", // Run `which uv` to find this "args": [ "--directory", "/path/to/personal-whatsapp-mcp/whatsapp-mcp-server", // Use full path "run", "main.py" ] } } }
For Claude Desktop, save this as:
~/Library/Application Support/Claude/claude_desktop_config.json
For Cursor, save this as:
~/.cursor/mcp.json
How the Automation Works
Automated Scripts
This project includes several well-documented shell scripts in the automation/
directory:
- setup.sh: Main installation script that checks dependencies, installs requirements, and sets up LaunchAgents
- uninstall.sh: Safely removes automation while preserving your WhatsApp data
- start-whatsapp-bridge.sh: Manually starts the WhatsApp bridge if it's not running
- check-and-restart-bridge.sh: Monitors and automatically restarts the bridge if it stops
- check-qr-auth.sh: Detects when authentication is needed and shows a QR code
Automatic Startup
The WhatsApp bridge is configured to start automatically when your system boots through a macOS Launch Agent.
Watchdog Service
Once per day and at system startup, a watchdog script checks if the WhatsApp bridge is running. If it's not, the watchdog automatically restarts it and logs the action.
QR Authentication Helper
When your WhatsApp session expires (typically after 20+ days), the system:
- Detects that re-authentication is needed
- Opens a terminal window showing the QR code
- Displays a system notification
- Automatically resumes normal operation after you scan the code
Logging System
All operations are logged to:
- WhatsApp bridge:
~/Library/Logs/whatsapp-mcp.log
- Error log:
~/Library/Logs/whatsapp-mcp-error.log
- Watchdog log:
~/Library/Logs/whatsapp-mcp-watchdog.log
Managing the Service
Checking Status
To confirm the service is running:
launchctl list | grep whatsapp
Viewing Logs
tail -f ~/Library/Logs/whatsapp-mcp.log
Manual Start
If you need to manually start the bridge:
bash automation/start-whatsapp-bridge.sh
Uninstalling
To remove the automation but keep your data:
bash automation/uninstall.sh
Troubleshooting
QR Code Not Appearing
If you need to force a QR code to appear:
cd whatsapp-bridge
go run main.go
Bridge Not Starting
Check the logs for error messages:
cat ~/Library/Logs/whatsapp-mcp-error.log
Authentication Issues
If you're having trouble with authentication:
- Delete the database files:
rm whatsapp-bridge/store/*.db
- Restart the bridge:
cd whatsapp-bridge && go run main.go
- Scan the QR code with your phone
Dependency Issues
If you encounter errors during setup about missing dependencies:
- Make sure Go is installed:
go version
- Make sure Python 3 is installed:
python3 --version
- For Python package issues, you can manually install dependencies:
pip install -r whatsapp-mcp-server/requirements.txt
Migrating to a New Computer
To set up this system on a new computer:
- Install the prerequisites (Go, Python)
- Clone this repository
- Run the setup script:
bash automation/setup.sh
- Authenticate with WhatsApp when prompted
- Configure Claude or your AI assistant as described above
Technical Details
Automation Components
The system consists of three main components:
-
Primary WhatsApp Bridge Service
- Starts the WhatsApp connection
- Handles message syncing
- Provides the MCP server interface
-
Watchdog Service
- Runs once daily and at system boot
- Checks if the bridge is running
- Automatically restarts it if needed
-
QR Authentication Helper
- Runs once daily and at system boot
- Monitors logs for authentication requests
- Displays QR code when needed
File Locations
- Launch Agents:
~/Library/LaunchAgents/com.user.whatsapp-mcp*.plist
- Log Files:
~/Library/Logs/whatsapp-mcp*.log
- Database:
whatsapp-bridge/store/*.db
- Scripts:
automation/*.sh
Credits and Acknowledgements
- Original WhatsApp MCP Server: Created by Luke Harries. Please visit the original repository for more information about the core functionality.
- WhatsApp Connection: Based on the whatsmeow library by Tulir Asokan.
- Enhancements, Automation, and Personalization: Gopal Shivapuja
This project is provided as-is without warranty. Please use responsibly and in accordance with WhatsApp's terms of service.