JinDaGe - titanmind-whatsapp-mcp MCP Details

article

README

🚀 Titanmind WhatsApp MCP

Titanmind WhatsApp MCP 是一款基于 Titanmind 的 WhatsApp 营销与消息服务工具，它采用 MCP（模型控制协议），能够自动处理自由格式消息（24 小时窗口）和模板工作流。

📋 概述

本服务借助 Titanmind 提供了所有 WhatsApp 营销和消息功能，包括模板创建、注册（涵盖标题、正文、CTA 等所有组件）、向大量电话号码批量广播模板，以及在活跃对话中读取和发送消息等。

此 MCP 依赖于 Titanmind，使用该 MCP 需要拥有 Titanmind 账户。

Titanmind 通过提供强大的功能，如对话管理、日程安排、智能对话、内容生成等，增强了 WhatsApp 的通信能力。

✨ 主要特性

对话管理

获取最近对话

检索过去 24 小时内有消息收发的所有对话。
返回包含最近活动的对话数据。

获取对话消息

从特定对话中获取所有消息。
需要参数：conversation_id（字母数字组成的对话标识符）。

发送 WhatsApp 消息

向现有的 WhatsApp 对话发送消息。
需要参数：conversation_id 和 message 内容。

模板管理

创建消息模板

注册新的 WhatsApp 消息模板以获得批准。
配置模板名称（单个单词，仅允许使用下划线）。
设置语言（默认："en"）和类别（MARKETING、UTILITY、AUTHENTICATION）。
构建消息组件，包括：
- 正文（必填）：主要文本内容。
- 标题（可选）：支持 TEXT、VIDEO、IMAGE 或 DOCUMENT 格式。
- 页脚（可选）：页脚文本。
- 按钮（可选）：支持 QUICK_REPLY、URL 或 PHONE_NUMBER 操作。

获取模板

检索所有已创建模板及其审批状态。
可根据模板名称进行可选过滤。

批量发送消息

使用已批准的模板向多个电话号码发送消息。
需要参数：template_id 和联系人列表。
联系人格式：国家代码缩写（如 "IN"）、国家代码（如 "91"）和电话号码。

📦 安装指南

前提条件

Python 3.10 或更高版本。
从 Titanmind 获取 API 密钥和业务代码。

在 MCP 客户端中使用

在任何 MCP 客户端（如 Claude 或 Cursor）中，可以通过以下方式添加 Titanmind WhatsApp MCP 配置：

使用 Titanmind WhatsApp MCP Python 包

安装 pipx 以全局安装 Python 包：

# 终端命令

# 首先安装 pipx
brew install pipx  # 在 macOS 上
# 或者
sudo apt install pipx  # 在 Ubuntu/Debian 上

# 然后安装 Titanmind WhatsApp MCP Python 包
pipx install titanmind-whatsapp-mcp

# 确保 '/[HOME_DIR_OR_USER_PRFILE]/.local/bin' 在您的 PATH 环境变量中。使用 pipx ensurepath 进行设置。
pipx ensurepath

在 MCP 客户端的 MCP 配置 JSON 文件中设置 MCP 配置脚本：

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

使用远程 Titanmind MCP 服务器配置

确保系统中安装了 npx。
然后添加 MCP 配置：

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

使用本地 Python 项目配置

首先按照“设置项目”部分中的说明设置项目。
然后添加 MCP 配置：

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

自定义用途或开发的手动安装

从 PyPI 安装包以供使用

pip install titanmind-whatsapp-mcp

或者使用 uv：

uv pip install titanmind-whatsapp-mcp

设置项目以供开发使用

克隆仓库：

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

安装依赖项：

pip install -e .
# 或者
uv pip install -e .

设置认证密钥：

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

🔧 工作原理

TitanMind 的 WhatsApp 消息系统根据时间和对话状态，以两种不同的消息模式运行：

自由格式消息（24 小时窗口）

可用时间：仅在用户在过去 24 小时内发送过消息之后。
内容自由度：任何内容无需预先批准即可发送。
使用场景：进行中的对话和即时响应。

模板消息（24 小时窗口之外）

需要时间：用于新对话或 24 小时窗口已过期时。
内容结构：仅允许使用预先批准的结构化消息模板。
使用场景：初始推广和重新参与活动。

📨 消息工作流程

检查消息窗口状态
- 验证接收方电话号码是否处于自由格式消息窗口内。
- 若满足以下条件，接收方有资格使用自由格式消息：
  - 与该电话号码的对话已经存在。
  - 接收方在过去 24 小时内发送过消息。
选择消息发送方法
- 自由格式：若在 24 小时窗口内，直接发送。
- 模板：若在窗口外，注册并使用已批准的模板。
模板审批流程（如有需要）
- 提交模板以供 WhatsApp 审批。
- 等待审批确认。
- 模板获批后可用于批量消息发送。
发送消息
- 使用适当的方法执行消息发送。
- 监控发送状态。
验证发送情况
- 检查对话以确认接收方已成功收到消息。
- 跟踪消息状态和参与度。

📌 使用注意事项

所有工具均与 Titanmind 的 WhatsApp 渠道消息功能集成。
模板在用于批量消息发送之前需要获得批准。
如需更多帮助，请通过 https://www.titanmind.so/ 与我们联系。

📄 许可证

本项目采用 MIT 许可证，请参阅 LICENSE 文件获取详细信息。

titanmind-whatsapp-mcp