金大哥 - titanmind-whatsapp-mcp MCP 详情

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”）和类别（营销、实用、认证）。
构建消息组件，包括：
- 正文（必需）：主要文本内容。
- 头部（可选）：文本、视频、图像或文档格式。
- 页脚（可选）：页脚文本。
- 按钮（可选）：快速回复、URL 或电话号码操作。

获取模板

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

批量发送消息

使用已批准的模板向多个电话号码发送消息。
需要提供：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 配置 Python 包脚本：

{
  "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-mcp