WaPulse WhatsApp

You can manage WaPulse WhatsApp operations programmatically through this MCP server, enabling you to send messages, handle files, manage groups, and control WhatsApp instances via the MCP protocol. This lets you automate common WhatsApp tasks within your existing MCP client workflows.

How to use

You connect your MCP client to the WaPulse MCP server and call the available tools to perform actions such as sending messages, uploading files, managing groups, or handling instance state. Use the server to integrate WaPulse WhatsApp capabilities into your automation, dashboards, or custom apps. Start by configuring an MCP connection with your WaPulse credentials, then invoke operations like sending messages to individuals or groups, loading chat history, creating groups, or managing group participants. If you need documentation or examples of available endpoints, use the built-in API help provided by the server through your MCP client.

How to install

Prerequisites you need before installing:

• Node.js 18 or newer
• An active WaPulse account with API credentials (token and instance ID)
• Access to the internet from the machine running the MCP server Choose one of the installation methods below to get started.

Additional sections

Configuration notes and usage tips are provided to help you connect your MCP client successfully and avoid common misconfigurations. Ensure you set your WaPulse token and instance ID, and optionally specify the base URL for WaPulse if you are using a non-default endpoint.

Installation options and details

Option 1: One-Click Cursor installation is available if you are using Cursor IDE. After installation, you will configure your MCP client to point at the WaPulse MCP server and provide your credentials. This option simplifies setup but requires you to edit the MCP client configuration afterward.

Option 2: NPX (manual)

Install and run the MCP server directly with NPX using your WaPulse credentials.

Command to start:
```bash
npx wapulse-whatsapp-mcp-server

Configuration via environment variables:

export WAPULSE_TOKEN="your-wapulse-token"
export WAPULSE_INSTANCE_ID="your-instance-id"
export WAPULSE_BASE_URL="https://wapulseserver.com:3003"  # optional
npx wapulse-whatsapp-mcp-server

Configuration in the MCP client (Cursor):

{
  "mcpServers": {
    "wapulse": {
      "command": "npx",
      "args": ["wapulse-whatsapp-mcp-server"],
      "env": {
        "WAPULSE_TOKEN": "your-wapulse-token",
        "WAPULSE_INSTANCE_ID": "your-instance-id",
        "WAPULSE_BASE_URL": "https://wapulseserver.com:3003"
      }
    }
  }
}

Option 3: Smithery Cloud

Install via Smithery Cloud if you prefer managed deployment. This path uses the Smithery CLI to install the WaPulse MCP server client-side tooling. You will still configure credentials in your MCP client or environment.

Option 4: Local Development

Local development flow if you want to build and run from source:

1. Clone the project
2. Install dependencies
3. Build the project
4. Run the server from the built artifact These steps enable you to customize or contribute to the server while staying aligned with the MCP protocol.

Configuration

Required credentials to operate with WaPulse:

• wapulseToken: Your WaPulse API token
• wapulseInstanceID: Your WhatsApp instance ID Optional:
• wapulseBaseUrl: WaPulse API base URL (defaults to https://wapulseserver.com:3003)

Usage examples

Send a text message to a number or group using the MCP client connected to this server, then verify delivery or retrieve history as needed. Use group management tools to create groups and manage participants, or load chat messages to review recent conversations. All actions are exposed via the MCP protocol through the WaPulse MCP server.

Phone number format

Use international format without the leading plus sign. Examples: 972512345678 (Israel), 14155552671 (US). Do not prefix with + or include separators.

Error handling

The server returns MCP error codes for validation or internal issues. Expect InvalidParams for input validation errors and InternalError for API or network problems.

Development

Build, test, and lint locally:

npm run build

npm test

npm run lint

## API Documentation

The server provides a built-in API help feature to browse available sections and search for specific topics. You can query about messaging, groups, instances, and error handling.

## Requirements

You need Node.js 18 or newer, a valid WaPulse account with credentials, and an active WhatsApp instance to operate the MCP server.

## Getting WaPulse credentials

Obtain your WaPulse API token and create a WhatsApp instance to note the instance ID. Use these credentials when installing and running the MCP server.

## Support

For issues related to the MCP server, raise an issue in the project issue tracker. For WaPulse API concerns, contact WaPulse support.

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome. Submit a Pull Request with your changes and notes on how to use the server in your environment.

## Available tools

### send\_whatsapp\_message

Send text messages to individuals or groups via WaPulse MCP Server

### send\_whatsapp\_files

Send images, documents, and other files to contacts or groups

### send\_whatsapp\_audio

Send audio messages and voice notes to contacts or groups

### load\_chat\_messages

Retrieve chat history and messages for a specific contact or group

### check\_id\_exists

Verify if a WhatsApp ID exists in your WaPulse account

### validate\_phone\_number

Validate the format of a phone number before sending messages

### get\_all\_chats

List all chat conversations accessible in WaPulse

### create\_whatsapp\_group

Create new WhatsApp groups with initial participants

### add\_group\_participants

Add members to an existing WhatsApp group

### remove\_group\_participants

Remove members from a WhatsApp group

### promote\_group\_participants

Promote group members to admin status

### demote\_group\_participants

Demote admins to regular members

### leave\_whatsapp\_group

Leave a WhatsApp group as a participant or admin

### get\_group\_invite\_link

Retrieve the current invite link for a group

### change\_group\_invite\_code

Generate a new invite link for a group

### get\_group\_requests

View pending join requests for a group

### approve\_group\_request

Approve a pending join request for a group

### reject\_group\_request

Reject a pending join request for a group

### get\_all\_groups

List all groups you are part of

### create\_instance

Create new WaPulse WhatsApp instances

### get\_qr\_code

Obtain the QR code to connect WaPulse Web for an instance

### start\_instance

Start a WaPulse instance to begin operations

### stop\_instance

Stop a WaPulse instance temporarily

### delete\_instance

Delete a WaPulse instance

### get\_wapulse\_documentation

Access MCP-related WaPulse API documentation