WhatsApp MCP Server for VS Code: Setup & Config

What you can do with WhatsApp in VS Code

Choose local WhatsApp history search with contact context and text, file, and voice-message tools.

• Find a past message and inspect its surrounding conversation.
• Send text or documents to an individual or group.

Before you start: WhatsApp in VS Code

• Go
• Python 3.6+
• uv
• Claude Desktop or Cursor
• A personal WhatsApp account and mobile app

Replace the README path placeholders with your uv executable and cloned source location. First run go run main.go in whatsapp-bridge and authenticate by QR code. FFmpeg is optional for voice conversion; Windows needs CGO and a C compiler.

WhatsApp VS Code configuration

1. Choose VS Code configuration scope

   For WhatsApp MCP Server, open Workspace: .vscode/mcp.json. Merge into servers; preserve existing inputs.

2. Add WhatsApp MCP Server to VS Code

   Use the whatsapp-mcp entry below in servers. Keep WhatsApp MCP Server's documented stdio connection fields and your other VS Code entries.

3. Check WhatsApp MCP Server in VS Code

   WhatsApp MCP Server: Start in VS Code’s MCP controls; inspect output and trust prompts.

{
  "servers": {
    "whatsapp-mcp": {
      "type": "stdio",
      "command": "{{PATH_TO_UV}}",
      "args": [
        "--directory",
        "{{PATH_TO_SRC}}/whatsapp-mcp/whatsapp-mcp-server",
        "run",
        "main.py"
      ],
      "env": {}
    }
  }
}

WhatsApp tools available to VS Code

WhatsApp's stored tool list documents 12 tools; compare it with VS Code's connected tool list, because the stored list is not a live check.

search_contacts

Look for search_contacts among VS Code's agent-mode tools after starting WhatsApp through the MCP controls.

Find WhatsApp contacts using a name or phone number.

list_messages

Look for list_messages among VS Code's agent-mode tools after starting WhatsApp through the MCP controls.

Retrieve messages using filters and optional contextual information.

list_chats

Look for list_chats among VS Code's agent-mode tools after starting WhatsApp through the MCP controls.

Enumerate chats along with their metadata.

get_chat

Look for get_chat among VS Code's agent-mode tools after starting WhatsApp through the MCP controls.

get_direct_chat_by_contact

Look for get_direct_chat_by_contact among VS Code's agent-mode tools after starting WhatsApp through the MCP controls.

get_contact_chats

Look for get_contact_chats among VS Code's agent-mode tools after starting WhatsApp through the MCP controls.

get_last_interaction

Look for get_last_interaction among VS Code's agent-mode tools after starting WhatsApp through the MCP controls.

Retrieve the latest message exchanged with a contact.

get_message_context

Look for get_message_context among VS Code's agent-mode tools after starting WhatsApp through the MCP controls.

Read messages surrounding a selected message.

send_message

Look for send_message among VS Code's agent-mode tools after starting WhatsApp through the MCP controls.

Send text to a phone number or group JID.

send_file

Look for send_file among VS Code's agent-mode tools after starting WhatsApp through the MCP controls.

send_audio_message

Look for send_audio_message among VS Code's agent-mode tools after starting WhatsApp through the MCP controls.

download_media

Look for download_media among VS Code's agent-mode tools after starting WhatsApp through the MCP controls.

WhatsApp: full stored tool descriptions

Troubleshooting WhatsApp in VS Code

• Known limitation: Requires both the Go bridge and Python server to run.
• Known limitation: QR authentication can need renewal; initial history loading may take time.
• Known limitation: Private chat content can create prompt-injection and data-exposure risks.
• General VS Code troubleshooting lives in the /clients/vscode guide.

Frequently asked questions