MCP Jira Server für Claude Code

Ein umfassender Model Context Protocol (MCP)-Server für die Jira-Integration mit Claude Code. Dieser Server bietet vollständige Jira-Funktionalität, einschließlich Vorgangsmanagement, Sprint-Operationen, Kommentaren, Anhängen und Stapelverarbeitung.

License: MIT TypeScript Node.js

⚠️ Sicherheitshinweis: Committen Sie niemals Ihre API-Token! Verwenden Sie Umgebungsvariablen (z. B. in ~/.zshrc) oder eine Secrets-Verwaltung.

🚀 Funktionen

📋 Vorgangsmanagement (12 Tools)

create-issue - Erstellen von Vorgängen mit vollständiger Feldunterstützung, einschließlich benutzerdefinierter Felder und Datumsangaben
update-issue - Aktualisieren bestehender Vorgänge mit intelligenter Feldbehandlung
get-issue - Abrufen detaillierter Vorgangsinformationen
search-issues - Erweiterte Suche mittels JQL oder vereinfachten Filtern mit Datumsunterstützung
transition-issue - Verschieben von Vorgängen durch Workflow-Status
link-issues - Erstellen von Beziehungen zwischen Vorgängen (mit intelligentem Typabgleich)
get-link-types - Auflisten verfügbarer Vorgangsverknüpfungstypen
get-fields - Anzeigen verfügbarer Felder für Projekt/Vorgangstyp
diagnose-fields - Fehlerbehebung bei der Feldkonfiguration und Finden von IDs benutzerdefinierter Felder
create-epic-with-subtasks - Erstellen eines Epics mit mehreren Unteraufgaben in einem Vorgang
create-task-for-epic - Erstellen einer mit einem Epic verknüpften Aufgabe (optimiert für lokalisiertes Jira)

💬 Kommentare & Verlauf (3 Tools)

get-comments - Lesen von Vorgangskommentaren mit Informationen zu Autor und Zeitstempel
get-history - Anzeigen des detaillierten Änderungsverlaufs mit Feldmodifikationen
add-comment - Hinzufügen von Kommentaren mit Unterstützung für das Atlassian Document Format
batch-comment - Gleichzeitiges Hinzufügen desselben Kommentars zu mehreren Vorgängen

📎 Anhänge (2 Tools)

get-attachments - Auflisten von Anhängen mit Metadaten (Größe, Typ, Hochladedatum)
upload-attachment - Hochladen von Dateien mittels Base64-Kodierung

🏃 Sprint- & Agile-Management (4 Tools)

get-boards - Auflisten verfügbarer Jira-Boards für agile Projekte
get-sprints - Anzeigen von Sprints für ein Board mit Statusanzeigen
move-issue-to-sprint - Verschieben von Vorgängen zwischen Sprints und Backlog
create-sprint - Erstellen neuer Sprints mit optionalen Start-/Enddaten

Ressourcen

jira://projects - Alle zugänglichen Projekte auflisten
jira://project/{key} - Details eines bestimmten Projekts abrufen
jira://issue/{key} - Details eines bestimmten Vorgangs abrufen
jira://myself - Informationen zum aktuellen Benutzer
jira://search?jql={query} - Suchergebnisse

Prompts

standup-report - Tägliche Standup-Berichte generieren
sprint-planning - Unterstützung bei Sprint-Planungsaktivitäten
bug-triage - Unterstützung bei der Priorisierung und Triage von Fehlern
release-notes - Release-Notes aus abgeschlossenen Vorgängen generieren
epic-status - Umfassende Fortschrittsberichte für Epics

Installation

Repository klonen:

git clone https://github.com/tom28881/JIRA_MCP.git
cd JIRA_MCP

Abhängigkeiten installieren:

npm install

Projekt bauen:

npm run build

Konfigurieren Sie Ihre Jira-Anmeldedaten in Umgebungsvariablen (z. B. ~/.zshrc):

Für Jira Cloud:

export JIRA_HOST=https://your-company.atlassian.net
export JIRA_EMAIL=your-email@company.com
export JIRA_API_TOKEN=your-api-token

Für Jira Server/DC 9.12+:

export JIRA_HOST=https://jira.your-company.com
export JIRA_PAT=your-personal-access-token

Für Jira Server/DC (Legacy):

export JIRA_HOST=https://jira.your-company.com
export JIRA_USERNAME=your-username
export JIRA_PASSWORD=your-password

Siehe docs/AUTH_SETUP.md für eine vollständige Anleitung zur Authentifizierung.

Anmeldedaten abrufen

Jira Cloud (API-Token)

Melden Sie sich bei den Atlassian-Kontoeinstellungen an
Klicken Sie auf "API-Token erstellen"
Geben Sie ihm einen Namen (z. B. "MCP Server")
Kopieren Sie das Token und fügen Sie es Ihrer Shell-Konfiguration (z. B. ~/.zshrc) als JIRA_API_TOKEN hinzu

Jira Server/DC 9.12+ (Persönliches Zugriffstoken)

Melden Sie sich bei Jira Server/DC an
Gehen Sie zu Profil → Persönliche Zugriffstoken
Klicken Sie auf Token erstellen
Legen Sie Name und Ablaufdatum fest (maximal 365 Tage)
Kopieren Sie das Token sofort – es kann nicht erneut angezeigt werden
Fügen Sie es Ihrer Shell-Konfiguration (z. B. ~/.zshrc) als JIRA_PAT hinzu

Siehe docs/AUTH_SETUP.md für detaillierte Einrichtungsanweisungen.

Claude Code Konfiguration

Um diesen MCP-Server mit Claude Code zu verwenden, müssen Sie ihn in Ihren MCP-Einstellungen konfigurieren.

Option 1: Verwendung von Umgebungsvariablen (Empfohlen)

Einrichten des Servers mit Umgebungsvariablen in Ihrer Shell-Konfiguration (z. B. ~/.zshrc):

# Add to ~/.zshrc
export JIRA_HOST="https://your-company.atlassian.net"
export JIRA_EMAIL="your-email@company.com"
export JIRA_API_TOKEN="your-api-token"
export JIRA_DEFAULT_PROJECT="PROJ"

# Restart terminal or run: source ~/.zshrc
# Then run Claude Code with the MCP server
claude --mcp "node /absolute/path/to/mcp-jira-server/dist/index.js"

Option 2: Hinzufügen zu den Claude Code-Einstellungen

Fügen Sie den Server zu Ihrer Claude Code-Einstellungsdatei (~/.claude/settings.json) hinzu:

{
  "mcpServers": [
    {
      "name": "jira",
      "command": "node",
      "args": ["/absolute/path/to/mcp-jira-server/dist/index.js"],
      "env": {
        "JIRA_HOST": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    }
  ]
}

Anwendungsbeispiele

Vorgänge erstellen

Create a new bug in project PROJ with high priority about login issues

Create a story "Implement user authentication" with 5 story points and assign it to john@example.com

Datumsangaben und Zeitschätzungen festlegen

Create task "Database backup" with dueDate "next week" and originalEstimate "4h"

Update PROJ-123 with startDate "tomorrow" and dueDate "+14d"

Create issue "Quarterly review" with dueDate "31.3.2025" and originalEstimate "2 days"

Epics mit Unteraufgaben erstellen

Create an epic "Database Migration" in project PROJ with subtasks "Backup current data" and "Migrate schema"

Unteraufgaben erstellen

Create a subtask "Review code" for parent issue PROJ-123

Tschechische Jira-Unterstützung

Create issue type "Úkol" in project PROJ

Create task for epic PPC-48 with summary "Database backup"

Vorgänge suchen

Find all open bugs assigned to me

Search for issues in project PROJ with label "urgent" that are not done

Datumsbasierte Suche

Search issues due before "next week" in project PROJ

Find issues created after "2024-12-01" and updated after "yesterday"

Search for overdue issues: dueBefore "today" and status != "Done"

Vorgänge verwalten

Update PROJ-123 to add story points 8

Transition PROJ-456 to "In Progress"

Link PROJ-123 to PROJ-456 as "blocks"

Hinweis: Epic-Story-Beziehungen verwenden das Feld epicLink, nicht reguläre Vorgangsverknüpfungen:

Update PROJ-456 with epicLink "PROJ-100"  # Links story to epic

Prompts verwenden

Generate a standup report for john@example.com

Help me plan the sprint for project PROJ

Create release notes for version 2.0 in project PROJ

Erweiterte Konfiguration

Benutzerdefinierte Felder

Der Server kann mit jeder Jira-Konfiguration arbeiten:

Option 1: Automatische Erkennung (Empfohlen)

Lassen Sie die IDs benutzerdefinierter Felder in Ihrer Umgebungskonfiguration leer, und der Server erkennt sie automatisch anhand der Feldnamen.

Option 2: Manuelle Konfiguration

Wenn die automatische Erkennung nicht funktioniert, konfigurieren Sie die IDs benutzerdefinierter Felder in Ihrer Umgebung (z. B. ~/.zshrc):

export JIRA_FIELD_STORY_POINTS=customfield_10001
export JIRA_FIELD_ACCEPTANCE_CRITERIA=customfield_10002
export JIRA_FIELD_EPIC_LINK=customfield_10003

Feld-IDs finden

Verwenden Sie das Tool diagnose-fields, um die korrekten Feld-IDs für Ihre Jira-Instanz zu finden:

diagnose-fields project:"PROJ" issueType:"Story"

Test-Tickets automatisch erstellen

Aktivieren Sie die automatische Erstellung von Test-Tickets für Stories:

AUTO_CREATE_TEST_TICKETS=true

Entwicklung

Ausführen im Entwicklungsmodus

npm run dev

Typüberprüfung

npm run typecheck

Linting

npm run lint

Funktionen

🌍 Lokalisierungsunterstützung

Automatische Unterstützung für lokalisierte Jira-Instanzen (Tschechisch, Englisch, etc.)
Namen von Vorgangstypen können in jeder Sprache vorliegen (z. B. "Task", "Úkol", "Aufgabe")
Prioritätsnamen unterstützen Lokalisierung (z. B. "High", "Vysoká", "Hoch")
Spezielle Unterstützung für tschechische Jira-Konfigurationen
Funktioniert mit jeder Jira-Spracheinstellung

📅 Datums- und Zeitverwaltung

Flexible Datums-Eingabeformate:
- ISO: "2024-12-31"
- Europäisch: "31.12.2024" oder "31/12/2024"
- Relativ: "today", "tomorrow", "next week", "+7d", "+2w", "+1m"
- Tschechisch: "dnes", "zítra", "příští týden"
Unterstützung für Zeiterfassung:
- Schätzungen: "2h", "1d 4h", "3 days", "2 hodiny"
- Automatische Formatkonvertierung
Datumsbasierte Suche und Filterung

🔄 Automatischer Wiederholungsversuch

Der Server wiederholt fehlgeschlagene Anfragen automatisch mit exponentiellem Backoff (bis zu 3 Versuche).

📦 Robuste Fehlerbehandlung

Behandlung leerer Antworten bei Jira-Übergängen
Detaillierte Fehlermeldungen mit Kontext
Graceful Degradation bei fehlenden Funktionen

📝 Umfassende Protokollierung

Aktivieren Sie das Debug-Protokoll, um detaillierte Informationen zu sehen:

DEBUG=* claude --mcp "./run.sh"
# or specific to jira-mcp:
DEBUG=jira-mcp claude --mcp "./run.sh"

🔒 Verbindungstest

Der Server testet die Verbindung beim Start und liefert klare Fehlermeldungen, falls die Authentifizierung fehlschlägt.

📄 Atlassian Document Format

Konvertiert automatisch Klartext und Markdown in das ADF-Format von Jira für Rich-Text-Felder.

Fehlerbehebung

Arbeiten mit verschiedenen Jira-Konfigurationen

Dieser MCP-Server ist so konzipiert, dass er mit jeder Jira-Instanz funktioniert, unabhängig von:

Spracheinstellungen (Englisch, Tschechisch, Deutsch, etc.)
Konfigurationen benutzerdefinierter Felder
Projektspezifischen Einstellungen

Best Practices:

Verwenden Sie get-fields, um verfügbare Vorgangstypen in Ihrer Sprache zu sehen
Verwenden Sie diagnose-fields, um IDs benutzerdefinierter Felder zu finden
Erstellen Sie Vorgänge unter Verwendung der exakten Namen der Vorgangstypen aus Ihrem Jira

Häufige Probleme

Authentifizierung fehlgeschlagen
- Überprüfen Sie, ob Ihr API-Token korrekt ist
- Stellen Sie sicher, dass Ihre E-Mail-Adresse mit Ihrem Atlassian-Konto übereinstimmt
- Überprüfen Sie, ob Ihre Jira-Instanz-URL https:// enthält
Projekt nicht gefunden
- Überprüfen Sie, ob Sie Zugriff auf das Projekt haben
- Überprüfen Sie, ob der Projektschlüssel korrekt ist (Groß-/Kleinschreibung beachten)
Benutzerdefinierte Felder funktionieren nicht
- Verwenden Sie das Tool diagnose-fields, um die korrekten Feld-IDs für Ihr Projekt zu finden
- Verwenden Sie das Tool get-fields, um alle verfügbaren Felder zu sehen
- IDs benutzerdefinierter Felder beginnen normalerweise mit customfield_
- Einige Felder sind für bestimmte Vorgangstypen möglicherweise nicht verfügbar (z. B. Labels bei Epics)
- Die Feld-ID für den Epic-Link variiert zwischen Jira-Instanzen
Verknüpfungstyp nicht gefunden
- Verwenden Sie das Tool get-link-types, um verfügbare Verknüpfungstypen zu sehen
- Verknüpfungstypen unterscheiden in der Jira-API zwischen Groß- und Kleinschreibung
- Der Server versucht einen Abgleich ohne Berücksichtigung der Groß-/Kleinschreibung
- Epic-Story-Beziehungen verwenden das Feld epicLink, nicht reguläre Vorgangsverknüpfungen
Probleme bei der Epic-Story-Verknüpfung
- Führen Sie diagnose-fields für das Projekt und den Vorgangstyp "Story" aus
- Aktualisieren Sie JIRA_FIELD_EPIC_LINK in Ihrer Umgebungskonfiguration mit der korrekten Feld-ID
- Starten Sie Ihr Terminal neu oder führen Sie source ~/.zshrc nach der Aktualisierung aus

Debug-Modus

Setzen Sie die Umgebungsvariable DEBUG für ausführliche Protokollierung:

DEBUG=* claude --mcp "./run.sh"
# or
DEBUG=jira-mcp claude --mcp "./run.sh"

Protokolle anzeigen

Protokolle werden nach stderr ausgegeben und enthalten:

Verbindungsstatus
API-Anfragen und -Antworten
Fehlerdetails mit Kontext
Leistungsmetriken

Mitwirken

Siehe CONTRIBUTING.md für Entwicklungsrichtlinien.

Lizenz

MIT-Lizenz - siehe LICENSE-Datei für Details

Support

Für Probleme und Funktionsanfragen verwenden Sie bitte den GitHub Issue Tracker.