JIRA MCP Server

Dies ist ein Model Context Protocol (MCP)-Server, der Werkzeuge für die Interaktion mit JIRA bereitstellt. Er ermöglicht es Ihnen, Tickets aus aktiven Sprints abzurufen und detaillierte Ticketinformationen über die MCP-Schnittstelle zu erhalten.

Funktionen

Der Server stellt die folgenden Werkzeuge bereit:

1. list-sprint-tickets: Ruft alle Tickets im aktiven Sprint für ein bestimmtes Projekt ab

   • Erforderlicher Parameter: projectKey (string)

2. get-ticket-details: Ruft detaillierte Informationen zu einem bestimmten Ticket ab

   • Erforderlicher Parameter: issueKey (string)

3. add-comment: Fügt einem bestimmten Ticket einen Kommentar hinzu

   • Erforderlicher Parameter: issueKey (string)

   • Entweder comment (string) oder filePath (string) – siehe Inhalt aus einer Datei bearbeiten

   • Optionaler Parameter: commentFormat – plain (Standard), wiki, markdown oder adf

4. link-tickets: Verknüpft zwei Tickets mit einer „verwandt mit“-Beziehung

   • Erforderlicher Parameter: sourceIssueKey (string)

   • Erforderlicher Parameter: targetIssueKey (string)

5. update-description: Aktualisiert die Beschreibung eines bestimmten Tickets

   • Erforderlicher Parameter: issueKey (string)

   • Entweder description (string) oder filePath (string) – siehe Inhalt aus einer Datei bearbeiten

   • Optionaler Parameter: descriptionFormat – plain (Standard), wiki, markdown oder adf

6. list-child-issues: Ruft alle Untertickets eines übergeordneten Tickets ab

   • Erforderlicher Parameter: parentKey (string)

7. create-sub-ticket: Erstellt ein Unterticket (Child Issue) für ein übergeordnetes Ticket

   • Erforderlicher Parameter: parentKey (string)

   • Erforderlicher Parameter: summary (string)

   • Optionaler Parameter: description (string) oder filePath (string) – siehe Inhalt aus einer Datei bearbeiten

   • Optionaler Parameter: issueType (string) – Der Name des Unteraufgaben-Issuetyps (z. B. „Sub-task“)

Related MCP server: mcp-jira

Einrichtung

1. Abhängigkeiten installieren:

   npm install

2. Den TypeScript-Code erstellen:

Dieser Schritt ist nur für Cline unter Windows erforderlich, das derzeit ein Problem mit der Ausführung von npx hat.

npm run build

3. Konfigurieren Sie die MCP-Einstellungen in Ihrer Claude-App-Einstellungsdatei (normalerweise unter ~/Library/Application Support/Claude/claude_desktop_config.json auf macOS oder %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json auf Windows):

Einstellungen für Claude:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["path/to/this/repo/jira.ts"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Einstellungen für Cline:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["path/to/this/repo/dist/jira.js"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Konfiguration

Sie müssen die folgenden Umgebungsvariablen in Ihren MCP-Einstellungen einrichten:

1. JIRA_HOST: Ihre Atlassian-Domain-URL (z. B. https://your-company.atlassian.net)

2. JIRA_EMAIL: Ihre JIRA-Konto-E-Mail

3. JIRA_API_TOKEN: Ihr JIRA-API-Token

   • Sie können ein API-Token über Ihre Atlassian-Kontoeinstellungen generieren

Verwendung

Nach der Konfiguration können Sie die Werkzeuge über die MCP-Schnittstelle in Claude verwenden:

Sprint-Tickets auflisten

Um alle Tickets im aktiven Sprint für ein Projekt abzurufen:

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>list-sprint-tickets</tool_name>
<arguments>
{
  "projectKey": "YOUR_PROJECT_KEY"
}
</arguments>
</use_mcp_tool>

Ticketdetails abrufen

Um detaillierte Informationen zu einem bestimmten Ticket abzurufen:

<use_mcp_tool>
<server_name>jira</server_name>
<tool_name>get-ticket-details</tool_name>
<arguments>
{
  "issueKey": "PROJECT-123"
}
</arguments>
</use_mcp_tool>

Inhalt aus einer Datei bearbeiten

update-description, update-comment, add-comment, create-ticket und create-sub-ticket akzeptieren filePath anstelle von Inline-Text. Dies ist für lange Inhalte gedacht: Halten Sie die Quelle in einer Datei, bearbeiten Sie diese Datei und senden Sie sie erneut – kein erneutes Einfügen des gesamten Texts über den Tool-Aufruf jedes Mal. Bei den beiden Erstellungswerkzeugen bleibt die Beschreibung optional, sodass das Weglassen beider weiterhin in Ordnung ist.

Das Format wird aus der Dateiendung abgeleitet, sodass descriptionFormat / commentFormat weggelassen werden können:

Die explizite Angabe des Formats überschreibt die Dateiendung, was auch der Weg ist, eine Datei mit einer beliebigen anderen Endung zu verwenden. Pfade sind absolut oder relativ zum Arbeitsverzeichnis des Servers.

{
  "issueKey": "PROJECT-123",
  "filePath": "/abs/path/to/description.md"
}

Eine leere Datei wird abgelehnt, anstatt die vorhandene Beschreibung oder den vorhandenen Kommentar zu löschen, und die Angabe sowohl des Inline-Texts als auch von filePath ist ein Fehler.

Vorhandenen Inhalt patchen

Um einen Teil einer bereits vorhandenen Beschreibung oder eines Kommentars zu ändern, exportieren Sie ihn zuerst mit export-content, bearbeiten Sie die Datei und laden Sie sie erneut hoch – kein Umschreiben des gesamten Inhalts erforderlich:

{ "issueKey": "PROJECT-123", "commentId": "54660", "filePath": "/tmp/pir-timeline.md" }

Der Export meldet, ob dieser Inhalt sicher als Markdown erneut hochgeladen werden kann. Jira speichert Inhalte als ADF, und Konstrukte wie Panels, Erwähnungen, Status-Lozenges, Medien, Tabellen, Aufgabenlisten und Expands haben kein Markdown-Äquivalent – das erneute Hochladen von Markdown würde sie stillschweigend verwerfen. Wenn solche vorhanden sind, warnt das Werkzeug und listet sie auf; exportieren Sie stattdessen mit "format": "adf" und patchen Sie das JSON, das immer exakt hin- und zurückkonvertiert (.json-Dateien werden beim Hochladen als ADF erkannt).

Lassen Sie filePath weg, um den Inhalt inline zurückzuerhalten, anstatt eine Datei zu schreiben. Kommentar-IDs werden von get-ticket-details angezeigt.

Inhaltsversionen (optimistische Nebenläufigkeit)

update-description und update-comment erfordern expectedVersion, sofern der zu ersetzende Inhalt nicht leer ist: die Version, auf der die Bearbeitung basiert. Wenn sich der Inhalt in Jira seitdem geändert hat, wird die Aktualisierung abgelehnt, anstatt diese Änderung stillschweigend zu verwerfen – dieselbe Sperre, die Confluence durch seine Seitenversionsnummern erhält.

Jira hat keine eigene Versionsnummer, und der updated-Zeitstempel eines Issues ist kein Ersatz: Er ändert sich bei jeder Änderung am Issue, sodass Übergänge, Labels und neue Kommentare alle Beschreibungs-Patches ablehnen würden, die nie in Konflikt geraten sind. Die Version ist daher ein Hash des Inhalts selbst (v1-…), sodass sie sich genau dann ändert, wenn sich das zu patchende Element ändert.

Versionen stammen von export-content und von get-ticket-details, das Description version: und eine version: für jeden Kommentar meldet – sodass eine kleine Inline-Bearbeitung keinen Export-Roundtrip benötigt.

Das erstmalige Schreiben einer Beschreibung benötigt keine Version. Das Weglassen von expectedVersion ist selbst die Annahme, dass hier noch nichts vorhanden ist, was der Server überprüft: Der Schreibvorgang wird durchgeführt, wenn die Beschreibung noch leer ist, und wird abgelehnt – unter Angabe der jetzt in Jira vorhandenen Version –, wenn in der Zwischenzeit jemand eine geschrieben hat. Somit deckt die Sperre auch den ersten Schreibvorgang ab, ohne dass der Aufrufer die Version des leeren Inhalts abrufen muss.

Übergeben Sie "force": true, um die Prüfung zu überspringen und unabhängig davon zu überschreiben.

Entwicklung

Der Server ist in TypeScript geschrieben und verwendet:

• @modelcontextprotocol/sdk für die MCP-Serverimplementierung

• jira.js für die JIRA-API-Integration

Empfohlene Skripte:

• Einmal erstellen: npm run build

• Erstellen und überwachen: npm run build:watch

• Nur Typprüfung: npm run typecheck

• Entwicklungsausführung mit Überwachung: npm run start:dev

• Kompilierten Server ausführen: npm start

• Formatprüfung: npm run fmt:check

• Format schreiben: npm run fmt

Typischer Arbeitsablauf:

1. Änderungen an jira.ts vornehmen

2. Während der Entwicklung npm run start:dev ausführen, oder npm run build und dann npm start für den kompilierten Lauf

3. Starten Sie Ihren MCP-Client bei Bedarf neu, um Änderungen zu übernehmen

Fehlerbehandlung

Der Server enthält Fehlerbehandlung für:

• Ungültige JIRA-Anmeldeinformationen

• Fehlende aktive Sprints

• Ungültige Projekt- oder Issue-Schlüssel

• Netzwerkfehler

Fehlermeldungen werden in der Tool-Antwort zurückgegeben.