Install

Install in under a minute

macOS 13+ with the WhatsApp desktop app installed. Node.js 20+ for the npm install. Xcode Command Line Tools for the Swift compile.

npm install -g whatsapp-mcp-macos

1. 01

   Install the npm package

   The postinstall script runs xcrun swift build -c release to compile the Swift binary. First install takes about 30 seconds. The package is open source, and the npm wrapper launches a local stdio process named whatsapp-mcp-macos.

2. 02

   Grant Accessibility permission

   macOS requires the host app (Claude Desktop, Terminal, Cursor, Windsurf, Fazm, whichever launches the MCP server) to be granted Accessibility permission. Open System Settings → Privacy & Security → Accessibility, click the + button, and add the host app. Toggle it on.

   If the toggle is on but tools fail, remove the entry and re-add it. The TCC database sometimes caches stale permissions.

3. 03

   Register the MCP server

   Drop the JSON config from this page into ~/.claude.json (Claude Code) or the equivalent file for your MCP client. Restart the client. The WhatsApp MCP server should appear in the available tool list.

   Claude Code

   Edit ~/.claude.json and add:

   {
     "mcpServers": {
       "whatsapp": {
         "command": "whatsapp-mcp-macos",
         "transport": "stdio"
       }
     }
   }

   Claude Desktop

   Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add:

   {
     "mcpServers": {
       "whatsapp": {
         "command": "whatsapp-mcp-macos",
         "transport": "stdio"
       }
     }
   }

   Cursor

   Edit ~/.cursor/mcp.json and add:

   {
     "mcpServers": {
       "whatsapp": {
         "command": "whatsapp-mcp-macos",
         "transport": "stdio"
       }
     }
   }

   VS Code

   Edit ~/Library/Application Support/Code/User/mcp.json and add:

   {
     "servers": {
       "whatsapp": {
         "command": "whatsapp-mcp-macos",
         "transport": "stdio"
       }
     }
   }

   Windsurf

   Edit ~/.codeium/windsurf/mcp_config.json and add:

   {
     "mcpServers": {
       "whatsapp": {
         "command": "whatsapp-mcp-macos",
         "transport": "stdio"
       }
     }
   }

4. 04

   Try it

   Open WhatsApp on your Mac (the server expects the app to be running). Then ask your assistant something like “Search WhatsApp for Mom and tell me her last three messages.”