{"id":30306466,"url":"https://github.com/samueljayasingh/whatsapp-mcp","last_synced_at":"2025-08-17T09:39:40.871Z","repository":{"id":310108387,"uuid":"1038741767","full_name":"SamuelJayasingh/WhatsApp-MCP","owner":"SamuelJayasingh","description":"The WhatsApp MCP Server enables sending and receiving WhatsApp messages, including text and media, through a custom Flask API, with all data stored securely in a local SQLite database.","archived":false,"fork":false,"pushed_at":"2025-08-15T19:08:59.000Z","size":12271,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-15T20:40:22.384Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SamuelJayasingh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-15T18:33:50.000Z","updated_at":"2025-08-15T19:09:02.000Z","dependencies_parsed_at":"2025-08-15T20:50:36.344Z","dependency_job_id":null,"html_url":"https://github.com/SamuelJayasingh/WhatsApp-MCP","commit_stats":null,"previous_names":["samueljayasingh/whatsapp-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/SamuelJayasingh/WhatsApp-MCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelJayasingh%2FWhatsApp-MCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelJayasingh%2FWhatsApp-MCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelJayasingh%2FWhatsApp-MCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelJayasingh%2FWhatsApp-MCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SamuelJayasingh","download_url":"https://codeload.github.com/SamuelJayasingh/WhatsApp-MCP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamuelJayasingh%2FWhatsApp-MCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270831698,"owners_count":24653400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-17T09:39:37.700Z","updated_at":"2025-08-17T09:39:40.856Z","avatar_url":"https://github.com/SamuelJayasingh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WhatsApp MCP Server\n\nThis is a Model Context Protocol (MCP) server for WhatsApp, with a custom Flask app to send messages to specific phone numbers.\n\nWith this server, you can send WhatsApp messages (including text, images, videos, documents, and audio messages) to individuals or groups. The app connects directly to your **personal WhatsApp account** via the WhatsApp web multidevice API (using the [whatsmeow](https://github.com/tulir/whatsmeow) library). All your messages are stored locally in a SQLite database.\n\n---\n\n## Installation\n\n### Prerequisites\n\n* **Go** (for the WhatsApp bridge)\n* **Python 3.6+** (for the Flask app)\n* **FFmpeg** (optional) — Only needed for audio messages. If you want to send audio files as playable WhatsApp voice messages, they must be in `.ogg` Opus format. With FFmpeg installed, the MCP server will automatically convert non-Opus audio files. Without FFmpeg, you can still send raw audio files using the `send_file` tool.\n* **SQLite** (included by default for data storage)\n\n---\n\n### Steps\n\n#### 1. **Clone the repository**\n\nStart by cloning the repository to your local machine.\n\n```bash\ngit clone https://github.com/SamuelJayasingh/WhatsApp-MCP.git\ncd WhatsApp-MCP\n```\n\n---\n\n#### 2. **Run the WhatsApp Bridge**\n\nNavigate to the `whatsapp-bridge` directory and run the Go application to establish a connection with WhatsApp.\n\n```bash\ncd whatsapp-bridge\ngo run main.go\n```\n\nThe first time you run this, the app will display a QR code in the terminal. You will need to scan the QR code with your **WhatsApp mobile app** to authenticate the connection.\n\n* After authentication, the bridge will remain connected for approximately 20 days before you may need to re-authenticate.\n\n---\n\n#### 3. **Run the Flask App**\n\nAfter setting up the WhatsApp bridge, navigate to the `whatsapp-mcp-server` directory and start the Flask server.\n\n```bash\ncd whatsapp-mcp-server\npython app.py\n```\n\nThis will start a Flask API server that allows you to send WhatsApp messages to a specific phone number or group. The Flask app exposes endpoints for sending text, images, audio, and documents.\n\n---\n\n### Windows Compatibility\n\nIf you're running this on Windows, ensure that **CGO is enabled** because the Go application depends on SQLite, which requires CGo to be enabled. By default, **CGO is disabled on Windows**.\n\n#### Steps to Enable CGO and Install Dependencies\n\n1. **Install a C compiler**:\n   We recommend using [MSYS2](https://www.msys2.org/) to install a C compiler. Follow the [MSYS2 guide](https://code.visualstudio.com/docs/cpp/config-mingw) to get started.\n\n2. **Enable CGO and run the app**:\n   Once MSYS2 is installed, make sure to set up your `ucrt64\\bin` folder in your `PATH` and enable CGO:\n\n   ```bash\n   cd whatsapp-bridge\n   go env -w CGO_ENABLED=1\n   go run main.go\n   ```\n\nWithout this setup, you will encounter errors like:\n\n\u003e `Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work.`\n\n---\n\n## Architecture Overview\n\nThis application consists of two main components:\n\n1. **Go WhatsApp Bridge** (`whatsapp-bridge/`): A Go application that connects to WhatsApp's web API, handles authentication via QR code, and stores message history in an SQLite database. It serves as the bridge between WhatsApp and the Flask app.\n\n2. **Flask MCP Server** (`whatsapp-mcp-server/`): A Python Flask server that allows you to send WhatsApp messages, both text and media, to specific phone numbers or groups.\n\n---\n\n### Data Storage\n\n* All message history is stored in a SQLite database located in the `whatsapp-bridge/store/` directory.\n* The database contains tables for storing chats and messages.\n* Messages are indexed for efficient searching and retrieval.\n\n---\n\n## Usage\n\nOnce the WhatsApp bridge and Flask app are running, you can use the Flask API to interact with your WhatsApp account and send messages.\n\n### Flask API Endpoints\n\n* **POST `/send_message`**: Send a WhatsApp message to a specified phone number or group JID.\n* **POST `/send_file`**: Send a file (image, video, raw audio, document) to a specified recipient.\n* **POST `/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).\n* **GET `/download_media`**: Download media from a WhatsApp message and get the local file path.\n\n### Media Handling Features\n\nThe MCP server supports both sending and receiving various media types:\n\n#### Media Sending\n\n* **Images, Videos, Documents**: Send these media types using the `send_file` endpoint.\n* **Voice Messages**: Send audio files as WhatsApp voice messages using the `send_audio_message` endpoint.\n\n  * For optimal compatibility, audio files should be in `.ogg` Opus format.\n  * With FFmpeg installed, the system will automatically convert other audio formats (MP3, WAV, etc.) to `.ogg` Opus format.\n  * Without FFmpeg, raw audio files can be sent using the `send_file` tool but they won’t appear as playable voice messages.\n\n#### Media Downloading\n\n* Media metadata is stored in the local database. To access this media, use the `download_media` tool by providing the `message_id` and `chat_jid` (both are shown when printing messages containing media).\n* The tool will download the media and return the local file path, which can be used to open or share the file.\n\n---\n\n## Troubleshooting\n\n### Authentication Issues\n\n* **QR Code Not Displaying**: If the QR code does not appear, try restarting the authentication script. If issues persist, verify that your terminal supports QR code display.\n* **WhatsApp Already Logged In**: If you’re already logged in, the Go bridge will reconnect without showing the QR code.\n* **Device Limit Reached**: WhatsApp limits the number of devices that can be linked. If you reach the limit, you will need to remove a device from WhatsApp on your phone (Settings \u003e Linked Devices).\n* **No Messages Loading**: After the initial authentication, it may take a few minutes to load all your message history, especially if you have many chats.\n\n### Connection Issues\n\n* Ensure both the Go WhatsApp bridge and Flask server are running for proper communication.\n* If your WhatsApp messages get out of sync, delete both database files (`whatsapp-bridge/store/messages.db` and `whatsapp-bridge/store/whatsapp.db`) and restart the Go bridge to re-authenticate.\n\n---\n\n## Acknowledgements\n\nThis project is based on the original work by [lharries](https://github.com/lharries/whatsapp-mcp). Modifications were made to remove the integration with Claude and replace it with a custom Flask app for sending WhatsApp messages.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamueljayasingh%2Fwhatsapp-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamueljayasingh%2Fwhatsapp-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamueljayasingh%2Fwhatsapp-mcp/lists"}