In the rapidly evolving landscape of AI assistants and productivity tools, the ability to connect different platforms and services has become increasingly valuable. One particularly powerful integration is connecting WhatsApp — the world’s most popular messaging platform — with AI tools like Claude and Cursor. This connection opens up a world of possibilities, from automated responses to conversational analysis and beyond.

In this guide, I’ll walk you through setting up WhatsApp Web MCP (Model Context Protocol), a tool that bridges WhatsApp Web with AI models. By the end of this tutorial, you’ll have a working setup that allows Claude and Cursor’s AI agents to interact with your WhatsApp conversations, enabling you to leverage AI capabilities directly within your messaging workflow.

What is WhatsApp Web MCP?

WhatsApp Web MCP is an open-source project that creates a standardized interface between WhatsApp Web and AI models through the Model Context Protocol (MCP). It allows AI models like those in Claude and Cursor to access WhatsApp functionality programmatically, making it possible to automate interactions, analyze conversations, and enhance your messaging experience.

The project consists of two main components:

  1. WhatsApp API Server: Connects to WhatsApp Web and exposes functionality through REST endpoints
  2. MCP Server: Implements the Model Context Protocol, allowing AI models to interact with WhatsApp

This architecture provides flexibility in how you deploy and use the integration, whether you’re running everything on a single machine or distributing components across different systems.

Prerequisites

Before we begin, make sure you have the following:

  • A computer with Node.js (v20 or later) installed
  • A WhatsApp account with an active phone number
  • Claude Desktop installed (for Claude integration)
  • Cursor installed (for Cursor AI Agent integration)
  • Basic familiarity with command line interfaces

Step 1: Start the WhatsApp API Server

The first component we need to run is the WhatsApp API server. This server will connect to WhatsApp Web and provide a REST API for interacting with WhatsApp. Run the following command:

npx wweb-mcp --mode whatsapp-api --auth-strategy local

This starts the WhatsApp API server with local authentication, which means your session will persist between restarts. The server will run on port 3001 by default.

Terminal showing the WhatsApp API server starting up

When you run this command for the first time, you’ll see a QR code displayed in your terminal. Open WhatsApp on your phone, go to Settings > Linked Devices, and scan this QR code to link your WhatsApp account to the API server.

After successfully scanning the QR code, you should see a message indicating that the client is ready. The terminal will also display an API key that looks something like this:

WhatsApp API key: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Make note of this API key as we’ll need it for the next steps. This key is used to authenticate requests to the WhatsApp API server.

Step 2: Integrate with Claude Desktop

Now that we have both servers running, let’s integrate them with Claude Desktop. This will allow Claude to interact with WhatsApp through the MCP server.

Configure Claude Desktop

  1. Open Claude Desktop
  2. Go to Settings (gear icon in the bottom left corner)
  3. Select “Developer”
  4. In the Developer, you’ll need to add an MCP server configuration. Look for the “Edit Config” section.

Claude Developer settings

Edit the claude_desktop_config.json file and add the following configuration under MCP Servers:

{  
    "mcpServers": {  
        "whatsapp": {  
            "command": "npx",  
            "args": [  
                "wweb-mcp",  
                "-m", "mcp",  
                "-c", "api",  
                "-t", "command",  
                "--api-base-url", "http://localhost:3001/api",  
                "--api-key", "YOUR_API_KEY"  
            ]  
        }  
    }  
}

Again, replace YOUR_API_KEY with the API key from your WhatsApp API server.

  1. Save the settings and restart Claude Desktop

After restarting, Claude should now have access to WhatsApp functionality through the MCP server. You can verify this by asking Claude to check the WhatsApp connection status:

Can you check my WhatsApp connection status?

Claude should be able to respond with information about your WhatsApp connection by calling the get_status function.

Using WhatsApp with Claude

Now that Claude is connected to WhatsApp, you can use a variety of commands to interact with your WhatsApp account. Here are some examples:

  1. Check connection status: Can you check if I'm connected to WhatsApp?
  2. Search for contacts: Can you search for contacts with "John" in their name?
  3. Get recent messages from a contact: Can you show me the last 5 messages from +12345678901?
  4. Send a message to a contact: Can you send a message to +12345678901 saying "Hello, this is a test message sent via Claude!"?

Step 3: Integrate with Cursor AI Agents

Cursor is a powerful AI-enhanced code editor that includes AI Agents capable of leveraging external tools like WhatsApp Web MCP. Let’s set up the integration between Cursor’s AI Agents and WhatsApp.

Configure Cursor AI Agents with MCP

  1. Open Cursor
  2. Go to Settings > Cursor Settings
  3. Navigate to the “MCP” section in the settings
  4. Add a new MCP configuration with the name “WhatsApp” and configure it with the following command:
npx wweb-mcp -m mcp -s local -c api -t command --api-base-url http://localhost:3001/api --api-key YOUR_API_KEY

Replace YOUR_API_KEY with your actual WhatsApp API key from Step 2.

Using WhatsApp with Cursor AI Agents

Now that you’ve configured the WhatsApp MCP integration in Cursor, you can access WhatsApp functionality directly through Cursor’s AI Chat or AI Agent interfaces. Here’s how to use it:

Cursor’s AI Agent will use the MCP integration to execute these commands and return the results directly in the chat interface. This enables a seamless workflow where you can discuss code and communicate with WhatsApp contacts all within the same environment.

Building WhatsApp-Powered Development Workflows

With the WhatsApp integration in Cursor, you can create powerful workflows that combine coding and communication. For example:

  1. Collaborative Development Updates: Ask the AI Agent to send progress updates to team members via WhatsApp when you complete significant code changes
  2. Notification System Testing: If you’re developing notification systems, you can test sending messages to WhatsApp directly from your development environment
  3. Code Review Coordination: Use the AI Agent to notify team members about code that needs review and coordinate the review process through WhatsApp
  4. Client Communication: Send status updates or questions to clients directly from your development environment

Example prompt in Cursor’s AI Chat:

I just finished implementing the user authentication feature. Can you send a message to John at +12345678901 with the code changes?

Advanced Applications

Now that you have WhatsApp Web MCP integrated with both Claude and Cursor, let’s explore some advanced applications:

1. Automated Customer Support

You can use Claude or Cursor’s AI Agents to automatically respond to common customer inquiries on WhatsApp. By analyzing incoming messages and generating appropriate responses, the AI can handle basic customer support tasks without human intervention.

Example prompt for Claude:

Can you set up a system to automatically respond to common questions from my WhatsApp business account? When customers ask about our business hours, return policy, or shipping information, I want you to send them the appropriate response.

2. Conversation Analysis

Ask the AI to analyze your WhatsApp conversations to extract insights, identify patterns, and summarize key points. This can be particularly useful for business communications or research purposes.

Example prompt for Cursor’s AI Agent:

Can you analyze my recent WhatsApp conversation with +12345678901 and provide a summary of the key discussion points, action items, and any unresolved questions?

3. Language Translation

If you communicate with people who speak different languages, the AI can translate messages in real-time, making cross-language communication seamless.

Example prompt:

Can you help me communicate with my Spanish-speaking client on WhatsApp? I'll tell you what I want to say in English, and you can translate it to Spanish before sending. Also, translate their Spanish responses to English for me.

4. Programming Assistant with Messaging Integration

In Cursor, you can use the AI Agent to help with programming tasks while also handling communication via WhatsApp. This creates a unified workflow where you can code and communicate without context switching.

Example prompt in Cursor:

I'm working on this React component for a form validation. Can you help me debug this issue with the submit handler? Also, once we fix it, send a message to Sarah at +12345678901 to let her know the validation bug has been fixed.

Troubleshooting

WhatsApp API Server Won’t Start

If you’re having trouble starting the WhatsApp API server, try the following:

  1. Make sure you don’t have another instance of the server running already
  2. Check if port 3001 is already in use by another application
  3. Delete the authentication data and start fresh:
rm -rf .wwebjs_auth  
npx wweb-mcp --mode whatsapp-api --auth-strategy local

Connection Issues between MCP Server and API Server

If the MCP server can’t connect to the API server:

  1. Make sure the WhatsApp API server is running
  2. Verify that you’re using the correct API key
  3. Check if there are any firewall rules blocking the connection
  4. Ensure the API base URL is correct (http://localhost:3001/api)

QR Code Scanning Problems

If you’re having trouble scanning the QR code:

  1. Make sure your phone camera is clean and focused on the QR code
  2. Try increasing the terminal font size to make the QR code larger
  3. Adjust your terminal’s color scheme if the QR code is difficult to read
  4. If using a remote connection, try copying the QR code text and generating the image locally

AI Agent Can’t Access WhatsApp Functions

If Claude or Cursor’s AI Agents can’t access WhatsApp functions:

  1. Verify that the WhatsApp API server is running
  2. Check that you’ve configured the MCP integration correctly with the right API key
  3. Restart the application after making configuration changes
  4. Make sure your WhatsApp session is still active (you may need to scan the QR code again if it’s expired)

Security Considerations

When using WhatsApp Web MCP, keep the following security considerations in mind:

  1. API Key Protection: The API key provides access to your WhatsApp account. Keep it secure and don’t share it publicly.
  2. Local Use Only: The WhatsApp API server should only be run on your local network, not exposed to the internet, unless you implement proper security measures.
  3. Personal Data: Be mindful of the personal data that may be accessed through this integration, including conversations and contact information.
  4. WhatsApp’s Terms of Service: Remember that automated or bot-like interactions may violate WhatsApp’s terms of service. Use this integration responsibly and in accordance with WhatsApp’s policies.

Conclusion

Integrating WhatsApp with AI tools like Claude and Cursor’s AI Agents opens up a world of possibilities for automation, analysis, and enhanced communication. With WhatsApp Web MCP, you can create a bridge between your everyday messaging and powerful AI capabilities, streamlining workflows and enabling new use cases.

The setup process may seem complex at first, but once you have everything running, the integration is seamless and powerful. Start with simple interactions, then gradually explore more advanced applications as you become familiar with the system.

The ability to interact with WhatsApp directly from your AI assistants represents a significant step forward in creating unified workflows that span both communication and productivity tools. Whether you’re using Claude Desktop for general assistance or Cursor for development-focused tasks, the WhatsApp integration adds a valuable dimension to what these AI tools can do for you.

Remember that this setup is primarily for personal or experimental use. For production or business use cases, you may want to explore official WhatsApp Business API solutions for more reliable and supported integration options.

By following this guide, you’ve taken the first step toward a more intelligent and automated messaging experience. Happy messaging!

Disclaimer: This project is not affiliated with WhatsApp, Meta, Anthropic, Cursor, or any other company mentioned. Use this integration responsibly and in accordance with the terms of service of all platforms involved.