TimelinesAI MCP Server

MCP-Server (Model Context Protocol), der die öffentliche API von TimelinesAI – den WhatsApp-Posteingang für Teams – für Claude bereitstellt. Entwickelt für die Bereitstellung auf Railway im Nur-Lese-Modus.

👉 Die Bereitstellungsschritte finden Sie in DEPLOY-RAILWAY.md.

Was es tut

Gibt Claude 12 Werkzeuge zum Lesen und Bedienen des Posteingangs: Chats, Nachrichten, Labels, Verantwortliche, verbundene Nummern und Team – plus ein generisches Werkzeug, ein Entdeckungswerkzeug und eine aggregierte Zusammenfassung des Posteingangs.

Umgebungsvariablen

Die drei Sperren

Dieser MCP spricht mit echten Menschen. Eine über WhatsApp gesendete Nachricht erreicht in Sekunden das Telefon einer Person und kann nicht rückgängig gemacht werden. Deshalb gibt es drei unabhängige Sperren.

1. TIMELINES_READ_ONLY – der Standard hängt vom Transport ab

• stdio (lokal): Schreibvorgänge erlaubt standardmäßig.

• http (remote): Schreibvorgänge blockiert standardmäßig.

Wenn die Variable bei einer öffentlichen Bereitstellung vergessen wird, bleibt sie im Nur-Lese-Modus.

2. TIMELINES_ALLOW_SEND – die Sendesperre

Standardmäßig in beiden Transporten deaktiviert, auch lokal. Selbst wenn Sie Schreibvorgänge aktivieren, bleibt das Senden von Nachrichten blockiert, bis Sie TIMELINES_ALLOW_SEND=1 setzen.

Der Grund ist die Asymmetrie: Ein Label ändern, einen Chat neu zuweisen oder schließen sind interne und reversible Aktionen. Ein WhatsApp an einen Kunden zu senden ist das nicht. Es macht keinen Sinn, dass sie denselben Schalter teilen.

3. confirm=true – die Sperre pro Aufruf

Jedes Senden erfordert zusätzlich zu dem oben Genannten confirm=true, ebenso wie das Löschen einer Datei, das Neukonfigurieren eines Webhooks oder das Entziehen des Zugriffs eines Kollegen. Die Anweisung des Tools ist explizit: Zeigen Sie dem Benutzer zuerst den genauen Empfänger und den genauen Text, und nur mit seiner Zustimmung wird bestätigt.

Jede Ablehnung sagt, welche der drei Sperren sie gestoppt hat.

Authentifizierung des Endpunkts

Das MCP-Protokoll bringt keine eigene Authentifizierung mit. Im http-Modus verlangt dieser Server bei jeder Anfrage Authorization: Bearer <MCP_AUTH_TOKEN> oder das in den Pfad eingebettete Geheimnis (/s/<secreto>/mcp) für die Claude-Connectors. /healthz ist der einzige öffentliche Pfad.

Der Server weigert sich zu starten, wenn MCP_AUTH_TOKEN fehlt oder weniger als 32 Zeichen hat.

Lokal ausführen

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

Beim Start gibt er aus, in welchem Modus er sich befindet:

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

Hinweise zur TimelinesAI-API

Verifiziert gegen die öffentliche Referenz (https://timelines.ai/docs/public-api-reference/overview):

• Basis: https://app.timelines.ai/integrations/api, Auth Authorization: Bearer <tla_...>.

• Die Bodies sind JSON, nicht form-encoded.

• Die Antworten sind verpackt: {"status":"ok","data":{...}}. Und es gibt Fehler, die mit HTTP 200, aber status:"error" ankommen – dieser Server behandelt sie als Fehler, nicht als Erfolg, denn sonst würde ein fehlgeschlagener Versand als gesendet gelesen.

• Die Fehler enthalten Details pro Feld: {"status":"error","message":..., "error_code":...,"errors":[{"fields":["phone"],"msg":"..."}]}. Sie werden im Fehlertext unverändert angezeigt.

• Mehrwertige Filter werden durch Kommas getrennt in einem einzigen Parameter (label=vip,enterprise), nicht wiederholt und nicht mit eckigen Klammern. Eine Python-Liste zu übergeben erzeugt diese Form.

• Die Seitengröße ist fest auf 50 und kann nicht geändert werden. Verifiziert gegen die Live-API am 2026-08-25: limit, per_page, page_size, size, count, take und rows werden alle ignoriert, und jede Seite kommt mit 50 Datensätzen. Der einzige Parameter, der etwas bewirkt, ist page, und has_more_pages in der Antwort sagt, ob es eine weitere gibt. Deshalb exponieren die Tools kein per_page: Es wäre ein Parameter, der vorgibt zu justieren und nichts justiert.

• Um die Größe einer Antwort zu reduzieren, bleibt also nicht, die Seite zu verkleinern: Man muss mehr filtern oder fields verwenden, um nur die benötigten Schlüssel zu behalten. Nachrichten sind der Fall, der es am meisten verlangt – ein Chat mit 50 Nachrichten überschreitet das Zeichenlimit problemlos. fields=["uid","text","from_me","timestamp"] lässt das Wesentliche einer Konversation in einem Bruchteil der Größe.

• Achtung bei wiederholten Feldnamen: Ein Nachrichtendatensatz bringt seinen eigenen Schlüssel data (ein Metadaten-Dict) mit, zusätzlich zum data der Hülle. Deshalb entscheidet fields, was nach Position beschnitten wird (was in einer Liste steht, ist ein Datensatz) und nicht nach dem Namen des Schlüssels.

• Telefonnummern sind im internationalen Format mit +: +5215512345678. Das Modell validiert sie, bevor es ins Netz geht, und entfernt Leerzeichen und Bindestriche.

• text hat ein Limit von 2000 Zeichen; Labels 64, Chatnamen 256.

• Wenn du whatsapp_account_phone weglässt, sendet TimelinesAI vom zuletzt verbundenen Konto – das selten das ist, das der Benutzer im Kopf hat. Bei mehr als einer verbundenen Nummer ist es ratsam, explizit zu sein.

• Die Sendungen werden ~2 Sekunden voneinander entfernt gesendet, gemäß der WhatsApp-Richtlinie, und jede Nachricht verbraucht Credits (1 Text, 2 mit Anhang; fehlgeschlagene werden erstattet).

• Es gibt drei verschiedene Limits, die man nicht verwechseln sollte:

  Limit	Wert	Gilt für
  Anfrage-Rate	50 pro Minute pro Workspace	Alles, einschließlich Lesevorgänge
  Monatliches Volumen	200,000 Aufrufe pro Monat	Alles
  Nachrichten-Kontingent	je nach Plan (Credits)	Nur Sendungen

  Das erste ist das, was zubeißt: Überschreiten gibt 429 rate_limit_exceeded mitten in der Arbeit, nicht am Anfang.

  Der Server verteidigt sich auf zwei Ebenen, beide auf der Anfrageebene, damit alle Tools abgedeckt sind, nicht nur die, die paginieren:

  1. Gemeinsames Tempo. Die Aufrufe werden im Abstand von 1,2 s zueinander gesendet (60÷50). Ein einzelner Aufruf wartet nichts; die Verzögerung erscheint nur bei Bursts, was genau der Fall ist, der das Limit trifft. Das Limit gilt pro Workspace und alle Tools teilen sich eines, also ist der Taktgeber auch einzigartig.

  2. Wiederholung mit Retry-After. Ein 429 bei einem Lesevorgang wird einmal wiederholt, wobei genau das gewartet wird, was der Server verlangt. Ein Senden wird nie automatisch wiederholt: Eine Nachricht, die vielleicht gesendet wurde, wird nicht aus Bauchgefühl wiederholt.

  timelines_activity_summary gibt außerdem zurück, was es zählen konnte, mit einem Hinweis stopped_early, wenn es trotzdem abgeschnitten wird. Für Fragen nach Personen ist es besser zu filtern (responsible=alguien@...) statt Seiten zu scannen: eine Anfrage statt zwanzig. Höhere Limits können per E-Mail an hello@timelines.ai angefordert werden.

• Es gibt keinen Aggregations-Endpunkt. Deshalb paginiert timelines_activity_summary und zählt auf der MCP-Serverseite und meldet mit complete=false, wenn die Zählung nicht bis zum Ende kam.

Sicherheit

• Geheimnisse kommen in Umgebungsvariablen, nie in den Code. Die .gitignore blockiert .env-Dateien.

• Ein TimelinesAI-Token gewährt Zugriff auf den gesamten Workspace: alle WhatsApp-Konversationen des Teams, mit ihren Telefonnummern und Inhalten. Es sind echte Kundendaten – behandeln Sie sie entsprechend.

• Ein einzelnes geteiltes Token bedeutet null Rückverfolgbarkeit pro Person.

• Um den Zugriff sofort zu unterbrechen: Widerrufen Sie das Token im TimelinesAI-Dashboard – der Server wird sofort unbrauchbar.