titanmind-whatsapp

Titanmind WhatsApp MCP provides a WhatsApp marketing and messaging integration powered by Titanmind. It supports free-form messaging within a 24-hour window for ongoing conversations, as well as template-based messaging for new or re-engaged conversations that require pre-approved templates. The MCP exposes tools to manage conversations, send messages, create and fetch templates, and perform bulk messaging through approved templates. You can integrate this MCP into your MCP Client (such as Claude or Cursor) using remote or local configurations to leverage Titanmind's conversation management, scheduling, content generation, and template workflows.

To use it, configure the MCP in your client as either a remote MCP (via npx) or a local Python-based setup. The remote option connects to Titanmind’s hosted MCP endpoint, while the local option runs the Python package installed in your environment. Provide the necessary API key and bus code in the MCP configuration so Titanmind can authorize and route messages to the correct business context. Once configured, you can manage conversations, create templates, register templates for approval, and broadcast messages to multiple contacts using the supported workflow that aligns with WhatsApp’s free-form vs template messaging rules.

Prerequisites:

• Access to Titanmind API key and bus code
• Network access to Titanmind services

Option A: Remote MCP (no local installation required)

1. Ensure you have Node.js and npm installed.
2. Install and run the remote MCP configuration using the MCP client by adding the following configuration:

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

Option B: Local Python-based MCP (requires Python 3.10+)

1. Install Python 3.10 or higher and ensure you have pipx installed (preferred) or use pip install.
2. Install the Titanmind WhatsApp MCP package (via pipx):

# Install pipx if not present (macOS/Linux)
brew install pipx  # macOS
# or
sudo apt install pipx  # Debian/Ubuntu

# Install the MCP package
pipx install titanmind-whatsapp-mcp

3. If you use uv/uvx, you can run the local project with the appropriate command as shown in the repository's examples. Example using uvx (adjust to your environment):

uvx run --directory /path/to/project python main.py

4. Create an MCP config referencing the local entry point (adjust paths as needed):

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

5. Set the environment variables api-key and bus-code with your Titanmind credentials.

Note: The exact command may vary depending on how you install and run the package locally. The README provides both remote (npx) and local (uv/uvx) usage patterns to cover common deployment scenarios.

Tips and considerations:

• Titanmind API key and bus code are required to authorize and route messages to your business context.
• Free-form messaging is available only within the 24-hour window after the recipient’s last message; use template messages for new conversations or when the window has expired.
• Templates require approval before bulk messaging can be performed. Ensure templates include BODY, optional HEADER (TEXT, IMAGE, VIDEO, DOCUMENT), FOOTER, and BUTTONS.
• When using remote MCP, headers api-key and bus-code must be supplied in the config for authentication.
• If using local development setups, export api-key and bus-code as environment variables or include them in the MCP config file under env.
• Keep Titanmind account credentials secure and rotate API keys regularly.