kimai-timelog-mcp

Ein MCP-Server, der es Claude (oder jedem MCP-fähigen LLM-Client) ermöglicht, deine Kimai-Zeitnachweise zu lesen und zu schreiben. Du sagst „Erfasse 9 bis 12:30 Uhr für den Portal-Umbau, inklusive Korrektur der Login-Weiterleitung“ und der Eintrag erscheint in Kimai.

Jede Anfrage wird in deinem Namen ausgeführt – sie verwendet dein persönliches Kimai-API-Token und kann daher nur das sehen und ändern, was dein Kimai-Konto darf.

1. Kimai-API-Token besorgen

1. Öffne Kimai → klicke auf deinen Namen (oben rechts) → Mein Profil → Reiter API-Zugriff.

2. Erstelle ein Token, gib ihm einen Namen wie claude, und kopiere es sofort – Kimai zeigt es nur genau einmal an.

Related MCP server: Kimai MCP Server

2. Installation

Du benötigst uv (empfohlen) oder Python 3.10+.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Danach entweder:

A. Aus einem gemeinsamen Ordner / Git-Repo (so machen es Kolleginnen und Kollegen)

uvx --from git+https://github.com/Alpha101Code/kimai-timelog-mcp kimai-mcp --check

B. Aus einer lokalen Kopie

cd /path/to/kimai-timelog-mcp
uv run kimai-mcp --check

--check überprüft die URL und das Token und gibt deine sichtbaren Projekte aus. Setze zuerst die beiden Umgebungsvariablen:

export KIMAI_URL=https://timesheet-sd.maccs.mu
export KIMAI_API_TOKEN=your-token-here

3. In deinen Client einbinden

Claude Desktop

Einstellungen → Entwickler → Konfiguration bearbeiten, dann hinzufügen:

{
  "mcpServers": {
    "kimai": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Alpha101Code/kimai-timelog-mcp", "kimai-mcp"],
      "env": {
        "KIMAI_URL": "https://timesheet-sd.maccs.mu",
        "KIMAI_API_TOKEN": "your-token-here"
      }
    }
  }
}

Starte Claude Desktop neu. Unter Windows verwende uvx.exe, falls uvx nicht im PATH gefunden wird.

Claude Code

claude mcp add kimai \
  --env KIMAI_URL=https://timesheet-sd.maccs.mu \
  --env KIMAI_API_TOKEN=your-token-here \
  -- uvx --from git+https://github.com/Alpha101Code/kimai-timelog-mcp kimai-mcp

Cursor / Windsurf / Cline / Zed

Gleiche JSON-Struktur wie bei Claude Desktop, in der MCP-Konfigurationsdatei des jeweiligen Clients (~/.cursor/mcp.json bei Cursor).

Alles andere

Es ist ein standardmäßiger stdio-MCP-Server. Befehl: kimai-mcp. Konfiguration: die beiden oben genannten Umgebungsvariablen.

Werkzeuge

Wissenswerte Design-Entscheidungen

• Namen, keine IDs. project: "Portal Revamp" funktioniert; ebenso ein eindeutiger Teilstring wie "portal". Bei mehrdeutigen Namen kommt ein Fehler zurück, der die Kandidaten auflistet; das Modell kann sie dir dann als Frage stellen.

• Flexible Zeiteingabe. date: today, yesterday, monday, 3 days ago, 2026-08-24, 25/08/2026. start/end: 09:00, 9am, 5.30pm, 0930. duration: 1h30m, 90m, 1.5h, 1:30.

• Deine Zeitzone. Kimai meldet die Zeitzone des Token-Inhabers; alles wird danach aufgelöst, nicht nach der Server-Uhr.

• Keine erfundenen Stunden. log_time benötigt start+end, start+duration oder duration – wenn nichts davon angegeben ist, gibt es einen Fehler zurück, der das Modell auffordert, dich zu fragen, statt zu raten.

• Löschen erfolgt in zwei Schritten. Der erste Aufruf gibt zurück, was gelöscht würde; erst ein zweiter Aufruf mit confirm: true entfernt es.

Beispiel-Prompts

Log 9:00–12:30 today on Portal Revamp, development, "fixed the login redirect".
What did I log this week? Break it down by project.
Same as yesterday afternoon, but for today.
Start a timer on Internal Tools / Admin.
I forgot Monday — 4 hours on Mobile App, release testing.
Move entry 512 to start at 10:15 instead.

Ausrollen bei Kolleginnen und Kollegen

Alle benötigen drei Dinge: uv installiert, ein eigenes Kimai-Token und den obigen Konfigurationsblock. Zwischen den Nutzern wird nichts geteilt – kein Server, den man betreiben muss, kein zentrales Token.

Falls du später einen einzelnen gehosteten Server anstelle einer Installation pro Maschine möchtest, bleibt die Tool-Ebene unverändert; nur der Transport in __main__.py ändert sich.

Sicherheit

• Das Token ist wie ein Passwort zu behandeln. Es liegt in der Konfigurationsdatei deines Clients auf deinem eigenen Rechner – committe es nicht und füge es nicht in ein gemeinsames Dokument ein.

• Versehe Tokens in Kimai mit einem Ablaufdatum und rotiere sie.

• Der Server kommuniziert nur mit KIMAI_URL. Er hat keinen weiteren Netzwerkzugriff, keinen Dateisystemzugriff und keine Shell.

• Wenn dein Kimai nur intern erreichbar ist, muss dies auf einem Rechner laufen, der es erreichen kann (VPN oder Büronetzwerk).

Entwicklung

src/kimai_mcp/
  client.py     Kimai REST client — auth, errors, name→id resolution, caching
  timeutil.py   parsing for human dates, times and durations
  server.py     the MCP tools
  __main__.py   stdio entrypoint + --check
tests/
  mock_kimai.py a stand-in Kimai instance
  test_e2e.py   drives the real server over stdio against it

Führe die Testsuite aus (keine Kimai-Instanz erforderlich):

uv run --with mcp --with httpx python tests/test_e2e.py

Kompatibilität

Funktioniert mit beiden Hauptversionen des Python-MCP-SDK: mcp 1.x (FastMCP) und 2.x (MCPServer). Der Server wählt beim Import die richtige Version aus, und vorhersehbare Fehler sind Unterklassen des ToolError des SDK, sodass die Meldung das Modell erreicht, statt einer generischen „Fehler beim Ausführen des Tools“. Die Testsuite wird in CI gegen beide ausgeführt.

Die Distribution heißt kimai-timelog-mcp (passend zum Repo); der Befehl, den sie installiert, ist kimai-mcp.

Entwickelt gegen die Kimai-2-REST-API (/api, Authorization: Bearer <token>). Endpunkt-Referenz: https://www.kimai.org/documentation/rest-api.html und /api/doc deiner eigenen Instanz.