{"id":50335389,"url":"https://github.com/bdombro/whatsapp-mcp","last_synced_at":"2026-05-29T13:02:08.598Z","repository":{"id":347731769,"uuid":"1195093828","full_name":"bdombro/whatsapp-mcp","owner":"bdombro","description":"A whatsapp MCP server + archiver","archived":false,"fork":false,"pushed_at":"2026-03-29T08:50:54.000Z","size":3030,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T10:37:17.817Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/bdombro.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T07:55:52.000Z","updated_at":"2026-03-29T08:23:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bdombro/whatsapp-mcp","commit_stats":null,"previous_names":["bdombro/whatsapp-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bdombro/whatsapp-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fwhatsapp-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fwhatsapp-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fwhatsapp-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fwhatsapp-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bdombro","download_url":"https://codeload.github.com/bdombro/whatsapp-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdombro%2Fwhatsapp-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33652986,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"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":"2026-05-29T13:02:07.596Z","updated_at":"2026-05-29T13:02:08.587Z","avatar_url":"https://github.com/bdombro.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Bridge\n\nA pluggable [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI assistants access to personal data sources. Currently supports **WhatsApp** — search/read messages, search contacts, send messages — with the architecture ready for additional sources (Gmail, Google Drive, etc.).\n\nData is stored locally in SQLite and only sent to an LLM when accessed through MCP tools. Each data source registers its own namespaced tools (e.g. `whatsapp_list_chats`, `whatsapp_send_message`).\n\n\u003e *Caution:* as with many MCP servers, this is subject to [the lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/). Project injection could lead to private data exfiltration.\n\n## Architecture\n\nA single Go binary (`whatsapp-cli`) with a pluggable `DataSource` interface. Each source owns its tools, storage, and lifecycle.\n\n| Mode | Command | Description |\n|------|---------|-------------|\n| Core | `whatsapp-cli core` | WhatsApp connection daemon: stores messages in SQLite, exposes a REST API |\n| MCP  | `whatsapp-cli mcp`  | MCP server over stdio. Loads all enabled sources and registers their tools |\n\nData flows: Claude/Cursor talks MCP (stdio) to `whatsapp-cli mcp`, which loads each data source. Read tools query local SQLite directly; write tools proxy through the source's backend (e.g. WhatsApp core daemon REST API).\n\nSee the [product spec](docs/spec.md) for full details.\n\n## Prerequisites\n\n- Go (to build)\n- FFmpeg (*optional*) — only needed for automatic audio format conversion when sending voice messages\n\n## Quick Start\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/lharries/whatsapp-mcp.git\n   cd whatsapp-mcp\n   ```\n\n2. **Install**\n\n   ```bash\n   chmod +x ./tasks.sh\n   ./tasks.sh install\n   ```\n\n   This builds the Go binary, copies it to `/usr/local/bin/whatsapp-cli`, sets up the core daemon, and adds shell completions.\n\n3. **Log in** (first time only)\n\n   ```bash\n   whatsapp-cli login\n   ```\n\n   Scan the QR code with your WhatsApp app. The initial history sync will be captured during login. The daemon will handle reconnection from now on.\n\n4. **Configure the MCP server** in your AI client:\n\n   ```json\n   {\n     \"mcpServers\": {\n       \"whatsapp\": {\n         \"command\": \"whatsapp-cli\",\n         \"args\": [\"mcp\"]\n       }\n     }\n   }\n   ```\n\n   - **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - **Cursor**: `~/.cursor/mcp.json`\n\n5. **Restart Claude Desktop / Cursor**\n\n## Managing the Daemon\n\nInstall the core daemon (runs on login, auto-restarts) and manage it:\n\n```bash\nwhatsapp-cli install-daemon\nwhatsapp-cli start\nwhatsapp-cli stop\nwhatsapp-cli restart\n```\n\nOther commands:\n\n```bash\n# Show status and data locations\nwhatsapp-cli info\n\n# Uninstall daemon and wipe all data\nwhatsapp-cli reset\n\n# Full uninstall (reset + remove binaries)\nwhatsapp-cli uninstall\n```\n\n## Troubleshooting\n\n- **QR code not displaying**: Restart the CLI. Check that your terminal supports QR rendering.\n- **Already logged in**: The CLI reconnects automatically without a QR code.\n- **Device limit reached**: Remove an existing device from WhatsApp on your phone (Settings \u003e Linked Devices).\n- **No messages loading**: Initial history sync can take several minutes for large accounts. History is only pushed during first pairing. If your database is empty, run `whatsapp-cli login --relogin` to re-pair and capture the initial sync.\n- **Out of sync**: Run `whatsapp-cli reset` to wipe all data, then `whatsapp-cli login` to re-authenticate.\n- **Session expired / 405 error**: Run `whatsapp-cli login --relogin` to clear the stale session and re-pair. The daemon will be restarted automatically.\nFor additional Claude Desktop troubleshooting, see the [MCP documentation](https://modelcontextprotocol.io/quickstart/server#claude-for-desktop-integration-issues).\n\n### Windows\n\n`go-sqlite3` requires CGO, which is disabled by default on Windows. Install a C compiler via [MSYS2](https://www.msys2.org/) (add `ucrt64\\bin` to PATH), then:\n\n```bash\ncd whatsapp-cli\ngo env -w CGO_ENABLED=1\ngo build -o whatsapp-cli .\n./whatsapp-cli --core\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdombro%2Fwhatsapp-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbdombro%2Fwhatsapp-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdombro%2Fwhatsapp-mcp/lists"}