bitbucket-mcp

MCP-Server für Bitbucket Cloud. Pull Requests, Code-Review, Branches, Source, Pipelines, Webhooks und Variablen – bereitgestellt als kontrollierte Tool-Oberfläche statt roher REST-Aufrufe.

Warum es das gibt

Der offizielle Atlassian MCP deckt nur Jira und Confluence ab. Bitbucket bleibt außen vor, sodass jede Repository-Operation auf handgeschriebene REST-Aufrufe zurückfällt: ausführliche Payloads, keine Leitplanken und ein Token, das alles erreichen kann, was der Scope erlaubt.

Dieser Server schließt diese Lücke an drei Fronten:

• Reduzierte Payloads. Antworten werden auf die Felder normalisiert, die du tatsächlich nutzt, sodass ein PR-Review nur einen Bruchteil des Kontexts einer rohen REST-Antwort verbraucht.

• Leitplanken im Server, nicht im Prompt. Geschützte Branches, confirm bei destruktiven Aktionen und ein Nur-Lese-Modus werden durchgesetzt, bevor der HTTP-Aufruf abgeht.

• Ein Tool pro Absicht. 55 Tools für die Review-, Branch-, Pipeline- und Webhook-Workflows statt eines generischen HTTP-Notausgangs.

flowchart LR
  A["MCP client<br/>(Claude Code, Inspector)"] -->|stdio| B["bitbucket-mcp"]
  B --> C{"Guards"}
  C -->|"read only, confirm,<br/>protected branch,<br/>workspace lock"| D["Bitbucket Cloud<br/>REST API"]
  C -.->|refused before<br/>the HTTP call| A
  B --> E["git over SSH<br/>or HTTPS"]
  E --> F["Repository"]
  D -->|normalized,<br/>trimmed response| A

Related MCP server: mcp-server-atlassian-bitbucket

Installation

Das Paket ist auf npm veröffentlicht als @marcusyoda/bitbucket-mcp.

Voraussetzungen

• Node >= 20

• Ein Atlassian-API-Token mit eingeschränktem Scope (siehe Auth)

• Ein auf Bitbucket registrierter SSH-Schlüssel für die git_*-Tools über SSH. Optional, wenn du stattdessen die HTTPS-Varianten verwendest.

Option 1: npx, nichts zu installieren

Der schnellste Weg. Richte deinen MCP-Client auf das Paket aus und lass npx es auflösen:

npx -y @marcusyoda/bitbucket-mcp

Option 2: globale Installation

npm install -g @marcusyoda/bitbucket-mcp
# or: pnpm add -g @marcusyoda/bitbucket-mcp
bitbucket-mcp

Option 3: aus dem Quellcode

git clone https://github.com/marcusyoda/bitbucket-mcp.git
cd bitbucket-mcp
pnpm install
pnpm build          # dist/index.js

In deinem MCP-Client registrieren

Claude Code, über die CLI

claude mcp add bitbucket \
  --env BITBUCKET_EMAIL=you@example.com \
  --env BITBUCKET_API_TOKEN=your-token \
  --env BITBUCKET_WORKSPACE=your-workspace \
  -- npx -y @marcusyoda/bitbucket-mcp

Beliebiger Client, über .mcp.json

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@marcusyoda/bitbucket-mcp"],
      "env": {
        "BITBUCKET_EMAIL": "you@example.com",
        "BITBUCKET_API_TOKEN": "your-token",
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_DEFAULT_REPO": "your-repo-optional"
      }
    }
  }
}

Stattdessen aus dem Quellcode ausführen? Ersetze den Befehl durch den gebauten Einstiegspunkt:

{ "command": "node", "args": ["/abs/path/to/bitbucket-mcp/dist/index.js"] }

Überprüfe die Verbindung, indem du get_current_user aufrufst: Er sendet das Token im Roundtrip und gibt deine Bitbucket-Identität zurück.

Authentifizierung

Die Authentifizierung erfolgt per HTTP Basic mit email:api_token. Erstelle ein API-Token mit eingeschränktem Scope unter id.atlassian.com > Manage account > Security > API tokens.

Token-Scopes (granularer Picker, erstelle nur, was du verwendest):

Die Variablen-Tools (*_variable*, list_deployment_*) benötigen admin:repository:bitbucket. Diesen Scope wegzulassen ist in Ordnung: Diese Tools geben einen 403 zurück und alles andere funktioniert weiter.

Die Begründung und der vollständige Berechtigungs-Entscheidungsbericht befinden sich in PERMISSIONS.md.

Umgebungsvariablen

Kopiere .env.example für lokale Ausführungen nach .env. Committe sie niemals.

Die .env des Pakets wird nur geladen, wenn BITBUCKET_API_TOKEN in der Umgebung fehlt. So gewinnt immer ein Launcher, der pro Projekt Anmeldedaten injiziert, und eine verirrte .env aus einem anderen Workspace kann das injizierte Token niemals überschreiben.

Sicherheitsmodell

• BITBUCKET_READ_ONLY=true blockiert jedes Schreib- und destruktive Tool, bevor es die API erreicht.

• Destruktive Tools (merge, decline, delete_*, stop_pipeline, git_commit, git_push, Inline-PR-Kommentare) erfordern confirm: true.

• Das Erstellen einer secured-Variable erfordert ebenfalls confirm: true.

• Werte gesicherter Variablen sind in der API nur schreibbar und werden niemals zurückgegeben oder protokolliert.

• Geschützte Branches (BITBUCKET_PROTECTED_BRANCHES, Standard main,dev) sind gegen direkte Änderungen hart gesperrt: git_push, git_rebase (wenn ausgecheckt), delete_branch und create_branch weigern sich, sie anzusteuern, selbst mit confirm. Bringe Änderungen dort über einen PR ein: merge_pull_request in einen geschützten Branch ist mit confirm: true erlaubt.

• Workspace-Sperre. Mit BITBUCKET_LOCK_WORKSPACE=true wird jeder Aufruf abgelehnt, der einen anderen Workspace nennt. Entwickelt für Maschinen, die mehrere Clients aus einer Installation bedienen.

Tools

Jedes Tool akzeptiert optionale workspace- und repo-Angaben, um die Standardwerte aus der Umgebung zu überschreiben.

Repo und Meta: get_current_user, list_repositories, get_repository, create_repository

Pull Requests: list_pull_requests, get_pull_request, get_pull_request_diff, get_pull_request_activity, create_pull_request, update_pull_request, approve_pull_request, unapprove_pull_request, request_changes_pull_request, decline_pull_request (confirm), merge_pull_request (confirm), list_pr_commits, get_diff

Kommentare: list_pr_comments, add_pr_comment (inline benötigt confirm), reply_pr_comment, update_pr_comment, delete_pr_comment (confirm), resolve_comment, react_pr_comment (experimentell)

Branches, Source und Git: list_branches, get_branch, create_branch, delete_branch (confirm), get_file_source, list_directory, clone_repo, clone_repo_https, git_commit (confirm), git_rebase, git_push (confirm), git_push_https (confirm). Alle Push- und Branch-Tools verweigern geschützte Branches.

Pipelines: list_pipelines, get_pipeline, get_pipeline_steps, get_pipeline_step_log, trigger_pipeline, stop_pipeline (confirm)

Variablen: list_repo_pipeline_variables, upsert_repo_pipeline_variable, delete_repo_pipeline_variable (confirm), list_workspace_variables, list_deployment_environments, list_deployment_variables, upsert_deployment_variable, delete_deployment_variable (confirm)

Webhooks: list_webhooks, get_webhook, create_webhook, update_webhook, delete_webhook (confirm)

SSH oder HTTPS für Git

clone_repo, git_commit, git_rebase und git_push verwenden deinen SSH-Schlüssel, nicht das Token. Wenn SSH keine Option ist, authentifizieren sich clone_repo_https und git_push_https mit username:token und benötigen BITBUCKET_USERNAME. Der Schutz für geschützte Branches gilt für beide Übertragungswege.

Bekannte Einschränkungen

• react_pr_comment ist experimentell. Emoji-Reaktionen auf PR-Kommentaren sind für Bitbucket Data Center dokumentiert, nicht für Cloud. Das Tool zielt auf einen Best-Effort-Endpunkt und kann einen Fehler zurückgeben, wenn dein Workspace dies nicht unterstützt.

• resolve_comment hängt davon ab, dass die Auflösung von Kommentarthreads für das Repository verfügbar ist.

• Es gibt keinen Endpunkt, der auflistet, welche Variablen eine benutzerdefinierte Pipeline erwartet. Diese Informationen stammen aus bitbucket-pipelines.yml; lies sie mit get_file_source.

• Gespeicherte Variablenwerte erfordern Admin-Scope, um sie wieder auslesen zu können.

Entwicklung

pnpm install
pnpm dev         # tsx watch
pnpm typecheck
pnpm build       # tsup, ESM
pnpm inspect     # build and open the MCP Inspector

Projektregeln und Konventionen stehen in CLAUDE.md. Beiträge folgen dem Issue-First-Workflow: Jeder Commit verlinkt in seiner Kopfzeile ein Issue, als type(scope): subject [#N].

Nutzung

MIT-lizenziert, und das ist wörtlich gemeint: Nutze es bei der Arbeit, nutze es kommerziell, forke es, binde es in deine eigenen Tools ein, benenne es um. Keine Erlaubnis nötig und kein Attributionsritual außer dem Beibehalten des Lizenzhinweises. Wenn es dir einen Nachmittag voller handgeschriebener REST-Aufrufe erspart, hat es sich bereits bezahlt gemacht.

Fehlt ein Tool, oder triffst du auf einen Bitbucket-Endpunkt, den dies nicht abdeckt? Öffne ein Issue. Pull Requests sind willkommen: Die einzige Hausregel ist, dass jeder Commit in seiner Kopfzeile ein Issue verlinkt, als type(scope): subject [#N].

Siehe LICENSE.