TimelinesAI MCP 服务器

MCP（模型上下文协议）服务器，将 TimelinesAI 的公共 API——面向团队的 WhatsApp 收件箱——暴露给 Claude。设计用于在 Railway 上以只读模式部署。

👉 部署步骤见 DEPLOY-RAILWAY.md。

功能

为 Claude 提供 12 个工具来读取和操作收件箱：聊天、消息、标签、负责人、已连接号码和团队成员——外加一个通用工具、一个发现工具，以及一个收件箱聚合摘要。

环境变量

三道限制

此 MCP 与真实的人对话。通过 WhatsApp 发送的消息会在几秒内到达某人的手机，而且无法撤销。因此有三道独立的锁。

1. TIMELINES_READ_ONLY — 默认值取决于传输方式

• stdio（本地）： 默认允许写入。

• http（远程）： 默认阻止写入。

在公共部署中忘记设置该变量，会使其保持只读状态。

2. TIMELINES_ALLOW_SEND — 发送限制

在两种传输方式下默认关闭，即使在本地也是如此。即使你启用了写入权限，发送消息仍然被阻止，直到你设置 TIMELINES_ALLOW_SEND=1。

原因在于不对称性：更改标签、重新分配聊天或关闭聊天都是内部且可逆的操作。向客户发送 WhatsApp 消息则不是。它们共享同一个开关没有意义。

3. confirm=true — 按调用设置的限制

除上述条件外，每次发送都要求 confirm=true，就像删除文件、重新配置 webhook 或撤销同事的访问权限一样。工具指令是明确的：首先向用户显示确切收件人和确切文本，只有获得用户明确同意后才能确认。

每次拒绝都会说明是哪一道限制阻止了操作。

端点认证

MCP 协议本身不包含认证机制。在 http 模式下，此服务器要求每个请求都带有 Authorization: Bearer <MCP_AUTH_TOKEN>，或者将密钥嵌入路径（/s/<secreto>/mcp）供 Claude 连接器使用。/healthz 是唯一的公共路径。

如果 MCP_AUTH_TOKEN 缺失或少于 32 个字符，服务器拒绝启动。

本地运行

pip install -r requirements.txt

# stdio (para Claude Desktop)
TIMELINES_API_TOKEN=tla_xxx python timelines_mcp.py

# http (como en Railway)
TIMELINES_MCP_TRANSPORT=http \
TIMELINES_API_TOKEN=tla_xxx \
MCP_AUTH_TOKEN=$(python3 -c "import secrets;print(secrets.token_urlsafe(48))") \
PORT=8000 python timelines_mcp.py

启动时会打印最终所处的模式：

[timelines-mcp] streamable-http on 0.0.0.0:8000  token=set  read_only=True  allow_send=False  sending_enabled=False

关于 TimelinesAI API 的说明

已对照公共参考文档（https://timelines.ai/docs/public-api-reference/overview）验证：

• 基础地址： https://app.timelines.ai/integrations/api，认证方式为 Authorization: Bearer <tla_...>。

• 请求体使用 JSON 格式，而非表单编码。

• 响应带有包装： {"status":"ok","data":{...}}。而且有些失败会以 HTTP 200 但 status:"error" 的形式到达——此服务器将其视为错误而非成功，否则失败的发送会被误读为已发送。

• 错误带有按字段的详细信息： {"status":"error","message":...,"error_code":...,"errors":[{"fields":["phone"],"msg":"..."}]}。这些信息会原样显示在错误消息中。

• 多值过滤器在单个参数中用逗号分隔（label=vip,enterprise），不重复也不带方括号。传入 Python 列表会产生这种形式。

• 页面大小固定为 50，无法更改。 已于 2026-08-25 针对在线 API 验证：limit、per_page、page_size、size、count、take 和 rows 全部被忽略，每页固定返回 50 条记录。唯一有效的参数是 page，响应中的 has_more_pages 指示是否还有下一页。因此工具不暴露 per_page 参数：那将是一个看似可调整实则无效的参数。

• 要减小响应大小，因此不能通过减小页面来实现：需要增加过滤条件，或使用 fields 只保留所需的键。消息是最需要这样做的场景——一个包含 50 条消息的聊天很容易超过字符限制。fields=["uid","text","from_me","timestamp"] 可以将对话的精华内容压缩到原来的一小部分。

• 注意重复的字段名： 一条消息记录带有自己的 data 键（一个元数据字典），此外还有包装层的 data。因此 fields 决定按位置修剪什么（列表内的是记录），而不是按键名。

• 电话号码使用国际格式并带 +：+5215512345678。模型在发出网络请求前会进行验证，并清理空格和连字符。

• text 上限为 2000 个字符；标签为 64 个，聊天名称为 256 个。

• 如果省略 whatsapp_account_phone，TimelinesAI 会从最近连接的账户发送——这很少是用户心中所想的那一个。当连接了多个号码时，最好明确指定。

• 发送之间间隔约 2 秒，这是 WhatsApp 的政策，每条消息消耗积分（1 条文本，2 条带附件；失败的消息会退款）。

• 有三个不同的限制，最好不要混淆：

  限制	数值	适用范围
  请求速率	每个工作区每分钟 50 次	所有操作，包括读取
  每月调用量	每月 200,000 次调用	所有操作
  消息配额	取决于你的套餐（积分）	仅发送

  第一个最容易被触发：超出限制会在操作进行到一半时返回 429 rate_limit_exceeded，而不是在开始时。

  服务器在两层进行防护，两者都在请求层，以便所有工具都被覆盖，而不仅仅是分页的工具：

  1. 共享节奏。 调用之间间隔 1.2 秒（60÷50）。单次调用无需等待；延迟只出现在突发请求中，而这正是触发限制的情况。限制是按工作区计算的，所有工具共享同一个工作区，因此节拍器也是唯一的。

  2. 带 Retry-After 的重试。 如果读取操作遇到 429，会重试一次，等待服务器要求的确切时间。发送操作永远不会自动重试：一条可能已经发出的消息不会因为猜测而重复发送。

  timelines_activity_summary 此外还会返回它已统计到的内容，如果仍然被截断，会附带 stopped_early 注释。对于按人查询的问题，最好使用过滤器（responsible=alguien@...）而不是扫描页面：一次请求而不是二十次。可以写信至 hello@timelines.ai 申请更大的限制。

• 没有聚合端点。 因此 timelines_activity_summary 在 MCP 服务器端进行分页和统计，当计数未到达末尾时会以 complete=false 提示。

安全性

• 密钥放在环境变量中，绝不放在代码里。.gitignore 阻止 .env 文件。

• 一个 TimelinesAI 令牌即可访问整个工作区：团队的所有 WhatsApp 对话，包括电话号码和内容。这是真实客户的信息——请如此对待。

• 共享一个令牌意味着无法按人追踪。

• 要立即切断访问：在 TimelinesAI 仪表板中撤销令牌——服务器会立即失效。