tsheets-mcp

MCP-Server für TSheets (QuickBooks Time) – Intuits Plattform für Zeiterfassung, Terminplanung und bezahlte Freizeit (PTO). Stellt die vollständige öffentliche TSheets-REST-API v1 als MCP-Tools bereit.

Übersicht

• Zustandsloser HTTP-Dienst. Es werden niemals Anmeldedaten gespeichert – jede Anfrage übermittelt ihr eigenes Zugriffstoken über einen Header, das nur für die Dauer dieser einzelnen Anfrage verwendet wird.

• Unterstützt parallele Anfragen; die Isolierung der Anmeldedaten pro Anfrage erfolgt über Python-contextvars und nicht über eine globale/gemeinsame Client-Instanz.

• Einstiegspunkte: POST /mcp (MCP-Protokoll) und GET /health (Health-Check).

• Standardport: 8080 (konfigurierbar über MCP_HTTP_PORT).

• In der gesamten TSheets-API gibt es keine Pfad-Template-Parameter – jede Kennung (ids, user_id usw.) wird als Query-String-Parameter übergeben, auch bei Abfragen einzelner Ressourcen. Dies ist eine echte Eigenschaft des API-Designs und keine Vereinfachung durch diesen Server.

Related MCP server: Timesheet MCP Server

Umfang

15 Tools, reduziert von einem ursprünglichen 85-Tool-Voll-API-Build (2026-08-04). Die gespeicherte Integrationskonfiguration von MSPbots für diesen Anbieter ruft genau 6 Endpunkte auf (Effective Settings, Jobcodes, Users, Customfielditem User Filters, Timesheets, Custom Fields – alle GET, schreibgeschützt). Gemäß der Scope-Entscheidung „tatsächliche Nutzung + Core-CRUD derselben Kategorie" behält dieser Build genau diese 6 Kategorien vollständig – effective_settings (1, schreibgeschützt, für diese Ressource existieren keine CRUD-Verben), custom_field_item_user_filters (1, ebenso), jobcodes (3: create/retrieve/update), users (3: create/retrieve/update), timesheets (4: create/retrieve/update/delete), custom_fields (3: create/retrieve/update) – insgesamt 15 Tools. Alle anderen Kategorien des ursprünglichen 85-Tool-Builds (Reports, Files, Time Off Requests (+ Entries), Schedule Events (+ Calendars), Reminders, Projects (+ Notes/Activities/Activity Replies/Activity Read Times), Notifications, Locations (+ Maps), Jobcode Assignments, Groups, Estimates (+ Items), Custom Field Items (+ Filters + Jobcode Filters), Geolocations, Timesheets Deleted, Managed Clients, Last Modified, Invitations, Geofence Configs, Current User – 28 Kategorien, ~70 Tools) wurden vollständig entfernt, da sie von MSPbots nicht genutzt werden.

Die Quelldaten für die beibehaltenen Tools wurden ursprünglich durch Klonen des GitHub-Repositorys der TSheets-Dokumentation (https://github.com/tsheetsteam/api_docs) und Parsen jeder Markdown/ERB-Partialdatei pro Endpunkt (source/includes/APIReference/<Category>/_*.md.erb) nach HTTP-Methode, Pfad und Parametertabelle extrahiert – derselbe Ansatz aus strukturierter Extraktion und anschließender Codegenerierung, der auch für andere Anbieter mit großen APIs in diesem Programm verwendet wird (ConnectSecure, Dynu, Jira Data Center, Opsgenie). Falls eine entfernte Kategorie später benötigt wird, kann dieselbe Quelle auf dieselbe Weise erneut geparst werden.

Authentifizierung

TSheets verwendet ein statisches Zugriffstoken, das über den eigenen OAuth-/API-App-Ablauf des Anbieters bezogen wird (siehe den internen KB-Artikel von MSPbots, der in der eigenen Integrationskonfiguration verlinkt ist). Die Integrationskonvention von MSPbots sendet dieses Token als Authorization: Bearer <accessToken>, was dem von TSheets dokumentierten Format entspricht, und dieser Server leitet es genau so weiter.

HEADER: Beschreibung der Autorisierungsparameter

Fehlt der Header, wird 401 zurückgegeben:

{
  "error": "Missing credentials",
  "message": "This server requires the X-TSheets-Access-Token header",
  "required_headers": ["X-TSheets-Access-Token"],
  "optional_headers": []
}

Umgebungsvariablen

MCP-Endpunkt

• POST /mcp – MCP-Protokoll (streambarer HTTP-Transport)

• GET /health – Health-Check, gibt exakt {"status": "ok"} zurück. Dies ist eine reine lokale Prüfung – sie ruft die TSheets-API nicht auf, sodass TSheets-Ausfälle den Container niemals als ungesund markieren.

Fehler und Paginierung

• Tool-Fehler werden als In-Band-JSON-Envelope zurückgegeben (keine ausgelöste Ausnahme und kein Fehler auf Protokollebene): {"error": {"code": "...", "message": "...", "retryable": true|false}}. code ist einer der Werte not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error, abgebildet vom HTTP-Status des Upstreams.

• Ausgehende Aufrufe an die TSheets-API verwenden ein Connect-Timeout von 5s / Read-Timeout von 30s, wiederholen bei 429/5xx bis zu 3 Mal mit gedeckeltem exponentiellem Backoff (unter Beachtung von Retry-After) und nutzen für die gesamte Prozesslebensdauer einen einzigen Verbindungspool.

• Der Parameter limit jedes retrieve_*-Tools hat standardmäßig den Wert 50 und wird auf das von TSheets dokumentierte Maximum von 200 pro Seite begrenzt, wenn ein Aufrufer mehr anfordert (die TSheets-API selbst hat ebenfalls einen Standardwert bzw. ein Maximum von 200, sodass die beiden Obergrenzen hier übereinstimmen).

Tool-Liste

Die Tool-Namen lauten tsheets_<category>_<operation> und leiten sich aus der ## Heading-Überschrift jeder Operation in den Quelldokumenten ab (z. B. „Retrieve Timesheets" in der Kategorie timesheets → tsheets_timesheets_retrieve_timesheets). Mehrere Filterparameter von retrieve sind als „required (unless X, Y, or Z is set)" dokumentiert – eine 1-aus-N-Anforderung, die sich nicht sauber als einzelner zwingend erforderlicher Python-Parameter ausdrücken lässt. Daher werden diese als optional modelliert und die ODER-Bedingung stattdessen im Docstring des jeweiligen Tools ausformuliert. body-Parameter für Create-/Update-Endpunkte werden als generisches dict akzeptiert – die Konvention von TSheets selbst verpackt diese in {"data": [ {...}, ... ]} (Massen-Create/-Update von bis zu 50 Objekten pro Aufruf), pro Tool dokumentiert.

Testbeispiel

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-TSheets-Access-Token: <your-tsheets-access-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "tsheets_jobcodes_retrieve_jobcodes",
      "arguments": {}
    }
  }'

Live-verifiziert (2026-07-30): Ein erster Test-Access-Token stellte sich als abgelaufen heraus (401 invalid_grant, per direktem curl als identisch bestätigt — siehe den Bug-Hinweis unten für das, was dieser Lauf aufgedeckt hat). Ein zweites, frisch ausgestelltes Access-Token wurde anschließend Ende-zu-Ende durch diesen laufenden Server getestet und lieferte echte Kontodaten: tsheets_current_user_retrieve_the_current_user gab den tatsächlichen aktuellen Benutzerdatensatz zurück (Name, Berechtigungen, PTO-Guthaben) sowie ergänzende Jobcode-Daten, und tsheets_jobcodes_retrieve_jobcodes (das einem von MSPbots' eigenen 6 konfigurierten Endpunkten entspricht) lieferte echte Jobcode-Datensätze. Beide bestätigen, dass die vollständige Request-/Auth-/Response-Pipeline korrekt gegen die Live-API funktioniert.

Während des Selbsttests behobener Bug: Der anfängliche _raise_for_status-Fehlerparser nahm an, dass TSheets Fehlerdetails immer als {"error": {"message": "..."}} verschachtelt, aber TSheets liefert bei Authentifizierungsfehlern tatsächlich ein flaches OAuth-Format {"error": "invalid_grant", "error_description": "..."} zurück — der Aufruf von .get() auf den String "invalid_grant" stürzte mit 'str' object has no attribute 'get' ab. Dies wurde mit dem ersten (abgelaufenen) Test-Token erkannt und behoben, bevor dieser Server als fertig betrachtet wurde.

API-Referenz

• Übersicht: https://tsheetsteam.github.io/api_docs/

• Quelle (inkl. offizieller Postman-Collection): https://github.com/tsheetsteam/api_docs

Bekannte Lücken

• Am 2026-08-04 von 85 auf 15 Tools reduziert. Der ursprüngliche Build deckte die gesamte öffentliche API über 34 Kategorien ab, gemäß einer früheren Scope-Entscheidung. Eine spätere Scope-Entscheidung reduzierte dies auf genau die tatsächlich von MSPbots verwendeten 6 Kategorien (alle vollständig behalten — kein kategoriespezifisches Kürzen war nötig, da keine Kategorie mehr als eine Handvoll Tools umfasste) — siehe den Abschnitt „Scope“ oben für die vollständige Liste der 28 entfernten Kategorien (~70 Tools). Falls eine entfernte Kategorie später benötigt wird, können die Quelldokumente (https://github.com/tsheetsteam/api_docs) auf dieselbe Weise neu geparst werden, wie die behaltenen Tools erzeugt wurden.

• tsheets_timesheets_delete_timesheets löscht Timesheet-Datensätze laut der eigenen Dokumentation des Anbieters dauerhaft — als destruktiv/irreversibel behandeln und vor dem Aufruf mit einem Menschen bestätigen. Die anderen behaltenen create/update-Tools verändern ebenfalls echte TSheets-Daten (Jobcodes, Benutzer, benutzerdefinierte Felder).

• One-of-N-„erforderliche“ Filtergruppen sind als alle optional modelliert — mehrere Retrieve-Endpunkte dokumentieren einen Parameter als „erforderlich (sofern nicht X, Y oder Z gesetzt ist)“; dies als echte Einschränkung durchzusetzen, ist in einer einfachen Funktionssignatur nicht ausdrückbar, daher sind alle solche Parameter in der Tool-Signatur optional und die ODER-Anforderung wird stattdessen im Docstring ausdrücklich beschrieben. Aufrufer müssen gemäß der dokumentierten Einschränkung mindestens einen angeben, sonst lehnt die Live-API die Anfrage ab.

• body-Parameter sind untypisiert (dict) statt vollständig modelliert — TSheets' eigene Dokumentation zeigt typspezifische Feldvarianten (z. B. haben „Regular Timesheets“ und „Manual Timesheets“ unterschiedliche Pflichtfelder innerhalb desselben data-Arrays), die sich nicht sauber auf feste typisierte Parameter abbilden lassen; die eigene Referenz des Anbieters (oben verlinkt) dokumentiert das genaue Schema pro Ressource.