Jira MCP Server (nur lesend)

Ein lokaler MCP-Server, der es Claude Code ermöglicht, Jira-Ticketkontext (Ticketdetails, Kommentarthreads, den Referenzgraphen um ein Ticket und JQL-Suchergebnisse) als kompaktes Markdown abzurufen. Bildanhänge (z. B. der Screenshot auf einem UI-Fehler-Ticket) können abgerufen werden, damit Claude sie visuell analysieren kann.

Was es bewusst nicht kann

Dieser Server ist streng schreibgeschützt. Er stellt kein Werkzeug bereit, das etwas erstellt, aktualisiert, übergeht, löscht oder kommentiert. Die Durchsetzung ist mehrschichtig:

1. Im Code: Jede HTTP-Anfrage läuft durch einen einzigen Helfer, der nur GET zulässt, mit einer Ausnahme in der Whitelist: POST /rest/api/3/search/jql, eine Leseoperation, die Atlassian als POST senden muss. Jede andere Methode löst ReadOnlyViolationError aus, sodass eine zukünftige Änderung, die einen Schreibaufruf hinzufügt, laut scheitert.

2. Auf der Anmeldeebene: Erstellen Sie das API-Token nur mit Lese-Berechtigungen (siehe unten), sodass selbst ein Fehler nicht schreiben könnte.

Related MCP server: JIRA MCP Server

Werkzeuge

Einrichtung

1. Atlassian-API-Token erstellen

1. Gehen Sie zu https://id.atlassian.com/manage-profile/security/api-tokens.

2. Wählen Sie API-Token mit Bereichen erstellen (Atlassian stellt Tokens ohne Bereiche ein).

3. Wählen Sie die Jira-App und wählen Sie nur diese Bereiche:

   • read:jira-work

   • read:jira-user

4. Kopieren Sie das Token sofort; es wird nur einmal angezeigt.

Ein älteres unscoped Token funktioniert ebenfalls; der Server behandelt beide automatisch (siehe unten).

2. .env konfigurieren

cp .env.example .env   # then edit

Erforderliche Schlüssel (das ist die gesamte Konfigurationsoberfläche):

.env ist gitignored; committen Sie es niemals. Echte Umgebungsvariablen haben Vorrang vor der Datei. Die Datei befindet sich relativ zum Projektverzeichnis (nicht zum Arbeitsverzeichnis), sodass der Server sie findet, egal von wo aus er gestartet wird.

3. Abhängigkeiten installieren

Mit uv (bevorzugt, da dieses Repository eine uv.lock hat):

uv sync

Oder mit einfachem pip in eine venv:

python -m venv .venv
.venv/bin/pip install -r requirements.txt   # Windows: .venv\Scripts\pip

4. Mit --check verifizieren

.venv/bin/python -m jira_mcp --check            # connectivity + auth only
.venv/bin/python -m jira_mcp --check PROJ-123   # also fetch a ticket in full

Dies gibt aus, ob .env gefunden wurde, welche Basis-URL ausgewählt wurde (und ob der Cloud-ID-Fallback benötigt wurde), das authentifizierte Konto und, wenn ein Schlüssel angegeben ist, das Ticket genau so, wie Claude es sehen würde.

Scoped vs. unscoped Tokens: das Basis-URL-Problem

• Ein unscoped Token funktioniert gegen Ihre Site-URL, https://<site>.atlassian.net.

• Ein scoped Token gegen dieselbe URL schlägt still fehl und gibt anonym aussehende Antworten zurück. Es muss stattdessen https://api.atlassian.com/ex/jira/{cloudId} aufrufen.

Sie müssen nicht wissen, welche Art Sie besitzen. Beim Start testet der Server die Site-URL mit GET /rest/api/3/myself; wenn das kein echtes Konto zurückgibt, ruft er Ihre Cloud-ID von {site}/_edge/tenant_info ab und versucht es erneut gegen api.atlassian.com. Der Gewinner wird für die Prozesslebensdauer zwischengespeichert und auf stderr protokolliert.

Falls die Erkennung jemals fehlschlägt: _edge/tenant_info ist nicht Teil der offiziell unterstützten REST-API von Atlassian (obwohl Atlassians eigene Support-Dokumente darauf verweisen), also könnte es sich ändern. In diesem Fall setzen Sie ATLASSIAN_CLOUD_ID in .env, um die Erkennung zu überspringen; die Fehlermeldung sagt Ihnen, wann das zutrifft. Sie brauchen es fast nie.

PyCharm-Einrichtung

1. Interpreter: Einstellungen → Projekt → Python-Interpreter → Interpreter hinzufügen → Vorhanden → wählen Sie .venv/bin/python im Projektverzeichnis. (Wenn Sie uv sync ausgeführt haben, existiert die venv bereits mit allem installiert.)

2. Ausführungskonfiguration für Debugging: Ausführen → Konfigurationen bearbeiten → + → Python:

   • Ausführen: Modul jira_mcp (wählen Sie „Modul" statt „Skriptpfad")

   • Parameter: --check PROJ-123

   • Arbeitsverzeichnis: das Projektverzeichnis (alles funktioniert, aber das ist ordentlich)

   Jetzt können Sie überall Haltepunkte setzen (z. B. in client.py) und echte Anfragen debuggen. Fehler in einem laufenden MCP-Server sind sonst unsichtbar.

Mit Claude Code verbinden

Verwenden Sie das Python der venv mit absolutem Pfad; ein bloßes python wird nicht auf die venv aufgelöst, wenn Claude Code den Server startet.

macOS/Linux:

claude mcp add jira -- /path/to/PythonProject/.venv/bin/python -m jira_mcp

Windows:

claude mcp add jira -- C:\path\to\PythonProject\.venv\Scripts\python.exe -m jira_mcp

Hinweise:

• Alles nach -- ist der Befehl, den Claude ausführt; alles davor sind Claudes eigene Optionen.

• Der Standardbereich ist local (nur Sie, nur dieses Projekt, gespeichert in ~/.claude.json). Fügen Sie --scope project hinzu, um über eine eingecheckte .mcp.json zu teilen, oder --scope user, um es in allen Ihren Projekten zu verwenden.

Verifizieren, dass es verbunden ist

In einer Claude-Code-Sitzung:

• Führen Sie /mcp aus; der jira-Server sollte als verbunden aufgelistet sein, mit sechs Werkzeugen.

• Oder fragen Sie einfach: „use whoami to check the jira connection".

Fehlerbehebung

Hinweise für Entwickler, die neu in Python sind

• Die venv (.venv/) ist eine projektlokale Kopie von Python plus den Paketen dieses Projekts: das Äquivalent zu node_modules, außer dass der Interpreter selbst auch darin lebt. Deshalb muss Claude Code .venv/bin/python mit absolutem Pfad erhalten: Es gibt keine globale Installation, auf die zurückgegriffen werden kann.

• asyncio.run(...) wird benötigt, weil asynchrone Funktionen in Python nicht einfach durch Aufrufen ausgeführt werden; das Aufrufen einer solchen Funktion gibt ein Coroutine-Objekt zurück, und etwas muss es antreiben. Es gibt keine Umgebungs-Event-Loop wie in Node; asyncio.run() erstellt eine Loop, führt eine Coroutine bis zum Ende aus und baut die Loop wieder ab. Der MCP-Server macht das intern über mcp.run(); der --check-Modus macht es explizit.

• Die Dekorateure (@mcp.tool) sind Funktionen, die die darunter definierte Funktion empfangen und registrieren/umhüllen, wie eine Middleware-Fabrik, die zur Definitionszeit angewendet wird. FastMCPs Dekorator liest den Namen, die Typ-Hinweise und den Docstring der Funktion, um das MCP-Tool-Schema zu generieren, das Claude sieht; der Docstring ist die API-Dokumentation des Tools.

• python -m jira_mcp führt die __main__.py des Pakets aus, das, was Python am nächsten an einem npm-bin-Eintrag hat. Es funktioniert von jedem Verzeichnis aus, weil uv sync das Projekt in die venv installiert hat.