@nicola5tor/openproject-timelog

MCP-Server (Model Context Protocol) zum Führen eines lokalen Stundenprotokolls und zum Synchronisieren mit OpenProject (API v3). Erfasse deine Arbeit in natürlicher Sprache über Claude Desktop (oder einen anderen MCP-Client), überprüfe sie und lade sie zu OpenProject hoch, wenn sie fertig ist.

• Transport: stdio

• Lokale Speicherung: ~/.openproject-timelog/entries.json

• Konfiguration: Umgebungsvariablen OPENPROJECT_URL und OPENPROJECT_API_KEY

Installation

Es muss nichts global installiert werden: Der Server wird mit npx ausgeführt.

# probarlo directamente
npx @nicola5tor/openproject-timelog

Oder in einem Projekt installieren:

npm install @nicola5tor/openproject-timelog
# o
pnpm add @nicola5tor/openproject-timelog

Related MCP server: OpenProject MCP Server

Konfiguration in Claude Desktop

Bearbeite die Konfigurationsdatei (claude_desktop_config.json) und füge den Server unter mcpServers hinzu:

{
  "mcpServers": {
    "openproject-timelog": {
      "command": "npx",
      "args": ["-y", "@nicola5tor/openproject-timelog"],
      "env": {
        "OPENPROJECT_URL": "https://tu-openproject.example.com",
        "OPENPROJECT_API_KEY": "TU_API_KEY"
      }
    }
  }
}

Starte Claude Desktop nach dem Speichern neu.

So erhältst du deinen OpenProject-API-Schlüssel

In OpenProject: Mein Konto → Zugriffstokens → API und generiere einen Schlüssel. Der Server authentifiziert sich mit Basic Auth unter Verwendung des Literal-Benutzers apikey und deines Schlüssels als Passwort.

Die nur lokalen Tools (log_entry, list_entries, edit_entry, assign_entry, delete_entry, clear_sent) funktionieren auch ohne OpenProject-Konfiguration. Die Abfrage- und Upload-Tools erfordern OPENPROJECT_URL und OPENPROJECT_API_KEY.

Tools

Lokales Protokoll

OpenProject abfragen

Synchronisierung

* = erforderlich.

Verhaltenshinweise

• Lokale IDs sind UUID v4. Die Stunden werden als Dezimalzahl gespeichert (1.5 = 1h30m) und beim Hochladen in die ISO-8601-Dauer (PT1H30M) umgewandelt.

• Die projectId eines Eintrags wird, falls nicht angegeben, beim Hochladen vom Arbeitspaket abgeleitet (ein zusätzlicher Aufruf an OpenProject).

• Die JSON-Datei wird atomar geschrieben (temporäre Datei + Umbenennung) und die Operationen werden serialisiert, um Beschädigungen zu vermeiden.

• Netzwerk-/Anmelde-/Berechtigungsfehler werden als lesbare Meldungen in der Tool-Antwort zurückgegeben, ohne den Server zu beenden.

Beispiele für die Konversationsnutzung

Du: Erfasse heute 2 Stunden für die Behebung des Logins, Aufgabe 1234. Claude: (ruft log_entry mit description="Login reparieren", hours=2, workPackageId=1234 auf)

Du: Trag mir 45 Minuten Besprechung ein, die Aufgabe weise ich später zu. Claude: (log_entry description="Besprechung", hours=0.75) — bleibt bis zur Zuweisung offen.

Du: Was habe ich noch nicht hochgeladen? Claude: (list_entries status="pending")

Du: Weise diesen beiden Besprechungen Aufgabe 1234 zu. Claude: (assign_entry entryIds=[...], workPackageId=1234)

Du: Welche Aktivitäten gibt es? Setz überall "Development" ein und lade es hoch. Claude: (get_activities → edit_entry/assign für activityId → upload_entries)

Du: Bereinige, was bereits hochgeladen wurde. Claude: (clear_sent)

Entwicklung

npm install      # instala deps y compila (prepare -> build)
npm run build    # compila TypeScript a dist/
npm start        # ejecuta dist/index.js

Struktur:

openproject-timelog/
├── src/
│   ├── index.ts        # entry point, setup MCP y registro de tools
│   ├── store.ts        # CRUD bitácora local (JSON atómico)
│   ├── openproject.ts  # cliente API OpenProject v3
│   └── types.ts        # interfaces/types
├── package.json
├── tsconfig.json
└── README.md

Lizenz

MIT