← Back to Free Tools

Set Up Claude Cowork + WhatsApp MCP on Mac

Complete beginner guide. From a fresh MacBook to sending WhatsApp messages through Claude Desktop in 15 minutes.

Prerequisites

1. Install Claude Desktop

Claude Desktop is Anthropic's native Mac app. The "Cowork" features let Claude use external tools (called MCPs) to do things like send WhatsApp messages, read files, and more.

1a. Download Claude Desktop

Go to claude.ai/download and download the macOS installer.

1b. Install it

Open the downloaded .dmg file and drag Claude into your Applications folder.

1c. Open and sign in

Open Claude from Applications (or Spotlight: press Cmd + Space and type "Claude"). Sign in with your Anthropic account.

1d. Enable Cowork features

Once signed in:

1. Click Claude in the menu bar (top-left of screen)
2. Click Settings
3. Go to the Developer tab
4. Enable MCP Servers (this is what powers Cowork tools)

2. Install Node.js (if not installed)

The WhatsApp MCP server is built with Node.js. You need version 20 or higher.

Check if you already have it

Open Terminal (Spotlight: Cmd + Space, type "Terminal") and run:

If it shows v20.x or higher, skip to Step 3. If it says "command not found" or shows an older version, install it:

Install using Homebrew (recommended)

Homebrew is a package manager for Mac. If you don't have it yet, install it first:

Then install Node.js:

Verify the installation:

3. Get the WhatsApp MCP Server

You need to get the WhatsApp MCP server code onto your Mac. Choose one of these options:

Option A: Clone from GitHub (easiest if you have git)

Option B: Copy from USB or AirDrop

If someone already has the project, they can send you the folder directly:

1. Copy the entire whatsapp-mcp folder to your Mac (via USB drive, AirDrop, or any file transfer method)
2. Open Terminal
3. Navigate to the folder and build:

Option C: Download ZIP from GitHub

1. Go to github.com/tradecrypto1/project20
2. Click the green Code button, then Download ZIP
3. Extract the ZIP file
4. Open Terminal and navigate to the WhatsApp MCP folder:

4. Register the MCP with Claude Desktop

You need to tell Claude Desktop where to find the WhatsApp MCP server. This is done through a config file.

4a. Find your Mac username

In Terminal, run:

Remember this value — you'll need it for the config file.

4b. Edit the config file

Open the Claude Desktop config file in Terminal:

4c. Add the WhatsApp MCP configuration

Paste this into the file. Replace YOUR_USERNAME with the output of whoami from Step 4a, and adjust the path if you put the folder somewhere else:

4d. Save and exit

Press Ctrl + O (letter O), then Enter to save. Press Ctrl + X to exit nano.

5. Restart Claude Desktop

Claude Desktop only reads the config file when it starts up. You need to fully restart it.

1. Press Cmd + Q to quit Claude Desktop completely
2. Reopen Claude from Applications or Spotlight
3. The WhatsApp MCP should now appear in the tools list

6. Connect WhatsApp

Now you need to link your WhatsApp account to the MCP server, just like linking WhatsApp Web.

6a. Check connection status

In Claude Desktop, type:

Claude will use the get_connection_status tool. It should say "disconnected" since this is the first time.

6b. Get the QR code

Type:

Claude will display a QR code image in the chat.

6c. Scan with your phone

1. Open WhatsApp on your phone
2. Go to Settings (bottom right on iPhone, top right on Android)
3. Tap Linked Devices
4. Tap Link a Device
5. Scan the QR code shown by Claude

6d. Wait for confirmation

After scanning, wait a few seconds. Ask Claude:

It should now say "ready". You're connected!

7. Test It

Try these commands in Claude Desktop to make sure everything works:

8. Available WhatsApp Commands

The WhatsApp MCP provides 15 tools that Claude can use. Here's the full list:

Tool	Description
get_qr_code	Get the WhatsApp authentication QR code. Scan with your phone to link.
get_connection_status	Check connection status (disconnected, qr_pending, authenticated, ready, reconnecting).
search_contacts	Search for contacts by name or phone number.
list_chats	List all available chats, sorted by most recent activity.
get_chat	Get information about a specific chat including its messages.
get_direct_chat_by_contact	Find a direct chat with a specific contact by phone number.
get_contact_chats	List all chats (direct + groups) involving a specific contact.
get_last_interaction	Get the most recent message with a contact.
list_messages	Retrieve messages from a chat with optional filters (limit, search, sent/received).
get_message_context	Retrieve messages before and after a specific message.
list_groups	List all WhatsApp group chats with participant counts.
send_message	Send a text message to a phone number, group name, or JID.
send_file	Send a file (image, video, audio, document) to a recipient.
send_audio_message	Send an audio file as a WhatsApp voice message (plays inline like a voice note).
download_media	Download media (images, videos, documents) from a WhatsApp message.

9. Transferring to a Friend's Computer

Want to set this up on someone else's Mac? Here's how:

Step 1: Get the files to their Mac

Choose any method:

• AirDrop — select the whatsapp-mcp folder, right-click, Share → AirDrop
• USB drive — copy the folder to a USB stick and plug it in
• Git clone — run git clone https://github.com/tradecrypto1/project20.git on their Mac

Step 2: Install Node.js on their Mac

Step 3: Build the project

Step 4: Edit their Claude Desktop config

Add the same config from Step 4, but with their username and the correct path to where they put the folder.

Step 5: Restart Claude Desktop

Cmd + Q to quit, then reopen.

Step 6: They scan their own QR code

Ask Claude: "Get QR code for WhatsApp" — then they scan it with their own phone.

Troubleshooting

MCP not showing up in Claude Desktop

Check that the path in claude_desktop_config.json is correct. The most common mistake is a wrong username or path.

If the file doesn't exist, you probably need to run npm run build again. After fixing, restart Claude Desktop (Cmd + Q, then reopen).

QR code not appearing

Delete the authentication data folder and try again:

Then restart Claude Desktop and ask for a new QR code.

Connection keeps dropping

The server automatically reconnects up to 20 times with exponential backoff. This is normal behavior. If you're still having issues, check your internet connection and try deleting the auth_data folder to re-authenticate.

Messages not persisting across restarts

Messages are stored in a messages.db SQLite file inside the whatsapp-mcp folder. This file persists across restarts. If messages seem to disappear, check that Claude is looking at the right chat.

"node: command not found"

Node.js is not in your PATH. Try using the full path to node in your config file instead:

Then update claude_desktop_config.json to use the full path. For example:

On Apple Silicon Macs with Homebrew, it's usually:

Config file syntax errors

The config file must be valid JSON. Common mistakes:

• Trailing comma after the last item in a list
• Missing quotes around strings
• Using single quotes instead of double quotes

You can validate your JSON at jsonlint.com.

Monthly Costs

Item	Cost
Claude Desktop	Free (included with any Claude plan)
WhatsApp MCP Server	Free (open source)
Node.js	Free
Total	$0/mo