WhatsApp MCP by TimelinesAI

TimelinesAI 提供的 WhatsApp MCP

通过 Claude、ChatGPT、Cursor 或任何 AI 助手管理团队的 WhatsApp 收件箱。

将你的 TimelinesAI WhatsApp 收件箱连接到 Claude、ChatGPT、Cursor、Codex、Grok 或任何 MCP 客户端。询问哪些消息需要回复，然后通过提示词回复、添加表情回应、添加标签并分配聊天。共提供 34 个工具，全部以你的身份运行，既支持普通 WhatsApp 号码，也支持 WhatsApp Business API（WABA）号码。

所有 TimelinesAI 套餐均包含此功能，不额外收费。 网站 · 设置指南 · MCP 学院

---

这是什么？

TimelinesAI MCP 服务是一个远程控制工具，可在 TimelinesAI 中操作你的真实 WhatsApp 收件箱。使用 TimelinesAI 账号登录一次后，你的 AI 助手即可使用 34 个工具，涵盖聊天发现、消息处理、分流（标签 + 分配）和工作区信息查看，既支持普通 WhatsApp 号码（通过二维码连接），也支持 **WhatsApp Business API（WABA）**号码。

这是托管服务：无需安装，也无需 API 密钥。你的助手连接到 https://mcp.services.timelines.ai/mcp，然后登录一次即可。

这里没有沙盒。写入操作都是真实的，联系人也能看到。收件人无法分辨消息是来自界面还是 AI 助手：发消息的始终是你。

要求

• 一个 TimelinesAI 账号，且工作区中至少连接了一个 WhatsApp 号码。若没有已连接的号码，大多数工具会返回空结果或错误。此 MCP 服务用于远程操作你的真实收件箱，并非沙盒。
• 一个支持远程 MCP 服务的 AI 助手（下方列出的客户端均支持）。

还没有 TimelinesAI 账号？开始 10 天免费试用 →

---

快速设置（约 1 分钟）

所有客户端的服务 URL：https://mcp.services.timelines.ai/mcp

ChatGPT

打开 ChatGPT 中的 TimelinesAI 插件，点击 Connect，并使用 TimelinesAI 账号登录。然后提问：“@TimelinesAI 今天有哪些事需要我处理？”

Claude（claude.ai 和 Claude Desktop）

在 Claude 中，打开 Customize → Connectors → Add custom connector，粘贴服务 URL，并使用 TimelinesAI 账号登录。

Claude Code

claude mcp add --transport http timelinesai https://mcp.services.timelines.ai/mcp

首次使用工具时，Claude Code 会打开浏览器标签页。使用 TimelinesAI 账号登录。

更喜欢使用插件？运行 /plugin marketplace add InitechSoftware/whatsapp-mcp-by-timelinesai，然后运行 /plugin install timelinesai-whatsapp@timelinesai。该插件会启动本地代理，因此需要 Node.js 18+；上述命令则不需要。

Cursor

添加到 Cursor（一键添加），或将以下内容添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "timelinesai": {
      "url": "https://mcp.services.timelines.ai/mcp"
    }
  }
}

首次调用工具时，会打开登录窗口。

Codex

添加到 ~/.codex/config.toml：

[mcp_servers.timelinesai]
url = "https://mcp.services.timelines.ai/mcp"

然后运行一次 codex mcp login timelinesai，并在浏览器中批准。Codex 不会自行启动登录流程。

Grok Build

grok mcp add timelinesai https://mcp.services.timelines.ai/mcp

然后输入 /mcps，选择 timelinesai，并按 i 登录。Grok Build 不会自行启动登录流程。

其他 MCP 客户端

将 https://mcp.services.timelines.ai/mcp 添加为远程服务（Streamable HTTP），并在提示时登录。

可在 examples/ 中查看可直接复制的配置文件。

---

首先尝试

连接后，向助手提问：

“今天有什么事需要我处理？”

或者，想了解功能时：

“timelinesai MCP 服务提供哪些工具？按用途分组，并为每组提供一个提示词示例。”

---

工具目录（34 个工具）

两组并行的工具（一组用于通过 QR code 连接的普通 WhatsApp 号码，另一组用于 **WhatsApp Business API（WABA）**号码），另有两组共用的三个工作区工具。请根据号码选择对应的工具组：workspace_whatsapp_accounts 列出 QR 号码，waba_accounts 列出 WABA 号码。

分组	工具数
工作区（共用）	3
WhatsApp：通过 QR code 连接的号码	14
WhatsApp Business API（WABA）	17
总计	34

工作区：3 个工具

只读信息查询。调用成本低。两组工具共用。

工具	用途
workspace_quotas	当前套餐、席位数、消息与 API 调用配额、计费周期
workspace_whatsapp_accounts	已连接的 QR WhatsApp 账号（id、电话号码、所有者、状态）
workspace_team	团队成员、角色、邀请状态、账号绑定。两组工具中分配负责人时可用来查询邮箱

WhatsApp（通过 QR code 连接的号码）：14 个工具

聊天发现与查看：4 个工具

浏览和读取，不会写入数据。

工具	用途
list_chats	按状态、标签、负责人、群聊/单聊、电话号码、名称、日期、WA 账号筛选聊天。每页 50 条
chat_details	单个聊天的完整元数据
chat_history	列出聊天中的消息。可按日期和方向筛选，并使用消息 UID 游标翻页
message_details	查看单条消息

消息写入：4 个工具

消耗配额。 使用与 TimelinesAI UI 相同的每月消息配额。

工具	用途
chat_send_message	在现有聊天中发送消息（文本、附件或回复）
whatsapp_account_send_message	通过指定的 WA 账号向任意电话号码发送消息（若聊天不存在则创建聊天，即主动发送消息）
message_reply	对特定消息进行线程式回复
message_react	设置或清除消息上的表情回应

聊天变更：6 个工具

用于聊天状态和分流处理的操作。标签和分配操作具有幂等性。

工具	用途
chat_open	重新打开已关闭的聊天
chat_close	关闭聊天
chat_assign	按邮箱将聊天分配给团队成员（使用 workspace_team 查询邮箱）
chat_unassign	取消分配当前负责人
chat_set_label	为聊天添加标签
chat_remove_label	从聊天中移除标签

WhatsApp Business API（WABA）：17 个工具

账号与聊天发现：5 个工具

浏览和读取，不会写入数据。

工具	用途
waba_accounts	可用于发送消息的 WABA 号码。将 id 用作 waba_account_id
waba_list_chats	可查看的 WABA 聊天。按打开/关闭状态、负责人、WABA 账号、电话号码筛选；每页 50 条。发送前检查 service_window_is_open
waba_chat_details	单个 WABA 聊天：服务窗口、分配情况、标签、WABA 账号
waba_chat_history	WABA 聊天中的消息，按最新消息优先排列。可按日期和方向筛选，并使用消息 UID 游标翻页
waba_message_details	查看单条 WABA 消息；发送失败时会包含 failure_reason

模板：2 个工具

工具	用途
waba_templates	可用的消息模板，每页 50 个。只有 APPROVED 模板才能发送
waba_template_details	查看某个模板的组件、状态，以及可以用来发送该模板的 WABA 账号。发送模板前调用

消息写入：4 个工具

发送模板会产生 Meta 费用。 只有在聊天的服务窗口开启时，才能发送自由文本。

工具	用途
waba_start_chat	使用已批准的模板，通过电话号码发起新聊天。Meta 会收费
waba_chat_send_message	在现有 WABA 聊天中发送自由文本消息；仅当 service_window_is_open 为 true 时可用
waba_chat_send_template	在现有 WABA 聊天中发送已批准的模板：服务窗口关闭时的消息发送方式。Meta 会收费
waba_message_react	为 WABA 消息设置或清除表情回应

聊天变更：6 个工具

用于管理 WABA 聊天状态和分流。执行任何变更后，waba_chat_details 都会返回权威状态。

工具	用途
waba_chat_open	重新打开已关闭的 WABA 聊天
waba_chat_close	关闭 WABA 聊天
waba_chat_assign	按电子邮件地址将 WABA 聊天分配给团队成员（来自 workspace_team）
waba_chat_unassign	清除 WABA 聊天的负责人
waba_chat_set_label	添加标签，同时保留现有标签
waba_chat_remove_label	移除一个标签，同时保留其他标签；如果聊天没有该标签，则不执行任何操作

→ 完整架构和提示词示例：docs/tools.md

---

登录方式

该服务使用 OAuth。助手首次连接时，浏览器会在 TimelinesAI 上打开。登录 TimelinesAI 账号并批准访问即可。助手会保留登录状态，因此后续会话重新连接时无需再次询问。

如果你已在浏览器中登录 TimelinesAI，只需单击一次即可批准。

每项操作都以你的身份执行：你在 TimelinesAI 中的角色权限同样适用于 MCP 调用和 UI 操作。

---

安全与生产环境行为

⚠️ 此 MCP 服务会控制真实的 WhatsApp 收件箱。 发送写入操作前请阅读本节。

• 通过 MCP 发送的消息与通过 UI 发送的消息无法区分。 收件人无法辨别。
• 写入操作会立即生效且真实执行。 无法撤销。批量操作前请先确认。
• 配额与 UI 使用量共享：MCP 消息会占用同一月度消息额度。调用 workspace_quotas 查看剩余额度。
• WABA 模板消息会产生 Meta 费用。 waba_start_chat 和 waba_chat_send_template 会发送已批准的模板，Meta 会对此收费。自由文本 waba_chat_send_message 仅在聊天服务窗口开启时可用。
• 没有沙盒模式。 如果不确定，请先用自己的号码进行练习。
• 如果没有关联的 WhatsApp 号码，大多数工具会返回空结果或错误。请先在 TimelinesAI 中关联号码。

---

开始使用

1. 开始 TimelinesAI 的 10 天免费试用 →
2. 在 TimelinesAI 控制面板中关联一个 WhatsApp 号码。
3. 选择上方的助手并连接。
4. 登录，然后询问：“今天有什么需要我处理？”

---

链接

• WhatsApp MCP 页面：timelines.ai/whatsapp-mcp
• 设置指南：timelines.ai/whatsapp-mcp-guide
• MCP Academy（简短课程，无需注册）：timelines.ai/academy/mcp
• 注册：app.timelines.ai/register
• MCP 服务端点：https://mcp.services.timelines.ai/mcp
• Model Context Protocol：modelcontextprotocol.io
• 问题 / 反馈：在此仓库中提交问题

---

许可证

MIT © 2026 Initech Software / TimelinesAI