TimelinesAI MCP Server

TimelinesAIの公開API — チーム向けWhatsAppインボックス — をClaudeに公開するMCP（Model Context Protocol）サーバー。Railwayに読み取り専用モードでデプロイすることを想定しています。

👉 デプロイ手順はDEPLOY-RAILWAY.mdにあります。

機能

Claudeにインボックスを読み取り・操作するための12のツールを提供します：チャット、メッセージ、ラベル、担当者、接続済み番号、チーム — さらに汎用ツール、ディスカバリーツール、インボックスの集計サマリーも含みます。

環境変数

3つのゲート

このMCPは実際の人間と通信します。WhatsAppで送信されたメッセージは数秒で誰かの電話に届き、取り消すことはできません。そのため、独立した3つの鍵があります。

1. TIMELINES_READ_ONLY — デフォルトはトランスポートに依存

• stdio（ローカル）： 書き込みはデフォルトで許可。

• http（リモート）： 書き込みはデフォルトでブロック。

公開デプロイでこの変数を忘れると、読み取り専用のままになります。

2. TIMELINES_ALLOW_SEND — 送信ゲート

両方のトランスポートでデフォルトでオフ（ローカルでも）。書き込みを有効にしても、TIMELINES_ALLOW_SEND=1を設定するまでメッセージ送信はブロックされたままです。

理由は非対称性にあります：ラベルの変更、チャットの再割り当て、クローズは内部的な可逆アクションです。顧客へのWhatsApp送信はそうではありません。同じスイッチを共有するのは意味がありません。

3. confirm=true — 呼び出しごとのゲート

すべての送信は上記に加えてconfirm=trueを要求します。ファイルの削除、webhookの再設定、同僚のアクセス取り消しと同じです。ツールの指示は明示的です：まずユーザーに正確な宛先と正確なテキストを表示し、承認を得た場合のみ確認します。

各拒否は、3つのゲートのどれが停止させたかを示します。

エンドポイントの認証

MCPプロトコルには独自の認証がありません。httpモードでは、このサーバーは各リクエストでAuthorization: Bearer <MCP_AUTH_TOKEN>を要求するか、Claudeコネクタ用にパスに埋め込まれたシークレット（/s/<secreto>/mcp）を要求します。/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で、form-encodedではありません。

• レスポンスはラップされています： {"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キー（メタデータのdict）が含まれます。そのため、fieldsはキー名ではなく位置（リスト内にあるものはレコード）で何を削るかを決定します。

• 電話番号は国際形式で+付き：+5215512345678。モデルはネットワークに送信する前に検証し、スペースとハイフンをクリーンアップします。

• textは2000文字が上限；ラベルは64、チャット名は256。

• whatsapp_account_phoneを省略すると、TimelinesAIは最も最近接続されたアカウントから送信します — これはユーザーが考えているアカウントであることは稀です。複数の番号が接続されている場合は、明示的に指定することをお勧めします。

• 送信はWhatsAppのポリシーにより約2秒間隔で行われ、各メッセージはクレジットを消費します（テキスト1、添付付き2；失敗したものは返金されます）。

• 3つの異なる制限があり、混同しないように注意してください：

  制限	値	適用対象
  リクエストレート	ワークスペースあたり毎分50	すべて、読み取りを含む
  月間ボリューム	月間200,000コール	すべて
  メッセージングクォータ	プランによる（クレジット）	送信のみ

  最初のものが厄介です：超過すると429 rate_limit_exceededが作業の途中で返されます。最初ではありません。

  サーバーは2つのレベルで防御します。両方ともリクエスト層にあり、すべてのツールがカバーされるようにします。ページングするものだけではありません：

  1. 共有ペーシング。 呼び出しは1.2秒間隔（60÷50）で行われます。単発の呼び出しは待機しません；遅延はバースト時のみ発生し、それがまさに制限に達するケースです。制限はワークスペース単位で、すべてのツールが1つを共有するため、ペースメーカーも1つだけです。

  2. Retry-Afterによる再試行。 読み取りでの429は、サーバーが要求する時間だけ待って1回再試行されます。送信は決して自動再試行されません：送信されたかもしれないメッセージを推測で繰り返すことはありません。

  timelines_activity_summaryはさらに、それでも切断された場合にstopped_earlyという注記付きで数えられた分を返します。人に関する質問には、ページをスキャンする代わりにフィルタリング（responsible=alguien@...）することをお勧めします：20回ではなく1回のリクエストで済みます。より大きな制限はhello@timelines.aiに連絡してリクエストできます。

• 集計エンドポイントはありません。 そのためtimelines_activity_summaryはMCPサーバー側でページングしてカウントし、カウントが最後まで到達しなかった場合はcomplete=falseで通知します。

セキュリティ

• シークレットは環境変数に置かれ、コードには決して置かれません。.gitignoreは.envファイルをブロックします。

• TimelinesAIのトークンはワークスペース全体へのアクセスを提供します：チームのすべてのWhatsApp会話、その電話番号と内容を含みます。これは実際の顧客情報です — そのように扱ってください。

• 共有された単一のトークンは、個人ごとのトレーサビリティがゼロであることを意味します。

• アクセスを即座に遮断するには：TimelinesAIのダッシュボードでトークンを失効させます — サーバーは即座に無効になります。