WAHA WhatsApp MCP Server

A TypeScript Model Context Protocol stdio server for WhatsApp through a unified WAHA backend. It exposes 28 tools for messages, contacts, media, transcription, speech generation, automatic voice-note replies, message-store search, and per-conversation media automation.

Architecture

MCP client → this package → unified backend /api (:8200)
                                  ├─ PostgreSQL message store
                                  ├─ WAHA live proxy
                                  ├─ transcription and TTS providers
                                  └─ media analysis/archive worker

The MCP server only talks to the authenticated /api facade. It does not connect directly to WAHA, databases, Nextcloud, or model providers. LAN-only management routes for archive review and LLM provider administration are intentionally excluded.

This release targets waha-backend commit 46acc32 or a compatible newer build.

Related MCP server: WhatsApp MCP Server

Install

Claude Code

claude mcp add waha-whatsapp -- \
  env WAHA_API_URL=http://your-server:8200/api \
      WAHA_API_KEY=your-backend-api-key \
  npx -y @marcos-heidemann/waha-mcp-server

MCP JSON configuration

{
  "mcpServers": {
    "waha-whatsapp": {
      "command": "npx",
      "args": ["-y", "@marcos-heidemann/waha-mcp-server"],
      "env": {
        "WAHA_API_URL": "http://your-server:8200/api",
        "WAHA_API_KEY": "your-backend-api-key"
      }
    }
  }
}

Configuration

Older WAHA_STORE_* and WAHA_TRANSCRIPTION_* variables are no longer used. Those services are configured behind the unified backend.

Contact identifiers

Chat-targeting tools use a stable contactId:

• Person: phone digits with country code, such as 5521999999999.

• Group: the stable group JID ending in @g.us.

• Legacy @c.us and @lid aliases remain accepted on routes where the backend supports them.

• Imported chat IDs ending in @import work with message read/search, but not with the backend chat-summary route.

Use whatsapp_list_contacts to discover identifiers.

Tools (28)

Media automation settings

whatsapp_media_settings_update supports:

• captureEnabled

• analyzeImages

• analyzeDocuments

• whatsappReplyEnabled

• includeMediaInRecap

• archiveMode: off, review, or auto

• fixedNextcloudFolderId: integer or null

• archiveConfirmationEnabled

• allowSensitiveProcessing

• askOnReview

Conversation settings are combined with backend-wide kill switches. Always inspect returned warnings or call whatsapp_automation_health before assuming a feature is active. The current public health/warning contract does not expose the global gates for recap inclusion or review questions.

Current backend limitations

• Manual quote replies are not implemented by the public backend send route. Supplying replyTo returns an MCP error and sends nothing.

• whatsapp_forward_message re-sends stored text. It does not preserve media, sender attribution, or WhatsApp's Forwarded label.

• Some current GOWS media is still exposed as stored type chat; type filters may miss it until the backend public API switches to normalized_type.

• Public chat summaries are not fully @lid alias-aware. Read/search are the safer choices for migrated histories.

• Imported sender identities are history-only and are omitted from whatsapp_list_contacts; imported *@import chats support read/search but not live read receipts or chat summaries.

• Durable staged-media preview, Nextcloud folder discovery, archive review/actions, and Motor/LLM configuration remain operator-only management functions.

Development and verification

npm ci
npm test                  # hermetic unit + backend-contract tests
npm run build
npm pack --dry-run

Releases are deployed by pushing a tag that exactly matches the package version, for example v2.4.0. The publish workflow repeats unit tests and the build before publishing to npm with the repository secret.

Live tests require WAHA_API_URL and WAHA_API_KEY:

npm run test:live                         # read-only suites
WAHA_TEST_LEVEL=2 npm run test:live       # includes self-chat writes
WAHA_TEST_LEVEL=3 npm run test:live       # includes configured contact writes

The default test and CI paths never contact WhatsApp.

Security

• Treat the backend API key as a password; never commit it.

• Sending through an unofficial WhatsApp API can trigger anti-abuse controls. Keep automation narrow and rate-limited.

• Media and chat exports can contain sensitive data. Review automation policy before enabling analysis, replies, or archival.

• Rotate any credential that has previously appeared in Git history.

License

MIT