
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.
README
@wsapichat/mcp-server
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
- Install the package:
npm install @wsapichat/mcp-server
- Configure environment variables:
WSAPI_API_KEY=your_api_key_here
WSAPI_INSTANCE_ID=your_instance_id_here
WSAPI_BASE_URL=https://api.wsapi.chat
- 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
- Clone and install dependencies:
git clone https://github.com/wsapi-chat/wsapi-mcp
cd wsapi-mcp
npm install
- Configure environment:
cp .env.example .env
- 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
- 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
- Visit WSAPI.chat and create an account
- Create a new WhatsApp instance
- Get your API key and Instance ID from the dashboard
- 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 messageswhatsapp_send_image
- Send image messageswhatsapp_send_video
- Send video messageswhatsapp_send_audio
- Send audio fileswhatsapp_send_voice
- Send voice messageswhatsapp_send_document
- Send document fileswhatsapp_send_sticker
- Send stickerswhatsapp_send_location
- Send location datawhatsapp_send_contact
- Send contact vCardswhatsapp_send_link
- Send links with previewwhatsapp_send_reaction
- React to messageswhatsapp_edit_message
- Edit sent messageswhatsapp_delete_message
- Delete messageswhatsapp_mark_message_read
- Mark messages as readwhatsapp_star_message
- Star messages
Contact Tools
whatsapp_get_contacts
- List all contactswhatsapp_get_contact
- Get contact detailswhatsapp_create_contact
- Create new contactwhatsapp_update_contact
- Update contact infowhatsapp_get_contact_picture
- Get contact profile picturewhatsapp_get_contact_business
- Get business profilewhatsapp_subscribe_contact_presence
- Monitor contact status
Group Tools
whatsapp_get_groups
- List all groupswhatsapp_create_group
- Create new groupwhatsapp_get_group
- Get group detailswhatsapp_update_group_name
- Change group name
Chat Tools
whatsapp_get_chats
- List all chatswhatsapp_get_chat
- Get chat detailswhatsapp_set_chat_presence
- Set typing/recording statuswhatsapp_archive_chat
- Archive/unarchive chatswhatsapp_pin_chat
- Pin/unpin chats
Session Tools
whatsapp_get_session_status
- Check connection statuswhatsapp_get_qr_code
- Get QR code for loginwhatsapp_get_qr_code_image
- Get QR code imagewhatsapp_get_pair_code
- Get pairing codewhatsapp_logout
- Logout from WhatsApp
Instance Tools
whatsapp_get_instance_settings
- Get instance configurationwhatsapp_update_instance_settings
- Update instance settingswhatsapp_restart_instance
- Restart instancewhatsapp_update_api_key
- Generate new API key
Account Tools
whatsapp_get_account_info
- Get account informationwhatsapp_set_account_name
- Update display namewhatsapp_set_account_picture
- Update profile picturewhatsapp_set_account_presence
- Set availability statuswhatsapp_set_account_status
- Update status message
🐛 Troubleshooting
Common Issues
-
Authentication Errors
- Verify your API key and instance ID are correct
- Check that your WSAPI subscription is active
- Ensure the instance is properly configured
-
Connection Issues
- Check your internet connection
- Verify the WSAPI service status
- Review firewall settings
-
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
-
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
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - 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
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
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.
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.

VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
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.
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.

E2B
Using MCP to run code via e2b.
Neon Database
MCP server for interacting with Neon Management API and databases
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.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.