Hubstaff MCP Server – Eine produktionsreife Implementierung

Was ist das Model Context Protocol (MCP)?

Das MCP ermöglicht es KI-Assistenten, sich direkt mit externen Tools und Diensten zu verbinden und verwandelt sie damit von passiven Textgeneratoren in aktive Teilnehmer realer Arbeitsabläufe. MCP-Server fungieren als Brücke zwischen KI-Client und externen APIs. Mit dem wachsenden Ökosystem MCP-kompatibler Clients eröffnet ein gut gebauter, produktionsreifer MCP-Server echte Möglichkeiten für KI-gestützte Automatisierung.

Emyoli Hubstaff MCP Server: Open-Source-Integration für Hubstaff

Der Emyoli Hubstaff MCP Server ist ein Open-Source-MCP-Server, entwickelt von Emyoli Technologies. Der Server bietet sowohl Lese- als auch ausgewählte Schreibzugriffe auf die Hubstaff API v2 und ermöglicht es Zeiterfassungsdaten abzufragen, Projekte und Aufgaben zu verwalten, sowie manuelle Zeiteinträge zu erstellen und das alles über sprachliche Interaktion mit einem MCP-kompatiblen KI-Client.

Das Projekt wird unter der MIT-Lizenz veröffentlicht und steht in keiner direkten Verbindung zu Hubstaff. Es handelt sich um die erste Veröffentlichung (v0.1.0, Mai 2026) eines Tools, das von Grund auf als ausgereiftes, wartbares Werkzeug konzipiert wurde.

Das gesamte Open-Source-Projekt sowie Anleitungen zur Einrichtung und Konfiguration finden Sie in unserem GitHub-Repository.

Für wen ist der Hubstaff MCP Server interessant?

Ob Sie bereits Hubstaff nutzen oder einfach mal ausprobieren möchten, was das MCP leisten kann: Dieses Projekt bietet für verschiedene Zielgruppen echten Mehrwert.

Teams und Organisationen, die Hubstaff einsetzen, profitieren sofort vom natürlichsprachlichen Zugriff auf ihre Zeiterfassungsdaten. So können sie problemlos Aktivitäten abfragen, Projekte verwalten und Zeiteinträge erstellen, ohne eine einzige Zeile Code schreiben zu müssen.

Agenturen und Beratungsunternehmen, die mehrere Kundenprojekte in Hubstaff managen, können diesen Server als Grundlage für KI-gestützte Berichte und Projektcontrolling nutzen und damit den manuellen Aufwand beim Zusammenstellen von Daten und Zusammenfassungen erheblich reduzieren.

Entwickler, die mit MCP arbeiten, können dieses Projekt als Referenzimplementierung nutzen. Es geht weit über ein einfaches Tutorial hinaus: Dual-Transport, Docker-Deployment, automatische Token-Rotation, Session-Management, CI und korrektes Secrets-Handling. All das ist in einer echten Codebase umgesetzt, die reale Probleme löst.

Technische Leads und Architekten, die prüfen wollen, ob MCP in ihren Stack passt, finden hier ein konkretes, greifbares Beispiel. Das Protokoll an einer bekannten Workforce-Management-API zu sehen, macht den Aufwand, die Abwägungen und die Möglichkeiten viel besser nachvollziehbar als jedes abstrakte Spezifikationsdokument.

Aufbau des GitHub-Repositories

Das Repository folgt einer klaren, professionellen Struktur mit sauberer Trennung der Zuständigkeiten:

• src/ – der zentrale TypeScript-Quellcode des Servers
• tests/ – Unit-Test-Suite auf Basis von Vitest
• .github/workflows/ – CI-Pipeline-Konfiguration via GitHub Actions
• Dockerfile und docker-compose.yml – vollständige Docker-Unterstützung für stdio- und HTTP-Deployment-Modi
• .env.example – dokumentierte Vorlage für die Umgebungskonfiguration
• CONTRIBUTING.md und SECURITY.md – Community- und Sicherheitsrichtlinien, die zeigen, dass das Projekt auf kollaborative Pflege ausgelegt ist

Die dedizierte Build-Konfiguration (tsconfig.build.json), eine separate Test-Konfiguration (vitest.config.ts) und das Linting-Setup (eslint.config.js mit typescript-eslint) zeigen, dass Wert auf Developer Experience gelegt wird.

Technologie-Stack: TypeScript, Node.js, Docker & MCP SDK

Das Projekt ist hauptsächlich in TypeScript geschrieben, ergänzt durch etwas JavaScript und Dockerfile-Code.
Zum Einsatz kommen folgende Technologien:

• Node.js 20+ als Laufzeitumgebung
• TypeScript mit strengen Kompilierungseinstellungen und separater Build-tsconfig
• @modelcontextprotocol/sdk zur Implementierung des MCP-Protokolls (stdio und HTTP)
• Express für den HTTP-Server-Modus
• Vitest für Unit-Tests
• ESLint mit TypeScript-ESLint für Code-Qualität
• Docker & Docker Compose für containerisiertes Deployment
• GitHub Actions für CI/CD

Kernfunktionen des Hubstaff MCP Servers

Authentifizierung

Der Server unterstützt zwei Authentifizierungsverfahren gegenüber der Hubstaff API:

• Personal Access Tokens (PAT): der empfohlene Weg für die meisten Automatisierungsszenarien. Hubstaff-PATs verhalten sich wie langlebige Refresh Tokens; der Server tauscht sie automatisch gegen kurzlebige Access Tokens aus und übernimmt die Rotation transparent.
• OAuth Refresh Tokens: eine Alternative für Fälle, in denen der OAuth-Login-Prozess bereits außerhalb des Servers abgewickelt wurde.

Stdio und Streamable HTTP

Eine Designentscheidung dieses Projekts ist die Unterstützung von zwei Deployment-Modi:

• Stdio-Transport: Der Server läuft als untergeordneter Prozess und kommuniziert mit dem MCP-Client über Standard-Input/Output. Das ist das klassische Integrationsmuster für Clients wie Cursor und Claude Desktop, die den Server direkt auf demselben Rechner (als localhost) starten.
• Streamable HTTP-Transport: Der Server läuft als eigenständiger HTTP-Service (Standard-Port 3333), stellt /mcp für MCP-Clients und /health für Readiness-Checks bereit. Dieser Modus eignet sich ideal für Docker-basierte Deployments, Remote-VMs oder Setups, bei denen ein persistenter Server bevorzugt wird.

Die Docker-Compose-Konfiguration des Projekts behandelt beide Modi explizit mit separaten Service-Profilen. Dies ist ein praktisches Detail, das Verwirrungen rund um stdio vs. TCP beim Containerisieren von MCP-Servern vermeidet.

Verfügbare Hubstaff-API-Tools über MCP

Der Server stellt insgesamt 20 Tools bereit, die die am häufigsten benötigten Hubstaff-Operationen abdecken

Leseoperationen

• Abrufen des Profils des authentifizierten Nutzers (hubstaff_whoami)
• Auflisten von Organisationen, Projekten, Mitgliedern, Teams, Aufgaben und Job-Sites
• Abfragen von Aktivitäten (detaillierte und täglich aggregierte Ansichten)
• Zugriff auf Stundenzettel und Screenshots
• Abrufen einzelner Nutzerdetails
• Ein abgesicherter generischer GET-Escape-Hatch (hubstaff_api_get), der auf die Pfadpräfixe organizations/* und users/* beschränkt ist, für sichere Ad-hoc-Abfragen

Schreiboperationen

• Erstellen und Löschen manueller Zeiteinträge
• Löschen von Aktivitätssegmenten
• Erstellen und Aktualisieren von Projekten
• Erstellen von Aufgaben

Destruktive Operationen sind in den Tool-Beschreibungen explizit gekennzeichnet – eine sinnvolle Sicherheitsmaßnahme, wenn diese Tools von einem KI-Agenten ausgeführt werden.

HTTP Session-Management und Stabilität

Der HTTP-Transport beinhaltet durchdachte Session-Management-Verhaltensweisen, die es wert sind, hervorgehoben zu werden:

• Sessions werden im Arbeitsspeicher gehalten. Ein Neustart des Containers löscht sie, aber der Server akzeptiert einen neuen initialize-Aufruf selbst mit einer verälteten Session-ID und schließt vorherige Sessions sauber ab.
• Ein Single-Session-Fallback ist standardmäßig aktiv: Existiert nur eine aktive Session, werden Anfragen mit fehlender oder verälterter Session-ID automatisch dorthin geleitet – das eliminiert den typischen „No valid session ID provided“-Fehler, wenn Clients den falschen Header cachen oder verlieren.
• Für strengere Multi-Client-Szenarien lässt sich dieser Fallback per MCP_HTTP_STRICT_SESSIONS=1 deaktivieren.
• POST-Antworten an /mcp liefern standardmäßig JSON statt SSE-umhüllte Antworten, was dem Streamable-HTTP-Client von Cursor entspricht und Session-Verluste nach dem ersten Round-Trip verhindert.

Konfiguration über Umgebungsvariablen

Die gesamte Konfiguration erfolgt über Umgebungsvariablen, was die Integration in jede Deployment-Umgebung unkompliziert macht. Der vollständige Variablensatz ist im README dokumentiert und umfasst Token-Credentials, API-Base-URL-Überschreibungen, Transport-Auswahl und HTTP-Binding-Optionen. Ein wichtiges Detail: Das Dockerfile ist so gestaltet, dass .env-Dateien niemals in das Image eingebaut werden – Credentials werden zur Laufzeit über Docker Compose injiziert, was der korrekten Vorgehensweise beim Secrets-Management entspricht.

Eine produktionsreife Grundlage für Hubstaff und MCP

Der Emyoli Hubstaff MCP Server ist ein durchdachter, produktionsorientierter MCP-Server, der über eine Minimalimplementierung weit hinausgeht. Die Dual-Transport-Modi, das sorgfältige Secrets-Management, das überlegte Session-Handling, die umfassende Tool-Abdeckung und das solide Developer-Tooling spiegeln die Art von Engineering-Disziplin wider, die man von einer Komponente in einem agentischen Workflow erwartet.
Für Teams, die Hubstaff-Daten in ihre KI-gestützten Workflows einbinden möchten, ist dies eine starke Ausgangsbasis. Das Projekt ist Open Source und verfügbar auf github.com/evirachmi/emyoli-mcp-hubstaff.