WSAPI WhatsApp MCP Server

WSAPI WhatsApp MCP Server

Enables AI assistants to interact with WhatsApp through the WSAPI service, supporting comprehensive messaging, contact management, group operations, and account management functionality. Allows sending various media types, managing chats, and controlling WhatsApp sessions through natural language.

Category
Visit Server

README

@wsapichat/mcp-server

npm version License: MIT

A comprehensive Model Context Protocol (MCP) server that provides LLMs with seamless access to WhatsApp functionality through the WSAPI service. This server enables AI assistants to send messages, manage contacts and groups, handle chat operations, and much more functionallity.

🚀 Features

📱 Core Messaging

  • Text Messages: Send rich text with mentions and replies
  • Media Messages: Send images, videos, audio files, and voice messages
  • Documents: Share files with captions
  • Stickers: Send animated and static stickers
  • Location: Share location data with coordinates and place information
  • Contacts: Send vCard contacts
  • Links: Send URLs with rich preview metadata
  • Reactions: React to messages with emojis

📧 Message Management

  • Edit Messages: Modify sent text messages
  • Delete Messages: Remove messages for all participants or just yourself
  • Star Messages: Mark important messages
  • Mark as Read: Update message read status
  • Reply to Messages: Create threaded conversations

👥 Contact Management

  • List Contacts: Get all WhatsApp contacts
  • Contact Details: Retrieve contact information and business profiles
  • Create/Update Contacts: Manage your contact list
  • Profile Pictures: Get contact profile images
  • Presence Subscription: Monitor contact online status

🏢 Group Management

  • Create Groups: Start new group chats with participants
  • Group Info: Get group details and participant lists
  • Manage Participants: Add/remove group members
  • Group Settings: Update name, description, and picture
  • Invite Links: Generate and manage group invite links

💬 Chat Management

  • List Chats: Get all active conversations
  • Chat Presence: Set typing/recording indicators
  • Archive/Unarchive: Organize chat list
  • Pin/Unpin: Prioritize important chats
  • Mute/Unmute: Control notifications
  • Ephemeral Messages: Configure disappearing messages

🔐 Session & Instance Management

  • Session Status: Monitor connection state
  • QR Code Login: Get QR codes for device pairing
  • Pair Code: Generate pairing codes for phone linking
  • Logout: Disconnect from WhatsApp
  • Instance Settings: Configure instance preferences
  • API Key Management: Generate new authentication keys

👤 Account Management

  • Profile Info: Get account details
  • Display Name: Update account name
  • Profile Picture: Change profile image
  • Status Message: Update account status
  • Presence Status: Set availability (available/unavailable)

📦 Installation

Prerequisites

  • Node.js 18.0.0 or higher
  • npm or yarn package manager
  • WSAPI account with API credentials

NPM Installation

npm install -g @wsapichat/mcp-server

Usage with MCP Clients

Claude Desktop Configuration

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wsapi": {
      "command": "npx",
      "args": ["@wsapichat/mcp-server"],
      "env": {
        "WSAPI_API_KEY": "your_api_key_here",
        "WSAPI_INSTANCE_ID": "your_instance_id_here"
      }
    }
  }
}

Alternative: Local Installation

  1. Install the package:
npm install @wsapichat/mcp-server
  1. Configure environment variables:
WSAPI_API_KEY=your_api_key_here
WSAPI_INSTANCE_ID=your_instance_id_here
WSAPI_BASE_URL=https://api.wsapi.chat
  1. Add to MCP client configuration:
{
  "mcpServers": {
    "wsapi": {
      "command": "node",
      "args": ["./node_modules/@wsapichat/mcp-server/dist/index.js"],
      "env": {
        "WSAPI_API_KEY": "your_api_key_here",
        "WSAPI_INSTANCE_ID": "your_instance_id_here"
      }
    }
  }
}

Development Setup

  1. Clone and install dependencies:
git clone https://github.com/wsapi-chat/wsapi-mcp
cd wsapi-mcp
npm install
  1. Configure environment:
cp .env.example .env
  1. Edit .env file with your WSAPI credentials:
WSAPI_API_KEY=your_api_key_here
WSAPI_INSTANCE_ID=your_instance_id_here
WSAPI_BASE_URL=https://api.wsapi.chat

# Server configuration
LOG_LEVEL=info
NODE_ENV=development
  1. Build and start:
npm run build
npm start

🔧 Development

Development Mode

npm run dev

Type Checking

npm run type-check

Linting

npm run lint
npm run lint:fix

Testing

npm test
npm run test:watch

Generate Types from OpenAPI

npm run generate-types

🛠️ Configuration

Environment Variables

Variable Required Default Description
WSAPI_API_KEY Yes - Your WSAPI API key
WSAPI_INSTANCE_ID Yes - Your WSAPI instance ID
WSAPI_BASE_URL No https://api.wsapi.chat WSAPI base URL
WSAPI_TIMEOUT No 30000 Request timeout in milliseconds
WSAPI_RETRY_ATTEMPTS No 3 Number of retry attempts
WSAPI_RETRY_DELAY No 1000 Delay between retries in milliseconds
PORT No 3000 Server port
LOG_LEVEL No info Logging level (error, warn, info, debug)
NODE_ENV No development Environment (development, production, test)

Getting WSAPI Credentials

  1. Visit WSAPI.chat and create an account
  2. Create a new WhatsApp instance
  3. Get your API key and Instance ID from the dashboard
  4. Configure your instance settings as needed

📚 Usage Examples

Send a Text Message

// Tool: whatsapp_send_text
{
  "to": "1234567890@s.whatsapp.net",
  "text": "Hello! How are you today?",
  "mentions": ["1234567890@s.whatsapp.net"]
}

Send an Image with Caption

// Tool: whatsapp_send_image
{
  "to": "1234567890@s.whatsapp.net",
  "imageURL": "https://example.com/image.jpg",
  "mimeType": "image/jpeg",
  "caption": "Check out this amazing photo!"
}

Create a Group

// Tool: whatsapp_create_group
{
  "name": "Project Team",
  "participants": [
    "1234567890@s.whatsapp.net",
    "0987654321@s.whatsapp.net"
  ]
}

Send Location

// Tool: whatsapp_send_location
{
  "to": "1234567890@s.whatsapp.net",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "name": "San Francisco",
  "address": "San Francisco, CA, USA"
}

Set Chat Presence

// Tool: whatsapp_set_chat_presence
{
  "chatId": "1234567890@s.whatsapp.net",
  "state": "typing"
}

🔗 Available Tools

Messaging Tools

  • whatsapp_send_text - Send text messages
  • whatsapp_send_image - Send image messages
  • whatsapp_send_video - Send video messages
  • whatsapp_send_audio - Send audio files
  • whatsapp_send_voice - Send voice messages
  • whatsapp_send_document - Send document files
  • whatsapp_send_sticker - Send stickers
  • whatsapp_send_location - Send location data
  • whatsapp_send_contact - Send contact vCards
  • whatsapp_send_link - Send links with preview
  • whatsapp_send_reaction - React to messages
  • whatsapp_edit_message - Edit sent messages
  • whatsapp_delete_message - Delete messages
  • whatsapp_mark_message_read - Mark messages as read
  • whatsapp_star_message - Star messages

Contact Tools

  • whatsapp_get_contacts - List all contacts
  • whatsapp_get_contact - Get contact details
  • whatsapp_create_contact - Create new contact
  • whatsapp_update_contact - Update contact info
  • whatsapp_get_contact_picture - Get contact profile picture
  • whatsapp_get_contact_business - Get business profile
  • whatsapp_subscribe_contact_presence - Monitor contact status

Group Tools

  • whatsapp_get_groups - List all groups
  • whatsapp_create_group - Create new group
  • whatsapp_get_group - Get group details
  • whatsapp_update_group_name - Change group name

Chat Tools

  • whatsapp_get_chats - List all chats
  • whatsapp_get_chat - Get chat details
  • whatsapp_set_chat_presence - Set typing/recording status
  • whatsapp_archive_chat - Archive/unarchive chats
  • whatsapp_pin_chat - Pin/unpin chats

Session Tools

  • whatsapp_get_session_status - Check connection status
  • whatsapp_get_qr_code - Get QR code for login
  • whatsapp_get_qr_code_image - Get QR code image
  • whatsapp_get_pair_code - Get pairing code
  • whatsapp_logout - Logout from WhatsApp

Instance Tools

  • whatsapp_get_instance_settings - Get instance configuration
  • whatsapp_update_instance_settings - Update instance settings
  • whatsapp_restart_instance - Restart instance
  • whatsapp_update_api_key - Generate new API key

Account Tools

  • whatsapp_get_account_info - Get account information
  • whatsapp_set_account_name - Update display name
  • whatsapp_set_account_picture - Update profile picture
  • whatsapp_set_account_presence - Set availability status
  • whatsapp_set_account_status - Update status message

🐛 Troubleshooting

Common Issues

  1. Authentication Errors

    • Verify your API key and instance ID are correct
    • Check that your WSAPI subscription is active
    • Ensure the instance is properly configured
  2. Connection Issues

    • Check your internet connection
    • Verify the WSAPI service status
    • Review firewall settings
  3. Message Sending Failures

    • Ensure the recipient number format is correct (include @s.whatsapp.net)
    • Check that the WhatsApp session is active
    • Verify media file formats and sizes
  4. Validation Errors

    • Review input parameters against the tool schemas
    • Check data types and required fields
    • Ensure string lengths don't exceed limits

Debug Mode

Enable debug logging for detailed troubleshooting:

LOG_LEVEL=debug npm start

Health Check

The server includes a built-in health check that verifies API connectivity on startup.

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow TypeScript best practices
  • Add tests for new functionality
  • Update documentation for new features
  • Run linting and type checking before committing
  • Follow the existing code style and conventions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

📞 Support

For support and questions:

  • Create an issue in this repository
  • Check the WSAPI documentation
  • Contact WSAPI support for API-related issues

Built with ❤️ using TypeScript, and the Model Context Protocol SDK.

Recommended Servers

playwright-mcp

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official
Featured
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Official
Featured
Local
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

Official
Featured
Local
TypeScript
VeyraX MCP

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official
Featured
Local
graphlit-mcp-server

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official
Featured
TypeScript
Kagi MCP Server

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official
Featured
Python
E2B

E2B

Using MCP to run code via e2b.

Official
Featured
Neon Database

Neon Database

MCP server for interacting with Neon Management API and databases

Official
Featured
Exa Search

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official
Featured
Qdrant Server

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official
Featured