mcp-redmine

Ein Model Context Protocol-Server, der Claude (Desktop oder Code) – oder jeden anderen MCP-Client – über seine REST-API mit einer Redmine-Instanz verbindet.

Er stellt 73 Werkzeuge bereit, die praktisch die gesamte stabile Redmine-REST-API abdecken: Vorgänge, Beziehungen, Projekte, Mitgliedschaften, Versionen, Kategorien, Benutzer, Gruppen, Rollen, Wiki, Zeiterfassung, Anhänge, Projektdateien, Neuigkeiten und Suche. Richten Sie Ihren Agenten auf ein Redmine-Projekt und lassen Sie ihn Vorgänge lesen und verwalten, Zeit erfassen, Wiki-Seiten bearbeiten und Benutzer verwalten – alles durch natürliche Konversation.

Funktionen

• Vollständige Lese-/Schreibabdeckung von Vorgängen, einschließlich Massenaktualisierungen, Beziehungen, Beobachtern und Kommentaren.

• Projektverwaltung: Projekte erstellen/aktualisieren/archivieren, Mitglieder, Versionen und Kategorien verwalten.

• Benutzer- und Gruppenverwaltung, bewusst ohne „Benutzer löschen“- oder „Projekt löschen“-Werkzeug – siehe Sicherheit.

• Wiki, einschließlich verschachtelter Seiten und Dateianhänge.

• Zeiterfassung, Anhänge, Projektdateien, Neuigkeiten und Volltextsuche.

• Lesbare Fehler: Jeder Fehler wird als klarer Satz aus Redmines eigener Validierungsantwort zurückgegeben, nicht als roher Stacktrace.

• Nichts zu betreiben: Ein einzelner Python-Prozess, der über stdio mit Ihrem MCP-Client spricht – keine Datenbank, kein zu hostender Server, kein Docker erforderlich.

Related MCP server: redmine-mcp

Voraussetzungen

• Python 3.10+

• Eine Redmine-Instanz mit aktivierter REST-API:

  1. Gehen Sie in Redmine zu Administration → Einstellungen → API und aktivieren Sie „REST-Webservice aktivieren“ (falls nicht bereits aktiviert).

  2. Gehen Sie zu Mein Konto → API-Zugriffsschlüssel und kopieren Sie den Wert.

Installation

Die Distribution wird als mcp-redmine-rest veröffentlicht, und der Befehl, den sie installiert, ist mcp-redmine-rest. Der kürzere Name mcp-redmine auf PyPI gehört zu einem unabhängigen Projekt – installieren Sie nicht dieses, wenn Sie diesen Server erwarten.

Wenn Sie einen KI-Agenten auf dieses Repository verweisen, um die Einrichtung für Sie durchzuführen, ist llms-install.md genau dafür geschrieben.

Mit uv (empfohlen)

uv tool install mcp-redmine-rest

Mit pip

pip install mcp-redmine-rest

Aus dem Quellcode

git clone https://github.com/alsimoes/mcp-redmine-rest.git
cd mcp-redmine-rest

python3 -m venv venv && source venv/bin/activate    # Linux/Mac

pip install -e .

Unter Windows verwenden Sie py und PowerShell anstelle einer Git-Bash/WSL-Shell – das Erstellen oder Neuerstellen der venv aus einer Unix-ähnlichen Shell unter Windows überschreibt venv\pyvenv.cfg mit einem Unix-home-Pfad, und jeder spätere Start von venv\Scripts\python.exe schlägt mit No Python at '/usr/bin\python.exe' (oder ähnlich) fehl:

git clone https://github.com/alsimoes/mcp-redmine-rest.git
cd mcp-redmine-rest

py -3 -m venv venv
.\venv\Scripts\Activate.ps1

pip install -e .

Konfiguration

Der Server liest seine Konfiguration aus Umgebungsvariablen:

Den Schlüssel aus der Client-Konfiguration heraushalten

Fehlende Werte in der Umgebung werden aus einer .env-Datei gelesen, sodass der API-Schlüssel nicht im Klartext in der Konfiguration Ihres MCP-Clients stehen muss. Kopieren Sie .env.example in .env im Repository-Stammverzeichnis und füllen Sie es aus – jede Variable in der obigen Tabelle wird berücksichtigt, sodass der env-Block des Clients vollständig weggelassen werden kann:

REDMINE_URL=https://redmine.example.com
REDMINE_API_KEY=your_api_key_here
REDMINE_TIMEOUT=15

Die Datei ist gitignored. Bereits in der Umgebung vorhandene Variablen gewinnen immer, sodass ein env-Block in der Konfiguration Ihres Clients sie weiterhin überschreibt. Um die Datei woanders zu speichern, setzen Sie REDMINE_ENV_FILE auf ihren vollständigen Pfad.

Dies ist besonders bei Claude Desktop wichtig: Es startet MCP-Server mit einer minimalen Umgebung, die es selbst erstellt, sodass Variablen, die Sie in Ihrer Shell exportieren oder mit setx setzen, den Server nie erreichen. Verwenden Sie den env-Block oder eine .env-Datei.

Claude Desktop

Bearbeiten (oder erstellen) Sie die Konfigurationsdatei von Claude Desktop:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "redmine": {
      "command": "mcp-redmine-rest",
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Wenn Sie aus dem Quellcode statt über uv tool install / pip install installiert haben, zeigen Sie mit command auf den Interpreter in Ihrer virtuellen Umgebung und übergeben Sie das Skript als Argument:

{
  "mcpServers": {
    "redmine": {
      "command": "/full/path/to/mcp-redmine/venv/bin/python",
      "args": ["-m", "mcp_redmine"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Unter Windows zeigen Sie mit command auf venv\Scripts\python.exe (mit \\ in JSON maskiert):

{
  "mcpServers": {
    "redmine": {
      "command": "C:\\full\\path\\to\\mcp-redmine\\venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_redmine"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Starten Sie Claude Desktop danach neu. Das Werkzeuge-Symbol (🔨) sollte die Redmine-Werkzeuge als verfügbar anzeigen.

Claude Code

claude mcp add redmine \
  --env REDMINE_URL=https://redmine.example.com \
  --env REDMINE_API_KEY=your_api_key_here \
  -- mcp-redmine-rest

Bestätigen Sie mit:

claude mcp list

Cline (VS Code)

Öffnen Sie die MCP-Einstellungen über die Palette – Ctrl+Shift+P → Cline: Open MCP Config File – oder klicken Sie auf das Zahnrad neben „MCP Servers“ in der Cline-Seitenleiste und wählen Sie Configure MCP Servers. Beides öffnet cline_mcp_settings.json; fügen Sie den Server dort hinzu:

{
  "mcpServers": {
    "redmine": {
      "command": "mcp-redmine-rest",
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Verwenden Sie den Palettenbefehl anstatt die Datei von Hand zu bearbeiten – sie liegt tief im globalen Speicher von VS Code (.../User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json), und der Pfad unterscheidet sich je nach Plattform.

Wenn mcp-redmine-rest nicht im PATH liegt, den VS Code sieht, verwenden Sie stattdessen die Modulform – "command" zeigt auf den Interpreter, auf dem das Paket installiert ist, mit "args": ["-m", "mcp_redmine"], genau wie in den obigen Claude-Desktop-Beispielen.

Laden Sie das Fenster neu (Ctrl+Shift+P → Developer: Reload Window), und der Server sollte unter „MCP Servers“ als verbunden erscheinen. Eine ausführlichere Anleitung, die die Arbeitsbereichs-.mcp.json und die Add-Server-Oberfläche abdeckt, finden Sie in CLINE_SETUP.md.

Andere MCP-Clients

Jeder Client, der einen lokalen Prozess starten und MCP über stdio sprechen kann, funktioniert auf die gleiche Weise: Führen Sie mcp-redmine-rest (oder python -m mcp_redmine) mit gesetzten REDMINE_URL- und REDMINE_API_KEY-Umgebungsvariablen aus.

Lokal ausführen (optional)

Nützlich für einen schnellen Sanity-Check, bevor Sie den Server in einen Client einbinden:

cp .env.example .env   # then edit .env with your values
export $(grep -v '^#' .env | xargs)   # or use a tool like direnv
mcp-redmine-rest

Wenn kein Verbindungsfehler auftritt, ist der Server bereit – er wartet auf MCP-Nachrichten auf stdin/stdout, sodass es normal ist, wenn im Terminal nichts passiert. Drücken Sie Ctrl+C, um ihn zu stoppen.

Verwendungsbeispiele

Sobald konfiguriert, sprechen Sie einfach mit dem Agenten:

• „Liste die offenen Vorgänge auf, die mir im Projekt Website zugewiesen sind.“

• „Erstelle einen Fehler in Website mit dem Titel ‚Login-Button reagiert nicht auf Mobilgeräten‘, Priorität hoch.“

• „Verschiebe die Vorgänge #101, #104 und #110 auf In Bearbeitung und weise sie Alice zu.“

• „Erfasse 3,5 Stunden für Vorgang #204 für heute, Aktivität Entwicklung.“

• „Was steht auf der Wiki-Seite ‚Deployment‘ für das Projekt Infra?“

• „Suche nach ‚timeout‘ über alle Projekte.“

Verfügbare Werkzeuge

73 Werkzeuge, gruppiert nach Ressource. Die vollständige Referenz – Signaturen, Parameter, Rückgabeform und die wichtigen Hinweise (wie dass precedes Vorgänge neu plant oder dass list_custom_fields einen Administrator erfordert) – finden Sie in docs/TOOLS.md.

API-Abdeckung

Die beiden Auslassungen sind beabsichtigt. delete_project und delete_user sind irreversibel und ziehen den Inhalt anderer Personen mit sich — Issues, Zeiteinträge, Wiki-Seiten, Autorenschaft. archive_project und update_user mit status=3 decken den realen Anwendungsfall reversibel ab. Das tatsächliche Löschen bleibt eine Web-UI-Operation, bei der die Bestätigung explizit und menschlich ist. Siehe SECURITY.md für die vollständige Begründung.

Trackers, Issue-Status, Prioritäten und Rollen haben in der Redmine-API keine Schreiboperationen — sie sind nur in der Administration konfigurierbar. Das ist keine Lücke in diesem Server.

Außerhalb der stabilen REST-API und damit außerhalb des Anwendungsbereichs dieses Servers liegen: Repositorys und Changesets, Wiki-Seitenschutz und instanzweite Einstellungsbildschirme.

Fehlermeldungen

Fehler werden zentral behandelt: Wenn Redmine einen Aufruf ablehnt, liest der Server den Antworttext — dort steht die eigentliche Erklärung im errors-Feld — und gibt diesen Satz zurück. Ohne einen brauchbaren Text fällt er auf den HTTP-Status mit einem wahrscheinlichen Grund zurück:

Dies gilt für jedes Tool, ob lesend oder schreibend.

Fehlerbehebung

• „REDMINE_URL und REDMINE_API_KEY müssen gesetzt sein“: Der Server prüft seine Konfiguration beim Start und beendet sich sofort mit dieser Meldung, anstatt defekt zu starten. Überprüfen Sie den env-Block in der Konfiguration Ihres MCP-Clients.

• Jeder Aufruf schlägt mit einem Netzwerkfehler fehl: Stellen Sie sicher, dass der Serverprozess tatsächlich REDMINE_URL erreichen kann — MCP-Clients führen den Server als lokalen Prozess aus, daher benötigt er denselben Netzwerkzugriff wie Ihr Rechner, nicht der Browser.

• 401 bei jedem Aufruf: Der API-Schlüssel ist falsch, oder „REST-Webservice aktivieren“ ist in den Redmine-Einstellungen deaktiviert.

• 403 bei einem bestimmten Tool: Meistens fehlt eine Berechtigung für die Rolle des Benutzers, dem der API-Schlüssel gehört. get_role zeigt genau, welche Berechtigungen eine Rolle hat.

• Ein Tool antwortet mit 404, obwohl Sie es erwarten würden: Einige Endpunkte (update_journal_note, update_news/delete_news, update_attachment) wurden in bestimmten Redmine-Versionen hinzugefügt — siehe docs/TOOLS.md für die Mindestversion jedes Endpunkts.

Sicherheit

Siehe SECURITY.md für das vollständige Modell. Kurz gesagt: Ein API-Schlüssel gewährt Zugriff, der dem Benutzer entspricht, dem er gehört. Erstellen Sie daher einen dedizierten Redmine-Benutzer mit einer Rolle, die auf das eingeschränkt ist, was der Agent tun soll, und verwenden Sie den Schlüssel dieses Benutzers — versuchen Sie nicht, den Agenten durch Bearbeiten des Codes dieses Servers einzuschränken.

Datei-Uploads sind deaktiviert, bis Sie REDMINE_UPLOAD_ROOTS setzen. Die drei Tools, die eine lokale Datei hochladen (attach_file_to_issue, attach_file_to_wiki_page, upload_project_file) verweigern standardmäßig jeden Pfad, genau weil ein Agent durch injizierten Inhalt (einen Issue-Kommentar, eine Wiki-Seite) dazu verleitet werden kann, eine Datei hochzuladen, die er nie lesen sollte. Siehe SECURITY.md.

Mitwirken

Siehe CONTRIBUTING.md.

Lizenz

MIT