OpenProject MCP Server

Ein hochwertiger Model Context Protocol (MCP)-Server, um Claude mit deiner OpenProject-Instanz zu verbinden. Er ermöglicht Claude, Projekte, Work Packages, Benutzer und Zeiteinträge direkt aus Gesprächen heraus abzufragen, zu durchsuchen und zu verwalten.

🚀 Funktionen

✅ Projektzugriff – Projekte auflisten, filtern und Details abrufen
✅ Work-Package-Verwaltung – Aufgaben, Bugs, Features mit erweiterter Filterung anzeigen
✅ Volltextsuche – Work Packages nach Inhalt durchsuchen
✅ Aktivitätsverlauf – Änderungen und Kommentare an Work Packages einsehen
✅ Benutzerverwaltung – Benutzer auflisten und Informationen abrufen
✅ Zeiteinträge – Registrierte Zeiten nach Projekt, Benutzer, Zeitraum abfragen
✅ Intelligente Paginierung – Unterstützung für große Datensätze
✅ Robuste Fehlerbehandlung – Klare und umsetzbare Meldungen
✅ Vollständige Typisierung – TypeScript für maximale Typsicherheit

Related MCP server: OpenProject MCP Server

📋 Voraussetzungen

• Node.js 18+ oder Bun 1.0+

• Eine OpenProject-Instanz 13+ mit API-Zugang

• Ein API-Token von OpenProject (in den Einstellungen generierbar)

🔧 Installation

1. Server klonen oder herunterladen

cd openproject-mcp-server

2. Abhängigkeiten installieren

npm install
# o con bun
bun install

3. Umgebungsvariablen konfigurieren

Kopiere .env.example nach .env und fülle die Werte aus:

cp .env.example .env

Bearbeite .env:

OPENPROJECT_URL=https://openproject.empresa.com
OPENPROJECT_API_TOKEN=tu-token-api-aqui
OPENPROJECT_PAGE_SIZE=50

So erstellst du einen API-Token in OpenProject:

1. Gehe in OpenProject zu Administration → API & Webhooks → Personal Access Tokens

2. Klicke auf „+ New Personal Access Token"

3. Vergib einen beschreibenden Namen (z. B. „Claude MCP")

4. Markiere die erforderlichen Berechtigungen:

   • ✅ view_work_packages

   • ✅ view_projects

   • ✅ view_users

   • ✅ view_time_entries

   • ✅ edit_work_packages (falls du erstellen/bearbeiten möchtest)

5. Kopiere das generierte Token in .env

4. Server kompilieren

npm run build

🎯 Verwendung

Option A: In Claude Code

1. Öffne Claude Code

2. Gehe zu Settings → MCP Servers

3. Klicke auf + Add Local Server

4. Konfiguriere:

   • Name: openproject

   • Command: node

   • Arguments: ["path/to/openproject-mcp-server/dist/index.js"]

   • Environment Variables: Die Werte aus .env

5. Speichern und zu Claude neu verbinden

Option B: Lokal zum Testen ausführen

npm run dev

Verwende dann in einem anderen Terminal den MCP Inspector:

npm run inspect

Dadurch wird eine Weboberfläche geöffnet, in der du jedes Tool testen kannst.

Option C: In Claude.ai

1. Öffne claude.ai/code

2. Gehe zu Settings → MCP Servers

3. Füge einen Remote-Server hinzu, falls du diesen Server auf einem erreichbaren Host bereitgestellt hast

4. Konfiguriere Zugangsdaten

🛠️ Verfügbare Tools

📦 Projekte

list_projects

Listet alle Projekte mit optionaler Filterung auf.

Parameter:

• offset (number, optional): Für Paginierung

• name_filter (string, optional): Nach Namen filtern

• status (enum: "active" | "archived", optional): Nach Status filtern

Beispiel:

Claude: List all active projects
→ OpenProject: Muestra proyectos activos

get_project

Ruft vollständige Details eines Projekts ab.

Parameter:

• project_id (string | number): ID oder Kennung des Projekts

📋 Work Packages (Aufgaben)

list_work_packages

Listet Work Packages mit erweiterter Filterung auf.

Parameter:

• project_id (string | number, optional): Nach Projekt filtern

• status (string, optional): Status (z. B. "Open", "In Progress")

• priority (string, optional): Priorität

• assignee_id (number, optional): Zugewiesen an Benutzer

• search (string, optional): Textsuche

• offset (number, optional): Paginierung

get_work_package

Ruft vollständige Details eines Work Packages ab.

Parameter:

• work_package_id (number): ID des Work Packages

get_work_package_activities

Ruft den Verlauf von Änderungen und Kommentaren ab.

Parameter:

• work_package_id (number): ID des Work Packages

search_work_packages

Volltextsuche in Work Packages.

Parameter:

• query (string, required): Suchbegriff

• project_id (string | number, optional): Auf Projekt beschränken

• status (string, optional): Nach Status filtern

• priority (string, optional): Nach Priorität filtern

👤 Benutzer

list_users

Listet alle Benutzer in OpenProject auf.

Parameter:

• offset (number, optional): Paginierung

get_user

Ruft Details eines bestimmten Benutzers ab.

Parameter:

• user_id (number): ID des Benutzers

⏱️ Zeiteinträge

list_time_entries

Listet Zeiteinträge mit Filterung nach Zeitraum, Benutzer, Projekt auf.

Parameter:

• work_package_id (number, optional): Nach Work Package filtern

• user_id (number, optional): Nach Benutzer filtern

• project_id (string | number, optional): Nach Projekt filtern

• from_date (string, optional): Startdatum (YYYY-MM-DD)

• to_date (string, optional): Enddatum (YYYY-MM-DD)

• offset (number, optional): Paginierung

get_time_entry

Ruft Details eines Zeiteintrags ab.

Parameter:

• time_entry_id (number): ID des Zeiteintrags

✍️ Schreiben (Epics und User Stories erstellen)

list_project_types

Listet die in einem Projekt verfügbaren Work-Package-Typen (Epic, User Story, Task, Bug...) mit ihrer ID auf. Zuerst verwenden – die Typ-IDs variieren zwischen OpenProject-Instanzen.

Parameter:

• project_id (string | number): ID oder Kennung des Projekts

create_work_package

Erstellt ein Work Package (Epic, User Story, Aufgabe usw.). Verwende parent_id, um eine User Story unter ihr Epic zu hängen.

Parameter:

• project_id (string | number)

• subject (string)

• description (string, optional, Markdown)

• type_id (number, optional): ID des Typs, abgerufen mit list_project_types

• parent_id (number, optional): ID des übergeordneten Epics

• priority_id, assignee_id, start_date, due_date (optional)

create_work_packages_bulk

Erstellt mehrere Work Packages in einem einzigen Aufruf (ideal zum Hochladen aller aus einem Word-Dokument extrahierten User Stories). Jedes Element kann sein eigenes parent_id haben, sodass Stories aus verschiedenen Epics im selben Aufruf erstellt werden können. Gibt einen Bericht pro Element zurück (Erfolg/Fehler) und bricht den gesamten Batch nicht ab, wenn eines fehlschlägt.

Parameter:

• project_id (string | number)

• items (array, max. 100): jedes mit denselben Feldern wie create_work_package (außer project_id)

📋 Ablauf: Epics und User Stories aus Word hochladen

Typischer Anwendungsfall des Teams: Sie haben User Stories in .docx verfasst und müssen sie unter Beachtung der Beziehung Epic → Story in OpenProject laden.

1. Generiere dein persönliches API-Token (jeder Entwickler verwendet sein eigenes, siehe oben) und konfiguriere deine lokale .env.

2. Öffne das Gespräch mit Claude und füge die .docx-Datei mit den Epics/Stories bei oder verweise darauf (Claude kann sie direkt lesen).

3. Bitte Claude: „Lies dieses Word-Dokument, identifiziere die Epics und ihre User Stories und lade sie in Projekt X in OpenProject hoch."

4. Claude wird normalerweise Folgendes tun, ohne dass du es manuell orchestrieren musst:

   • list_project_types für das Projekt ausführen, um die type_id von Epic und User Story zu ermitteln.

   • create_work_package für jedes Epic (wenige, einzeln, um ihre IDs zu erhalten).

   • create_work_packages_bulk für die User Stories, wobei das parent_id des jeweiligen Epics verwendet wird.

5. Überprüfe den Abschlussbericht (was erstellt wurde, was fehlgeschlagen ist) und korrigiere bei Bedarf in OpenProject.

Hinweis: Das Token benötigt die Berechtigung edit_work_packages (siehe Abschnitt zur Token-Erstellung), um erstellen zu können, nicht nur lesen.

📊 Anwendungsfälle

1. Projektanalyse

Claude: "Análiza todos los proyectos activos y resume cuáles tienen más work packages abiertos"
→ El servidor lista proyectos, luego itera para contar paquetes abiertos

2. Aufgabensuche

Claude: "Busca todas las tareas sobre 'API' en estado 'In Progress' del proyecto BACKEND"
→ search_work_packages con query="API", status="In Progress", project_id="BACKEND"

3. Zeitbericht

Claude: "¿Cuántas horas registró Juan en la última semana?"
→ list_time_entries con user_id=juan, from_date=última_semana

4. Projektstatus

Claude: "Dame un resumen del proyecto FRONTEND: qué se completó, qué está en progreso y qué sigue"
→ get_project + list_work_packages con diferentes status

5. Änderungsaudit

Claude: "¿Quién cambió el estado del work package #123 y cuándo?"
→ get_work_package_activities para ver el historial

🏗️ Architektur

src/
├── index.ts                 # Entry point del servidor MCP
├── client/
│   └── openproject.ts       # Cliente HTTP para OpenProject API
├── tools.ts                 # Registro e implementación de herramientas
├── schemas/
│   └── index.ts             # Validación Zod de inputs
└── utils/
    └── formatters.ts        # Formatos de salida Markdown

🔐 Sicherheit

• ✅ Bearer-Token-Authentifizierung (sicher, keine Klartext-Zugangsdaten erforderlich)

• ✅ Eingabevalidierung mit Zod (verhindert Injection)

• ✅ Granulare Fehlerbehandlung (gibt keine sensiblen Daten preis)

• ✅ TypeScript Strict Mode (verhindert Typfehler)

• ⚠️ Das Token wird in .env gespeichert – diese Datei niemals in Git committen

🚨 Fehlerbehebung

„Authentication failed"

• Überprüfe, ob das Token in .env gültig ist

• Generiere ein neues Token in OpenProject

„Connection error"

• Überprüfe, ob OPENPROJECT_URL von deinem Rechner aus erreichbar ist

• Wenn du Proxy/VPN verwendest, konfiguriere die Proxy-Umgebungsvariablen

„No projects found"

• Überprüfe, ob dein Benutzer Berechtigungen zum Anzeigen von Projekten hat

• Überprüfe, ob in deiner Instanz Projekte existieren

Server startet nicht

npm run build
npm run dev

Überprüfe die Fehlerausgabe im Terminal.

📈 Geplante Verbesserungen

• Unterstützung zum Erstellen/Bearbeiten von Work Packages über Claude

• Unterstützung für Kommentare an Work Packages

• Integration mit Gantt-Diagrammen

• Webhooks für Echtzeit-Benachrichtigungen

• Daten-Cache für bessere Leistung

• Umfassende Evaluierungen (SEP)

📦 Verteilung an dein Entwicklungsteam

Jeder Entwickler benötigt seine eigene Kopie + sein eigenes API-Token (niemals ein Token zwischen mehreren Personen teilen – Aktionen werden in OpenProject pro Benutzer protokolliert).

Empfohlene Option: gemeinsames Git-Repository

1. Lade diesen Ordner in ein privates Repository hoch (GitHub-Org oder das Gitea/GitLab von linux.ie). Vergiss nicht, dass .env bereits in .gitignore steht – es wird niemals hochgeladen.

2. Jeder Entwickler:

   git clone <url-del-repo>
   cd openproject-mcp-server
   npm install
   npm run build
   cp .env.example .env

3. Jeder generiert sein eigenes Token (Administration → API & Webhooks → Personal Access Tokens, mit Berechtigung edit_work_packages, falls Stories erstellt werden sollen) und fügt es in seine .env ein.

4. Jeder fügt es in Claude Code hinzu (Settings → MCP Servers → Add Local Server), das auf sein lokales dist/index.js verweist.

Alternative ohne Git: komprimierter Ordner

Falls du das Repository noch nicht einrichten möchtest, kannst du ein .zip des Ordners teilen (ohne node_modules, dist und .env) und jeder Entwickler führt lokal npm install && npm run build aus. Es ist dieselbe Mechanik, nur das Verteilungsmedium ändert sich – es ist kein CI/CD erforderlich, da es keinen zentralen Server zum Bereitstellen gibt: Das MCP läuft über stdio auf dem Rechner jedes Entwicklers.

Falls du es später als gemeinsamen Remote-Server betreibst

Falls du statt lokalem Betrieb durch jeden Entwickler einen einzigen Server bevorzugst (z. B. auf linux.ie), den alle nutzen, dann gilt CI/CD (Build + Deploy bei jedem Push) und der Transport müsste von stdio auf HTTP migriert werden. Das ist ein größerer Architekturwechsel – sag mir Bescheid, falls das der Weg ist, den du gehen möchtest, und wir planen es separat.

🤝 Beitragen

Dies ist ein Open-Source-MCP-Server. Zur Verbesserung:

1. Forke das Repository

2. Erstelle einen Branch für dein Feature (git checkout -b feature/mein-feature)

3. Committe Änderungen (git commit -am 'Füge mein-feature hinzu')

4. Pushe den Branch (git push origin feature/mein-feature)

5. Öffne einen Pull Request

📄 Lizenz

MIT – Verwende, modifiziere und verbreite es frei

💬 Support

Zum Melden von Bugs, Stellen von Fragen oder Abgeben von Vorschlägen:

• Öffne ein Issue im Repository

• Konsultiere die MCP-Dokumentation

• Sieh in die OpenProject-API-Dokumentation

Erstellt mit ❤️ für Integral de Empaques S.A.S.