mcp-bitbucket

Bitbucket Server für KI-Agenten und die Menschen daneben. Pull-Requests und ihre Diffs ohne Klon lesen, eine Review entwerfen und mit einem Urteil veröffentlichen, blockierende Aufgaben posten, Code und Commits durchsuchen, Pull-Requests öffnen, zusammenführen oder ablehnen – von einem MCP-Client, von einer Shell oder aus Ihrem eigenen TypeScript.

Nur Bitbucket Server / Data Center. Bitbucket Cloud wird nicht unterstützt.

Pakete

Claude Code / Claude Desktop Tool-Nutzung → mcp. Terminal, Skripte, CI, Agenten, die Befehle ausführen → cli. Wenn Sie etwas anderes bauen → core. Sie lesen dieselben Anmeldeinformationen und installieren sich nebeneinander.

Related MCP server: mcp-server-atlassian-bitbucket

Voraussetzungen

• Node.js 18+, pnpm 10+ (corepack enable)

• Ein Bitbucket-Server-Personal-Access-Token – Profil → Konto verwalten → HTTP-Zugriffstokens, mit Repository-Lesen + Pull-Request-Schreiben

• Nur für bb login (OS-Schlüsselbund): sudo apt install -y libsecret-1-0 gnome-keyring. Jeder Befehl funktioniert auch mit BITBUCKET_TOKEN.

Installation

pnpm install
pnpm build        # core first, then mcp and cli

Einstiegspunkte: packages/mcp/dist/index.js, packages/cli/dist/index.js.

Schnellstart

MCP-Server

claude mcp add mcp-bitbucket \
  -e BITBUCKET_URL=https://bitbucket.example.com \
  -e BITBUCKET_TOKEN=your-personal-access-token \
  -- node /absolute/path/to/mcp-bitbucket/packages/mcp/dist/index.js

Oder in .mcp.json (${VAR} wird von Claude Code expandiert, sodass kein Geheimnis committet wird):

{
  "mcpServers": {
    "mcp-bitbucket": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-bitbucket/packages/mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "${BITBUCKET_URL}",
        "BITBUCKET_TOKEN": "${BITBUCKET_TOKEN}"
      }
    }
  }
}

HTTP-Transport statt stdio: node packages/mcp/dist/index.js --http (Port 3000) oder MCP_HTTP_PORT=8080 node …. Routen: POST /mcp, GET /mcp (SSE), DELETE /mcp.

bb-CLI

pnpm --filter @mcp-bitbucket/cli link --global
bb login          # or export BITBUCKET_URL / BITBUCKET_TOKEN
bb whoami         # proves authentication — `bb ping` only proves reachability
bb pr get 42      # repository comes from the git origin remote

Befehlsübersicht: packages/cli/README.md oder bb --help.

Claude-Code-Skill

bash packages/skill/scripts/install.sh            # ~/.claude/skills/bitbucket-review
bash packages/skill/scripts/install.sh ./.claude  # project scope

Benötigt bb im PATH und eine auflösbare Anmeldeinformation.

Konfiguration

Umgebungsvariablen, .env im Repository-Stamm wird automatisch geladen (cp .env.example .env). Der MCP-Server validiert sie beim Start; die CLI akzeptiert auch --url / --token, die über allem stehen.

Grenzen

Jede numerische Obergrenze lebt in packages/core/src/operations/caps.ts und ist per Umgebungsvariable überschreibbar: BITBUCKET_DIFF_MAX_CHARS (60000), BITBUCKET_DIFF_HEAD_RATIO (0.6), BITBUCKET_DIFF_CONTEXT_LINES (3), BITBUCKET_DIFF_FETCH_MAX_CHARS (12000000), BITBUCKET_DIFF_CACHE_ENTRIES (4), BITBUCKET_CHANGED_FILES_MAX_ITEMS (1000), BITBUCKET_CHANGED_FILES_STATS_MAX_FILES (500). Die Kürzung ist nie still – der Hinweis nennt den Parameter und die Variable, die die Obergrenze anheben, und listet jeden ausgelassenen Hunk-Header auf.

Berechtigungen

Zwei unabhängige Schutzmechanismen.

MCP_PERMISSION_MODE – nur MCP-Server. Jedes Tool ist in packages/mcp/src/permissions.ts als read, write oder destructive klassifiziert; ein verbotenes Tool wird sowohl in ListTools versteckt als auch bei Aufruf mit Namen abgelehnt.

Die CLI liest es nicht. Eine readonly-Bereitstellung stoppt bb review merge nicht.

Repository-Zulassungsliste – beide Einstiegspunkte. BITBUCKET_ALLOWED_PROJECTS / BITBUCKET_ALLOWED_REPOS akzeptieren durch Komma, Semikolon oder Leerzeichen getrennte Muster: PROJ, PROJ/*, PROJ/repo-a. Die Prüfung läuft im gemeinsamen Client, bevor ein Socket geöffnet wird, sodass jedes Tool und jeder bb-Befehl sie erbt. Nicht gesetzt bedeutet jedes Repository. Groß-/Kleinschreibung wird ignoriert; persönliche Repos sind Projekt ~username. Ein fehlerhaftes Muster wird verworfen, nie erweitert – ein Wert, der nur aus fehlerhaften Mustern besteht, erlaubt nichts.

Tools

29 MCP-Tools: 17 lesend, 9 schreibend, 3 destruktiv. Vollständige Parameter in docs/tools.md.

Bemerkenswerte Standardeinstellungen

• Aufgelöste Diskussionen sind verborgen. get_pull_request_comments / bb comment ls benötigen includeResolved (--include-resolved), um aufgelöste Threads und Aufgaben zu zeigen; die Antwort sagt, wie viele verborgen wurden. Ein expliziter state-Filter überschreibt den Standard.

• Reviews werden entworfen, nicht veröffentlicht. add_pr_draft_comment / bb review draft speichern einen unsichtbaren Kommentar; submit_pr_review veröffentlicht jeden ausstehenden Kommentar mit einem Urteil als eine Benachrichtigung. pending: false (--no-pending) postet sofort; discard_pr_draft_review verwirft den Entwurf.

• bb ping ≠ Authentifizierung. /application-properties antwortet auf vielen Instanzen anonym mit 200. bb whoami ist die Authentifizierungsprüfung.

Entwicklung

pnpm build | typecheck | test | lint | format | clean
pnpm dev:mcp                 # MCP server from source (tsx)
pnpm cli pr ls               # bb from source
pnpm --filter @mcp-bitbucket/core test

Die Schichtungsregel, die verhindert, dass die Adapter auseinanderdriften:

• core weiß nichts über MCP oder die CLI – kein MCP-SDK, kein yargs, kein stdout. Operationen nehmen einen Client plus Parameter und geben strukturierte Daten zurück oder werfen eine Ausnahme.

• Adapter besitzen Eingabevalidierung und Ausgabeform – zod plus die MCP-Ergebnisform in mcp, yargs plus Text/--json in cli. Keines davon leckt in core.

• Fehlermeldungen werden einmal in core geschrieben, mit Platzhaltern im Stil von {projects} / {login}, die jeder Adapter in seiner eigenen Vokabular rendert – derselbe Fehler sagt einem Modell „verwende list_projects“ und Ihnen „verwende bb project ls“.

• Eine neue Fähigkeit ist eine Operation plus ein Formatierer in core, dann ein dünner Adapter in jedem von mcp und cli.

Docker

Das Image enthält nur den MCP-Server.

docker build -t mcp-bitbucket .
docker run -i --rm -e BITBUCKET_URL=… -e BITBUCKET_TOKEN=… mcp-bitbucket
docker run --rm -p 3000:3000 -e BITBUCKET_URL=… -e BITBUCKET_TOKEN=… -e MCP_HTTP_PORT=3000 mcp-bitbucket

Fehlerbehebung

docs/troubleshooting.md. Die drei häufigsten: Ein Tool, das in der Client-Liste fehlt, bedeutet, dass MCP_PERMISSION_MODE es versteckt hat (ein nicht erkannter Wert versteckt alle 29); Refused: … outside the configured repository allowlist bedeutet, dass die Zulassungsliste dieses Repo nicht abdeckt; weniger Kommentare als in der Web-UI bedeutet, dass aufgelöste Threads verborgen sind.

Einschränkungen

• Nur Bitbucket Server; kein Bitbucket Cloud, kein OAuth/SSO/App-Passwörter.

• bb login speichert Anmeldeinformationen nur im OS-Schlüsselbund – kein Klartextspeicher, kein --password.

• Keine Webhooks oder ereignisgesteuerter Modus; der Server beantwortet Tool-Aufrufe.

• Diffs sind serverseitig gerenderter Unified-Diff-Text; Inline-Kommentare, die im Diff verankert sind, werden nicht offengelegt.

• search_code benötigt den Code-Index der Instanz: Standard-Branch, ganze Wörter, kein Regex.

• MCP_PERMISSION_MODE beschränkt nur den MCP-Server; die Zulassungsliste beschränkt beide.