MCP Jira-Integration

Ein einfacher Model Context Protocol (MCP)-Server für Jira, der es LLMs ermöglicht, als Projektmanager und persönliche Assistenten für Teams zu fungieren, die Jira nutzen. Basiert auf der Jira REST API v3.

Funktionen

Zentrale MCP-Tools

• create_issue - Erstellen neuer Jira-Vorgänge mit korrekter Formatierung und ADF-Beschreibungen

• search_issues - Suchen von Vorgängen mittels JQL mit intelligenter Formatierung und Paginierung

• get_sprint_status - Abrufen umfassender Sprint-Fortschrittsberichte mit Metriken

• get_team_workload - Analysieren der Arbeitslast und Kapazität von Teammitgliedern

• generate_standup_report - Automatisches Erstellen täglicher Standup-Berichte

Projektmanagement-Funktionen

• Multi-Projekt-Unterstützung: Arbeiten mit mehreren Projekten durch dynamische Angabe von Projektschlüsseln

• Sprint-Fortschrittsverfolgung mit visuellen Indikatoren

• Analyse der Team-Arbeitslast und Kapazitätsplanung

• Automatisierte Erstellung täglicher Standup-Berichte

• Erstellung von Vorgängen mit korrekter Priorisierung

• Intelligente Suche und Filterung von Vorgängen

Zuverlässigkeit

• Automatischer Wiederholungsversuch mit exponentiellem Backoff bei Ratenbegrenzungen (429) und vorübergehenden Fehlern (503)

• Paginierung für große Ergebnismengen

• Zeitzonenbewusste Datumsverarbeitung

• Fehlertoleranter Umgang mit benutzerdefinierten Jira-Status und Vorgangstypen

Related MCP server: JIRA MCP Server

Anforderungen

• Python 3.8 oder höher

• Jira Cloud-Konto mit API-Token

• MCP-kompatibler Client (wie Claude Desktop)

Schnelleinrichtung

1. Klonen und installieren:

git clone https://github.com/your-org/mcp-jira.git
cd mcp-jira
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Jira-Anmeldedaten konfigurieren:

cp .env.example .env
# Edit .env with your values

JIRA_URL=https://your-domain.atlassian.net
JIRA_USERNAME=your.email@domain.com
JIRA_API_TOKEN=your_api_token
PROJECT_KEY=PROJ
DEFAULT_BOARD_ID=123

3. Server testen:

.venv/bin/python -m mcp_jira

Sie sollten Initializing MCP Jira server... in der Ausgabe sehen. Drücken Sie Strg+C zum Beenden.

Anwendungsbeispiele

Vorgänge erstellen

"Erstelle einen Bug mit hoher Priorität für das Login-System, das nicht richtig funktioniert"

• Weist automatisch den richtigen Vorgangstyp, die Priorität und die Formatierung zu

Sprint-Management

"Was ist unser aktueller Sprint-Status?"

• Ruft einen umfassenden Fortschrittsbericht mit Metriken und visuellen Indikatoren ab

Team-Management

"Zeige mir die Arbeitslast des Teams für john.doe, jane.smith, mike.wilson"

• Analysiert die Kapazität und liefert die Verteilung der Arbeitslast

Tägliche Standups

"Erstelle den heutigen Standup-Bericht"

• Erstellt einen formatierten Bericht mit abgeschlossenen, in Bearbeitung befindlichen und blockierten Elementen

MCP-Integration

Mit Claude Desktop

Die Konfigurationsdatei befindet sich unter:

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

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

Fügen Sie den folgenden Eintrag hinzu und ersetzen Sie /path/to/mcp-jira durch den absoluten Pfad, unter dem Sie das Repo geklont haben:

{
  "mcpServers": {
    "mcp-jira": {
      "command": "/path/to/mcp-jira/.venv/bin/python",
      "args": ["-m", "mcp_jira"]
    }
  }
}

Hinweis: Verwenden Sie die Python-Binary aus dem .venv-Ordner – dies stellt sicher, dass alle Abhängigkeiten verfügbar sind. Das Feld cwd ist nicht erforderlich; der Server löst seine Konfiguration intern über absolute Pfade auf.

Um den korrekten Pfad zu finden, führen Sie dies innerhalb des Projektverzeichnisses aus:

echo "$(pwd)/.venv/bin/python"

Starten Sie Claude Desktop nach dem Speichern der Konfiguration neu.

Mit anderen MCP-Clients

Der Server folgt dem Standard-MCP-Protokoll und funktioniert mit jedem MCP-kompatiblen Client.

Konfiguration

Erforderliche Umgebungsvariablen

• JIRA_URL - Ihre Jira-Instanz-URL

• JIRA_USERNAME - Ihr Jira-Benutzername/E-Mail

• JIRA_API_TOKEN - Ihr Jira-API-Token

• PROJECT_KEY - Standard-Projektschlüssel für Vorgänge (kann pro Anfrage überschrieben werden)

Optionale Einstellungen

• DEFAULT_BOARD_ID - Standard-Board für Sprint-Vorgänge (kann pro Anfrage überschrieben werden)

• STORY_POINTS_FIELD - Benutzerdefiniertes Feld-ID für Story Points (Standard: customfield_10026)

• DEBUG_MODE - Debug-Protokollierung aktivieren (Standard: false)

• LOG_LEVEL - Protokollierungsebene (Standard: INFO)

Jira-API-Token abrufen

1. Gehen Sie zu Atlassian-Kontoeinstellungen

2. Klicken Sie auf "API-Token erstellen"

3. Geben Sie ihm einen Namen und kopieren Sie das Token

4. Verwenden Sie Ihre E-Mail als Benutzernamen und das Token als Passwort

Architektur

Diese Implementierung priorisiert Einfachheit und Zuverlässigkeit:

• Einzelne MCP-Serverdatei - Alle Tools an einem Ort

• Standard-MCP-Protokoll - Verwendet das offizielle MCP-SDK

• Jira REST API v3 - Verwendet das Atlassian Document Format (ADF) für Beschreibungen

• Reiche Formatierung - Liefert schöne, lesbare Berichte

• Wiederholung mit Backoff - Behandelt Ratenbegrenzungen und vorübergehende Jira-API-Fehler automatisch

• Paginierung - Ruft alle Ergebnisse für große Vorgangsmengen ab

• Fehlerbehandlung - Fehlertoleranter Umgang mit Jira-API-Problemen und benutzerdefinierten Status

• Async-Unterstützung - Schnelle und reaktionsschnelle Vorgänge

Fehlerbehebung

Häufige Probleme

1. "No active sprint found"

   • Stellen Sie sicher, dass Ihr Board einen aktiven Sprint hat

   • Überprüfen Sie, ob DEFAULT_BOARD_ID korrekt gesetzt ist

2. Authentifizierungsfehler

   • Überprüfen Sie, ob Ihr API-Token korrekt ist

   • Überprüfen Sie, ob Ihr Benutzername Ihre E-Mail-Adresse ist

3. Berechtigungsfehler

   • Stellen Sie sicher, dass Ihr Jira-Benutzer über entsprechende Projektberechtigungen verfügt

   • Überprüfen Sie, ob der Projektschlüssel existiert und Sie Zugriff haben

Debug-Modus

Setzen Sie DEBUG_MODE=true in Ihrer .env-Datei für detaillierte Protokollierung.

Entwicklung

1. Forken Sie das Repository

2. Richten Sie eine Entwicklungsumgebung ein:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

3. Führen Sie Tests aus:

python -m pytest tests/ -v

4. Senden Sie einen Pull Request

Lizenz

MIT-Lizenz - siehe LICENSE-Datei