Hubstaff MCP Server

Ein Remote-MCP-Server (read-only) für die Hubstaff Time Tracking API v2 und die Hubstaff Tasks API v1. Er stellt Aufgaben, aktuelle Änderungen, Kommentare und aggregierte Zeiten pro Aufgabe über Streamable HTTP bereit.

Der Server enthält einen integrierten OAuth-2.1-Authorization-Server für den Entwicklermodus von ChatGPT: DCR, Authorization Code, PKCE S256, audience-gebundene JWT-Zugriffstokens und rotierende Refresh-Tokens.

MCP tools

• hubstaff_list_organizations — verfügbare Organisationen und ihre IDs.

• hubstaff_list_tasks — Aufgaben der Organisation mit Filtern.

• hubstaff_get_task — Details einer Time-Tracking-Aufgabe.

• hubstaff_recent_updates — kürzlich geänderte Aufgaben und Zeiteinträge.

• hubstaff_task_hours — Stunden pro Aufgabe und Aufschlüsselung nach Benutzern.

• hubstaff_tasks_list_projects — Hubstaff-Tasks-Projekte.

• hubstaff_tasks_list_project_tasks — Aufgaben des Projektboards.

• hubstaff_tasks_get_task — Details einer Hubstaff-Tasks-Aufgabe.

• hubstaff_tasks_list_comments — Kommentare zur Aufgabe, sofern der Endpoint für den Tarif und das Token verfügbar ist.

Alle Tools lesen nur Daten.

Related MCP server: timedoctor-mcp

Einrichtung

1. Kopieren Sie .env.example in .env.

2. Geben Sie einen MCP_AUTH_TOKEN mit mindestens 32 Zeichen an.

3. Geben Sie für ChatGPT OAUTH_ISSUER, OAUTH_USERNAME, OAUTH_PASSWORD und OAUTH_SIGNING_SECRET an. Der OAuth-Zustand wird in /data/oauth-state.json gespeichert.

4. Wählen Sie eine der folgenden Optionen für die Hubstaff-Autorisierung:

   • HUBSTAFF_ORGANIZATION_TOKEN (hsoat_...) — die empfohlene Option für einen dauerhaft laufenden Server;

   • HUBSTAFF_REFRESH_TOKEN — ein Personal Access Token, das Hubstaff als Refresh-Token ausgibt;

   • HUBSTAFF_ACCESS_TOKEN — ein temporäres Access-Token.

Für ein PAT sind die Scopes hubstaff:read und tasks:read erforderlich. Hubstaff rotiert das Refresh-Token bei jedem Token-Austausch; der Server speichert das aktuelle Paar atomar in /data/token.json innerhalb eines benannten Docker-Volumes. Der ursprüngliche Schlüssel verbleibt ausschließlich in .env, und .env ist von Git und dem Docker-Build-Kontext ausgeschlossen.

Start:

npm ci
npm run build
npm test
npm start

Docker:

docker compose up -d --build

Verbindung des MCP-Clients

URL:

https://hubstuff-mcp.copperdiver.studio/mcp

Für einen normalen MCP-Client kann ein Service-Header verwendet werden:

Authorization: Bearer <MCP_AUTH_TOKEN>

ChatGPT verbindet sich automatisch über OAuth. Der Server veröffentlicht:

• /.well-known/oauth-protected-resource

• /.well-known/oauth-authorization-server

• /oauth/register, /oauth/authorize, /oauth/token

Aktivieren Sie in ChatGPT Settings → Security and login → Developer mode und fügen Sie dann auf der Plugins-Seite die URL https://hubstuff-mcp.copperdiver.studio/mcp mit OAuth/DCR hinzu. Geben Sie beim ersten Verbindungsaufbau OAUTH_USERNAME und OAUTH_PASSWORD aus der .env des Servers ein.

Erreichbarkeitsprüfung ohne Geheimnis:

curl https://hubstuff-mcp.copperdiver.studio/health

Einschränkungen von Hubstaff

• Die Activity API liefert mit einer einzelnen Anfrage Intervalle von höchstens 7 Tagen; hubstaff_task_hours teilt den Zeitraum selbst in Abschnitte auf.

• Der Verlauf der detaillierten Aktivität ist maximal etwa 6 Monate verfügbar.

• Kommentare gehören zur Hubstaff Tasks API v1 und werden bei manchen Tarifen oder ohne den Scope tasks:read möglicherweise nicht zurückgegeben. In diesem Fall prüft das Tool außerdem die in die Aufgabenantwort eingebetteten Kommentare und gibt eine verständliche Fehlermeldung zurück, anstatt ein leeres Ergebnis zu liefern.

Offizielle Dokumentation: Hubstaff API, authentication, tasks, activities.