atlassian-mcp

Ein Model Context Protocol (MCP)-Server für selbst gehostetes Jira (Server / Data Center) und selbst gehostetes Bitbucket (Server / Data Center). Stellt Werkzeuge für Workflows in natürlicher Sprache rund um Tickets, Pull Requests, Review-Threads und Git-Kontext bereit.

Hinweis: Dieser Server unterstützt nur selbst gehostete Instanzen. Jira Cloud und Bitbucket Cloud verwenden andere APIs und werden nicht unterstützt.

Werkzeuge

Workflow

Git

Jira

Bitbucket

Beispiele in natürlicher Sprache

• „Woran arbeite ich gerade?“ → get_dev_context

• „Erstelle einen Branch für FOO-123“ → start_work

• „Ship das / merge und schließe das Ticket“ → complete_work

• „Zeig meine PRs, die auf Review warten“ → bitbucket_search mit mine=true

• „Liste offene PRs für dieses Repo von feature/ABC-123“ → bitbucket_search mit fromBranch

• „Gib mir eine vollständige Übersicht von PR 42“ → bitbucket_get_pr

• „Eröffne einen PR von meinem aktuellen Branch zu master“ → bitbucket_mutate mit create

• „Genehmige / merge / lehne PR 42 ab“ → bitbucket_mutate mit action

• „Antworte auf Kommentar 123 bei PR 42“ → bitbucket_comment mit commentId=123

• „Löse diesen Blocker bei PR 42“ → bitbucket_comment mit action=update, severity=BLOCKER, state=RESOLVED

• „Liste PR-Checklisten-Aufgaben“ → bitbucket_pr_tasks mit action=list

• „Finde Bugs, die mir im PAY-Projekt zugewiesen sind“ → jira_search mit mine=true, issueType=Bug

• „Was ist im aktuellen Sprint?“ → jira_search mit resource=board_overview

• „Setze FOO-123 auf In Progress“ → jira_mutate mit transitionName="In Progress"

• „Protokolliere 2h bei FOO-123“ → jira_mutate mit worklog

• „Erstelle Version 9.1.0 in PAY“ → jira_version mit action=create, projectKey=PAY, name=9.1.0

• „Liste Releases für PAY“ → jira_search mit resource=versions, project=PAY

• „Veröffentliche Version 12345“ → jira_version mit action=release, id=12345

• „Setze Fix-Version 9.1.0 auf FOO-123“ → jira_mutate mit update.fixVersion=9.1.0

• „Erstelle eine Aufgabe unter dem Epic FOO-100“ → jira_mutate mit create.issueType=Task, create.parent=FOO-100 (erkennt Epic automatisch und setzt Epic Link)

• „Verschiebe FOO-123 unter Epic FOO-100“ → jira_mutate mit update.epicLink=FOO-100

• „Erstelle ein Epic“ → jira_mutate mit create.issueType=Epic (Epic-Name standardmäßig die Zusammenfassung)

• „Setze Story Points auf 5“ → jira_mutate mit update.customFields={"Story Points": 5} – Werte sind einfach (Optionslabel, Benutzername, Datum, Array von Labels); der Server verpackt sie gemäß dem Feldschema

• „Was kann ich bei diesem Ticket / bei einem Epic setzen?“ → jira_search resource=fields mit issueKey=FOO-123 (Bearbeitungsbildschirm) oder project=FOO+issueType=Epic (Erstellungsbildschirm): Pflicht- und optionale Felder, Wertformen, zulässige Werte

Related MCP server: Bitbucket Server MCP

Einrichtung

1. Konfigurationsdatei erstellen

Erstelle ~/.atlassian-mcp.json:

{
  "$schema": "https://raw.githubusercontent.com/stubbedev/atlassian-mcp/master/atlassian-mcp.schema.json",
  "jira": {
    "url": "https://jira.example.com",
    "token": "your-jira-personal-access-token"
  },
  "bitbucket": {
    "url": "https://bitbucket.example.com",
    "token": "your-bitbucket-personal-access-token"
  }
}

Das Feld $schema ist optional, ermöglicht aber Editor-Autovervollständigung und Validierung.

• projectKey bedeutet einen Projektcode:

  • Jira-Beispiel: PAY im Ticket PAY-123

  • Bitbucket-Beispiel: Projekt ENG im Repo-Pfad ENG/payments-service

• Du kannst auch ergonomische Aliase verwenden:

  • Jira: project (Alias von projectKey)

  • Bitbucket: project und repo (Aliase von projectKey und repoSlug)

• Für Bitbucket-Werkzeuge werden projectKey und repoSlug normalerweise automatisch aus deinem lokalen origin-Remote erkannt.

• bitbucket_create_pull_request erkennt auch fromBranch automatisch aus deinem aktuellen Branch und gibt den bereits vorhandenen offenen PR zurück, falls für diesen Branch bereits einer existiert.

• Jira-Projektbezogene Aufrufe akzeptieren projectKey und funktionieren am besten, wenn sie angegeben werden.

• Wenn projectKey für die Jira-Issue-Erstellung/Typ-Suche weggelassen wird, versucht der Server, ihn aus dem Ticket-Schlüssel deines aktuellen Branches abzuleiten, fällt auf automatische Auswahl zurück, wenn nur ein Projekt sichtbar ist, und gibt andernfalls eine nummerierte Projektliste zur Auswahl zurück.

Alternativ können Umgebungsvariablen (oder eine .env-Datei in diesem Verzeichnis) verwendet werden:

JIRA_URL=https://jira.example.com
JIRA_ACCESS_TOKEN=your-jira-personal-access-token
BITBUCKET_URL=https://bitbucket.example.com
BITBUCKET_ACCESS_TOKEN=your-bitbucket-personal-access-token

Die Konfiguration wird in dieser Reihenfolge aufgelöst: --config <pfad>-CLI-Argument → ATLASSIAN_MCP_CONFIG-Umgebungsvariable → ~/.atlassian-mcp.json → $XDG_CONFIG_HOME/atlassian-mcp/config.json (Standard ~/.config/atlassian-mcp/config.json) → .atlassian-mcp.json im aktuellen Arbeitsverzeichnis → Umgebungsvariablen.

2. Mit deinem KI-Tool verbinden

Kein Klonen oder Bauen erforderlich – weise dein Tool einfach auf npx @stubbedev/atlassian-mcp@latest und es wird automatisch installiert und ausgeführt.

Hinweis: --prefer-online kann den MCP-Start in einigen Clients stören. Halte den Befehl einfach und verwende die unten stehenden Aktualisierungsschritte, wenn du aktualisieren möchtest.

Claude Code

claude mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest --config ~/.atlassian-mcp.json

Cursor

Füge zu ~/.cursor/mcp.json (global) oder .cursor/mcp.json (nur Projekt) hinzu:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Windsurf

Füge zu ~/.codeium/windsurf/mcp_config.json hinzu:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Zed

Füge zu ~/.config/zed/settings.json hinzu:

{
  "context_servers": {
    "atlassian": {
      "command": {
        "path": "npx",
        "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
      }
    }
  }
}

OpenCode

Füge zu opencode.json im Projektstamm hinzu (oder ~/.config/opencode/opencode.json für global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "atlassian": {
      "type": "local",
      "command": ["npx", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
    }
  }
}

Codex CLI

Füge zu ~/.codex/config.yaml hinzu:

mcpServers:
  atlassian:
    command: npx
    args:
      - -y
      - @stubbedev/atlassian-mcp@latest
      - --config
      - /home/you/.atlassian-mcp.json

Jedes andere MCP-kompatible Tool

Die meisten Tools, die MCP unterstützen, akzeptieren dasselbe JSON-Format. Verwende npx als Befehl mit ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/pfad/zu/config.json"] als Argumente.

Vorhandene Installationen aktualisieren

Wenn Ihr MCP-Client bereits konfiguriert ist und Sie die neueste Paketversion möchten:

npx clear-npx-cache

Starten Sie dann Ihren MCP-Client neu.

Installation ohne npm

Der Server ist ein einzelnes statisches Go-Binary. Der npx-Pfad oben lädt das vorgefertigte Binary für Ihre Plattform beim ersten Start herunter; diese Alternativen überspringen Node vollständig:

# Go toolchain — installs to $GOBIN / $GOPATH/bin
go install github.com/stubbedev/atlassian-mcp@latest

# Nix flake
nix run github:stubbedev/atlassian-mcp -- --config ~/.atlassian-mcp.json

Richten Sie dann den command Ihres MCP-Clients auf das resultierende atlassian-mcp-Binary statt auf npx. Auf diesen Pfaden müssen ffmpeg/ffprobe im PATH verfügbar sein (oder setzen Sie ATLASSIAN_MCP_FFMPEG_PATH / ATLASSIAN_MCP_FFPROBE_PATH); der npm-Wrapper bündelt sie automatisch.

Ausführung als HTTP-Server (gemeinsam genutzt / hinter einem Proxy)

Standardmäßig kommuniziert der Server über stdio per MCP (ein Prozess pro Client, von Ihrem Editor gestartet). Er kann stattdessen als langlebiger Streamable-HTTP-Server laufen, den viele Clients gemeinsam nutzen — nützlich hinter einem Reverse-Proxy:

atlassian-mcp --http                 # binds 127.0.0.1:7337
atlassian-mcp --http 127.0.0.1:9000  # custom address
ATLASSIAN_MCP_HTTP=1 atlassian-mcp   # same, via env

• Ein einzelner Endpunkt POST /mcp (JSON-RPC) plus ein optionaler GET /mcp-SSE-Stream, der Server→Client-Anfragen (roots/list, Elicitation) überträgt. Der Server ist zustandsbehaftet: initialize erstellt eine Sitzung und gibt einen Mcp-Session-Id-Header zurück, den der Client bei jeder nachfolgenden Anfrage und im SSE-Stream zurücksenden muss. Anfragen mit fehlender/unbekannter/abgelaufener Sitzungs-ID erhalten HTTP 404, sodass der Client neu initialisiert (Standardverhalten von MCP-Clients). Jeder verbundene Client/Worktree ist eine isolierte Sitzung.

• Auth: Bei einem Loopback-Bind ist kein Token erforderlich. Das Binden einer Nicht-Loopback-Adresse erfordert ATLASSIAN_MCP_HTTP_TOKEN (von Clients als Authorization: Bearer … gesendet); andernfalls weigert sich der Server zu starten. Beenden Sie TLS an Ihrem Proxy.

• GET /healthz ist ein nicht authentifizierter Liveness-Healthcheck (gibt ok zurück) für Proxys/Load-Balancer. Leerlaufende Sitzungen werden nach 1 Stunde entfernt.

Der Repo-Kontext stammt vom Client, nicht vom Arbeitsverzeichnis des Servers. Tools, die ein Repo benötigen (die git_*-Tools, get_dev_context, start_work, complete_work und die Bitbucket-Projekt-/Repo-Autoerkennung), lösen es in dieser Reihenfolge auf: ein explizites repoPath-Argument → eine über einen Request-Header gepinnte Root (siehe unten) → die MCP-Workspace-Roots des Clients (der Server fragt über roots/list, cached pro Sitzung und aktualisiert bei notifications/roots/list_changed) → das Prozess-CWD (nur stdio). So verwaltet ein gemeinsamer HTTP-Server viele Worktrees: Der eigene Workspace jedes Clients steuert dessen Aufrufe. Wenn eine Sitzung mehrere Roots verfügbar macht (mehrere Worktrees), verwendet ein Tool ohne repoPath die erste Git-Repo-Root; übergeben Sie repoPath (einen absoluten Pfad oder einen Worktree-Namen/Basisnamen, der einer der Roots entspricht), um einen bestimmten Worktree anzusprechen. Bei Bitbucket überspringt die explizite Übergabe von projectKey+repoSlug die Repo-Erkennung vollständig. Die Repos müssen auf dem Host des Servers erreichbar sein (die Git-Tools führen git lokal aus).

Pinnen der Root über einen Request-Header (HTTP). Ein Reverse-Proxy oder eine Testumgebung, die den Arbeitsbaum bereits kennt, kann ihn direkt an den Server übergeben und so den roots/list-Roundtrip überspringen (und funktioniert auch, wenn der Client die roots-Fähigkeit nie angekündigt hat). Senden Sie eine file://-URI oder einen absoluten Pfad (durch Kommas getrennt für mehrere; das erste Git-Repo gewinnt):

X-Mcp-Root: file:///srv/myrepo
X-Mcp-Roots: /srv/a, /srv/b

Akzeptierte Header-Namen: X-Mcp-Roots, X-Mcp-Root, Mcp-Roots, Mcp-Root. Ein Header-Wert ist maßgeblich — er hat Vorrang vor roots/list und übersteht list_changed.

Client-Konfiguration für einen bereits laufenden HTTP-Server (Claude-Code-Beispiel):

claude mcp add --transport http atlassian http://127.0.0.1:7337/mcp

Pipeline zur Dekodierung von Anhängen

Die Anhang-Tools (jira_get_attachment, bitbucket_get_attachment) dekodieren binäre Anhänge in modelllesbaren Inhalt, bevor sie sie zurückgeben:

Automatisch gespeicherte Dateien werden regelmäßig per TTL und Gesamtgrößen-Kontingent bereinigt — siehe Umgebungsüberschreibungen unten.

Externe Tools (optional)

Bild- und PDF-Text-Dekodierung sind reines Go und benötigen nichts Zusätzliches. Die beiden Pipelines ohne reine Go-Implementierung greifen auf externe Binaries zurück:

• ffmpeg + ffprobe — Frame-Abtastung für Videos und animierte Bilder. Der npm-Wrapper bündelt ffmpeg-static / ffprobe-static und injiziert deren Pfade, sodass der npx-Installationspfad ohne Konfiguration auskommt. Bei den go install-/Nix-Pfaden installieren Sie ffmpeg (das ffprobe bereitstellt) oder setzen Sie die unten genannten Umgebungsvariablen.

• pdftoppm (poppler) oder mutool (MuPDF) — nur erforderlich, um gescannte PDFs ohne extrahierbaren Text zu rastern. Wenn keines im PATH ist, werden solche PDFs stattdessen auf der Festplatte gespeichert.

Umgebungsüberschreibungen

Releases (Maintainer)

Dieses Paket wird als @stubbedev/atlassian-mcp auf npm veröffentlicht.

Verwenden Sie semantische Versionierung für Releases. Bahnbrechende Änderungen an der Tool-Oberfläche sollten die Nebenversion erhöhen, solange <1.0.0 (z. B. 0.0.x -> 0.1.0).

Bei einem gepushten v*-Tag kompiliert .github/workflows/publish.yml das Go-Binary für 14 OS/Arch-Ziele, hängt sie an ein GitHub-Release an und veröffentlicht den npm-Wrapper (der das passende Binary bei der Installation herunterlädt).

Release-Ablauf:

# choose one: patch | minor | major (also: npm run release:patch / :minor / :major)
npm version patch          # bumps package.json, commits, tags vX.Y.Z
git push origin HEAD --follow-tags

flake.nix liest seine Version aus package.json, sodass das Nix-Paket denselben Versionssprung automatisch übernimmt. GitHub Actions baut und veröffentlicht vom gepushten Tag.

• Der Workflow ist für npm Trusted Publisher (OIDC) konfiguriert, sodass kein NPM_TOKEN-Secret erforderlich ist

Erforderliche npm-Einrichtung (einmalig):

• Fügen Sie in den npm-Paketeinstellungen dieses GitHub-Repo/diesen Workflow als Trusted Publisher hinzu

Erstellen von Personal Access Tokens

Jira Server / Data Center

Personal Access Tokens werden ab Jira 8.14 unterstützt.

1. Melden Sie sich bei Ihrer Jira-Instanz an.

2. Klicken Sie oben rechts auf Ihren Profil-Avatar und wählen Sie Profil.

3. Klicken Sie in der linken Seitenleiste auf Personal Access Tokens.

4. Klicken Sie auf Token erstellen.

5. Geben Sie dem Token einen Namen (z. B. atlassian-mcp) und legen Sie optional ein Ablaufdatum fest.

6. Klicken Sie auf Erstellen und kopieren Sie das Token — es wird nur einmal angezeigt.

Fügen Sie das Token als token-Wert unter jira in Ihrer Konfigurationsdatei ein.

Wenn Ihre Jira-Version älter als 8.14 ist, können Sie stattdessen HTTP Basic Auth verwenden — dieser Server unterstützt jedoch nur die Bearer-Token-Authentifizierung (PAT).

Bitbucket Server / Data Center

Personal Access Tokens werden ab Bitbucket Server 5.5 unterstützt.

1. Melden Sie sich bei Ihrer Bitbucket-Instanz an.

2. Klicken Sie oben rechts auf Ihren Profil-Avatar und wählen Sie Konto verwalten.

3. Klicken Sie in der linken Seitenleiste unter Sicherheit auf Personal access tokens.

4. Klicken Sie auf Token erstellen.

5. Geben Sie dem Token einen Namen (z. B. atlassian-mcp).

6. Legen Sie die Berechtigungen fest:

   • Projekte: Lesen

   • Repositories: Lesen + Schreiben (Schreiben ist erforderlich, um Pull Requests zu erstellen und Kommentare hinzuzufügen)

7. Legen Sie optional ein Ablaufdatum fest.

8. Klicken Sie auf Erstellen und kopieren Sie das Token — es wird nur einmal angezeigt.

Fügen Sie das Token als token-Wert unter bitbucket in Ihrer Konfigurationsdatei ein.

Entwicklung

Der Server ist ein einzelnes Go-Modul im Repo-Root (kein src/-Baum).

# Build the binary
go build -o atlassian-mcp .

# Run it
./atlassian-mcp --config /path/to/config.json

# Vet + unit tests
go vet ./...
go test ./...

# Test the tool list
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./atlassian-mcp

# Quick release smoke check (build + tools/list validation)
npm run smoke