Titanmind Whatsapp MCP

🚀 Titanmind WhatsApp MCP

A WhatsApp marketing and messaging tool MCP (Model Control Protocol) service using Titanmind. It automatically handles free - form messages (within a 24 - hour window) and template workflows.

🚀 Quick Start

This service offers all the WhatsApp marketing and messaging capabilities through Titanmind. It includes features like template creation and registration (with components such as header, body, CTAs), bulk template broadcasting to phone numbers, and reading and sending messages in an active conversation.

⚠️ Important Note

This MCP utilizes Titanmind. A Titanmind Account is required to use this MCP.

Titanmind enhances WhatsApp communication by providing powerful features such as conversation management, scheduling, agentic conversations, content generation etc.

✨ Features

Conversation Management

Get Recent Conversations

• Retrieve all conversations with messages sent or received in the last 24 hours.
• Returns conversation data with recent activity.

Get Conversation Messages

• Fetch all messages from a specific conversation.
• Requires: conversation_id (an alphanumeric conversation identifier).

Send WhatsApp Message

• Send a message to an existing WhatsApp conversation.
• Requires: conversation_id and message content.

Template Management

Create Message Template

• Register new WhatsApp message templates for approval.
• Configure the template name (single word, only underscores allowed).
• Set the language (default: "en") and category (MARKETING, UTILITY, AUTHENTICATION).
• Structure message components including:
  • BODY (required): Main text content.
  • HEADER (optional): TEXT, VIDEO, IMAGE, or DOCUMENT format.
  • FOOTER (optional): Footer text.
  • BUTTONS (optional): QUICK_REPLY, URL, or PHONE_NUMBER actions.

Get Templates

• Retrieve all created templates with approval status.
• Optional filtering by template name.

Send Bulk Messages

• Send messages to multiple phone numbers using approved templates.
• Requires: template_id and a list of contacts.
• Contact format: country code alpha (e.g., "IN"), country code (e.g., "91"), and phone number.

📦 Installation

Prerequisites

• Python 3.10 or higher.
• API Key and Business Code from Titanmind.

Usage with MCP Client

In any MCP Client like Claude or Cursor, the Titanmind WhatsApp MCP can be configured in the following ways:

Using Titanmind WhatsApp MCP Python package

1. Install pipx to install the Python package globally.

# terminal

# Install pipx first
brew install pipx  # on macOS
# or
sudo apt install pipx  # on Ubuntu/Debian

# Then install Titanmind WhatsApp MCP Python package 
pipx install titanmind-whatsapp-mcp

# Make sure '/[HOME_DIR_OR_USER_PRFILE]/.local/bin' is on your PATH environment variable. Use pipx ensurepath to set it.
pipx ensurepath 

2. Set the MCP Config in the MCP Client's MCP Configs Json file.

{
  "mcpServers": {
    "TitanMindMCP": {
      "command": "/[HOME_DIR_OR_USER_PRFILE]/.local/bin/titan-mind-mcp",
      "args": [
      ],
      "env": {
        "api-key": "XXXXXXXXXXXXXXXXXXXXXXXX",
        "bus-code": "XXXXXX"
      }
    }
  }
}

Use Remote Titanmind MCP server config

1. Make sure npx is installed in the system.
2. Then just add the MCP config.

{
  "mcpServers": {
    "TitanMindMCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.titanmind.so/whatsapp/mcp/",
        "--header",
        "api-key:XXXXXXXXXXXXXXXXXXXXXXX",
        "--header",
        "bus-code:XXXXXX"
      ]
    }
  }
}

Use local python project config

1. First, set up the project using the instructions in the Setup Project section.
2. Then add the MCP config.

{
  "mcpServers": {
    "TitanMindMCP": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/[PATH_TO_THE_PROJECT]",
        "python",
        "main.py"
      ],
      "env": {
        "api-key": "XXXXXXXXXXXXXXXXXXXX",
        "bus-code": "XXXXXX"
      }
    }
  }
}

Manual Installation for custom purpose or development

Install package from PyPI for package use

pip install titanmind-whatsapp-mcp

Or use uv:

uv pip install titanmind-whatsapp-mcp

Setup Project for development use

1. Clone the repository:

git clone https://github.com/TitanmindAGI/titanmind-whatsapp-mcp
cd titanmind-whatsapp-mcp

2. Install dependencies:

pip install -e .
# Or
uv pip install -e .

3. Set the auth keys

export api-key="your-titanmind-api-key"
export bus-code="your-titanmind-business-code"

📚 Documentation

How it Works

TitanMind's WhatsApp messaging system operates under two distinct messaging modes based on timing and conversation status:

Free - Form Messaging (24 - Hour Window)

• When Available: Only after a user has sent a message within the last 24 hours.
• Content Freedom: Any content is allowed without pre - approval.
• Use Case: Ongoing conversations and immediate responses.

Template Messaging (Outside 24 - Hour Window)

• When Required: For new conversations or when the 24 - hour window has expired.
• Content Structure: Pre - approved, structured message templates only.
• Use Case: Initial outreach and re - engagement campaigns.

Messaging Workflow Process

1. Check Messaging Window Status
   • Verify if the receiver's phone number is within the free - form messaging window.
   • A receiver is eligible for free - form messaging if:
     • A conversation with their phone number already exists AND
     • The receiver has sent a message within the last 24 hours.
2. Choose Messaging Method
   • Free - Form: Send directly if within the 24 - hour window.
   • Template: Register and use an approved template if outside the window.
3. Template Approval Process (if needed)
   • Submit the template for WhatsApp approval.
   • Wait for approval confirmation.
   • The template becomes available for bulk messaging.
4. Send Message
   • Execute message delivery using the appropriate method.
   • Monitor the delivery status.
5. Verify Delivery
   • Check the conversation to confirm the receiver successfully received the message.
   • Track the message status and engagement.

💡 Usage Tip

• All tools integrate with Titanmind's WhatsApp channel messaging functionality.
• Templates require approval before they can be used for bulk messaging.
• For more help, contact us through https://www.titanmind.so/.

📄 License

MIT License - See LICENSE file