mediar-ai/whatsapp-macos

WhatsApp macOS MCP Skill

Control the native WhatsApp Catalyst app via dedicated MCP tools. No manual PID management or accessibility tree parsing needed.

Available Tools

| Tool | Description | Key params | |------|-------------|-----------| | whatsapp_status | Check if WhatsApp is running, accessibility granted | (none) | | whatsapp_start | Launch WhatsApp if not running | (none) | | whatsapp_quit | Quit WhatsApp | (none) | | whatsapp_search | Search contacts/chats, returns indexed structured results | query: search text | | whatsapp_open_chat | Click Nth search result to open chat | index: 0-based result index | | whatsapp_get_active_chat | Get current chat name, subtitle, recent messages | limit: max messages (default 10) | | whatsapp_send_message | Send message in current chat with delivery verification | message: text to send | | whatsapp_read_messages | Read messages from current open chat | limit: max messages (default 20) | | whatsapp_scroll_search | Scroll search results to load more | direction: "up"/"down", amount: lines | | whatsapp_list_chats | List visible sidebar chats | filter: "all"/"unread"/"favorites"/"groups" | | whatsapp_navigate | Switch tabs | tab: "chats"/"calls"/"updates"/"settings"/"archived"/"starred" |

Workflow: Send a Message

This is the REQUIRED workflow. Do NOT skip steps.

1. whatsapp_search("contact name") — returns indexed results with section (chats/contacts), contactName, preview, time
2. whatsapp_open_chat(index: N) — click the correct result, returns the active chat name
3. whatsapp_get_active_chat() — verify the correct chat is open (check name matches intended recipient)
4. whatsapp_send_message("your message") — sends in current chat, returns verified: true/false

If the contact isn't in the initial results, use whatsapp_scroll_search(direction: "down") to load more.

Workflow: Read Messages

1. whatsapp_search("contact name") → find the chat
2. whatsapp_open_chat(index: N) → open it
3. whatsapp_get_active_chat() → returns name + recent messages in one call
4. Or use whatsapp_read_messages(limit: 50) for more messages

Search Result Format

Each search result includes:

• index — 0-based position for whatsapp_open_chat
• section — "chats" or "contacts"
• contactName — parsed contact name (may be null for some chats)
• rawDescription — full accessibility description
• preview — last message preview
• time — timestamp

Safety

• Always confirm with user before sending messages unless they gave explicit instructions
• Always verify the active chat name matches the intended recipient before sending
• The send tool includes post-send verification (reads back last message)

Setup

The MCP server must be registered in ~/.claude.json:

"whatsapp": {
  "type": "stdio",
  "command": "whatsapp-mcp",
  "args": [],
  "env": {}
}

Install via: npm install -g whatsapp-mcp-macos

Requires: WhatsApp desktop installed, macOS accessibility permissions granted.