Titanmind Whatsapp MCP

🚀 Titanmind WhatsApp MCP

A WhatsApp marketing and messaging tool MCP (Model Control Protocol) service using Titanmind. Handles free-form messages (24hr window) and template workflows automatically

🚀 Quick Start

This service offers comprehensive WhatsApp marketing and messaging capabilities through Titanmind. It automates free - form messages within a 24 - hour window and template - based workflows.

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

Titanmind enhances WhatsApp communication with 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 (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 template name (single word, underscores allowed only).
• Set 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 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"

🔧 Technical Details

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 24 - hour window.
   • Template: Register and use approved template if outside window.
3. Template Approval Process (if needed)
   • Submit template for WhatsApp approval.
   • Wait for approval confirmation.
   • Template becomes available for bulk messaging.
4. Send Message
   • Execute message delivery using the appropriate method.
   • Monitor delivery status.
5. Verify Delivery
   • Check the conversation to confirm the receiver successfully received the message.
   • Track message status and engagement.

📚 Documentation

Usage Notes

• 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

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