Bitbucket MCP Server

Ein auf den Produktionseinsatz ausgerichteter Model Context Protocol-Server zum Abrufen von Pull-Request-Metadaten und Diffs aus Bitbucket Cloud und Bitbucket Server/Data Center, mit Pull-Request-Kommentaren als Opt-in-Funktion.

Funktionen

• Unterstützt Bitbucket Cloud und selbst gehostetes Bitbucket Server/Data Center.

• Stellt fokussierte Tools für Pull-Request-Metadaten, Diffs, Review-Diskussionen sowie allgemeine oder Inline-Kommentare bereit.

• Unterstützt Bearer-Tokens und Basic-Authentifizierung.

• Gibt rohe Diffs sowie strukturierte Daten zu geänderten Dateien zurück, sofern Bitbucket sie bereitstellt.

• Schließt generierte Dateien, Ordner oder Dateitypen über konfigurierbare Glob-Muster aus.

• Begrenzt große Diffs, ohne UTF-8-Zeichen zu beschädigen.

• Verwendet stdio, ohne protokollverletzende Logs in stdout zu schreiben.

• Lässt die Kommentarerstellung standardmäßig deaktiviert und genehmigt, merged oder verändert Pull Requests nicht.

Related MCP server: Atlassian Bitbucket MCP Server

Schnellstart

Erfordert eine unterstützte Node.js-LTS-Version (Node.js 22 oder neuer).

git clone https://github.com/inceon/bitbucket-mcp.git
cd bitbucket-mcp
npm install
npm run build
cp .env.example .env

Setzen Sie BITBUCKET_URL und BITBUCKET_TOKEN in Ihrer MCP-Client-Konfiguration und starten Sie dann den kompilierten Server mit node dist/index.js. Der Server lädt bewusst keine .env-Dateien selbst; MCP-Clients sollten Umgebungsvariablen direkt übergeben.

Authentifizierung

Die Bearer-Authentifizierung ist die Standardmethode und wird für persönliche Zugriffstokens von Bitbucket Server/Data Center empfohlen:

BITBUCKET_URL=https://bitbucket.example.com/bitbucket
BITBUCKET_TOKEN=your-personal-access-token
BITBUCKET_AUTH_TYPE=bearer

Für Bitbucket-Cloud-API-Tokens oder App-Passwörter, die eine Basic-Authentifizierung erfordern:

BITBUCKET_URL=https://api.bitbucket.org
BITBUCKET_TOKEN=your-api-token-or-app-password
BITBUCKET_AUTH_TYPE=basic
BITBUCKET_USERNAME=your-bitbucket-username

Gewähren Sie der Anmeldeinformation nur die Berechtigungen, die für die von Ihnen aktivierten Tools erforderlich sind. Die Kommentarerstellung erfordert die Berechtigung, Pull-Request-Kommentare zu erstellen. Committen Sie niemals Anmeldedaten und geben Sie keine echten Tokens in Issue-Meldungen an.

Umgebungsvariablen

Der Server schreibt Startfehler nur nach stderr und schwärzt konfigurierte Anmeldedaten in Bitbucket-HTTP-Fehlerausschnitten.

MCP-Konfiguration

Claude-Desktop-Konfiguration:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/my-bitbucket-mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "https://api.bitbucket.org",
        "BITBUCKET_TOKEN": "your-token"
      }
    }
  }
}

Codex-config.toml-Konfiguration:

[mcp_servers.bitbucket]
command = "node"
args = ["/absolute/path/to/my-bitbucket-mcp/dist/index.js"]

[mcp_servers.bitbucket.env]
BITBUCKET_URL = "https://api.bitbucket.org"
BITBUCKET_TOKEN = "your-token"

Verfügbare Tools

get_pull_request

Gibt Pull-Request-Metadaten zurück, einschließlich Beschreibung, Status, Autor, Reviewer, Branches, Zeitstempel und Links.

{
  "name": "get_pull_request",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123
  }
}

get_pull_request_comments

Gibt vorhandene allgemeine und Inline-Diskussionen als native Kommentarobjekte des Anbieters zurück. Nutzen Sie es, bevor Sie einen Review-Befund posten, um vorhandenes Feedback zu berücksichtigen. commentsStatus.complete ist false mit dem Grund max_comments oder max_pages, wenn die konfigurierten Abrufgrenzen erreicht sind.

get_pull_request_commits

Gibt die derzeit im Pull Request enthaltenen natives Commits des Anbieters zurück. Nutzen Sie es, um einen Befund bis zu seinem Ursprungs-Commit zurückzuverfolgen oder zu prüfen, ob spätere Arbeiten ihn aufgreifen. commitsStatus.complete ist false mit dem Grund max_commits oder max_pages, wenn die konfigurierten Abrufgrenzen erreicht sind.

get_pull_request_diff

Gibt einen Review-Diff im Git-Stil und, sofern verfügbar, strukturierte geänderte Dateien zurück.

{
  "name": "get_pull_request_diff",
  "arguments": {
    "workspace": "PROJECT_KEY",
    "repository": "my-repository",
    "pull_request_id": 123,
    "ignore_patterns": ["dist/**", "**/*.generated.ts", "package-lock.json"],
    "path": "src/service.ts",
    "context": 5,
    "ignore_whitespace": true,
    "renames": true
  }
}

Die Diff-Ausgabe ist sowohl als abwärtskompatibler JSON-Text als auch als MCP-structuredContent mit einem deklarierten Ausgabeschema verfügbar. Sie enthält:

• provider, pull_request_id, rawDiff, rawDiffBytes und rawDiffSource. rawDiffSource ist provider_raw für Cloud oder server_structured für eine lokal normalisierte Antwort von Server/Data Center.

• truncated plus truncationReason: input_limit, wenn das vorgelagerte Cloud-Leselimit erreicht wurde, output_limit, wenn das gefilterte Ergebnis BITBUCKET_MAX_DIFF_BYTES überschritt, oder provider_limit, wenn Server/Data Center seinen strukturierten Diff als abgeschnitten markiert hat.

• Optionale kompakte files-Einträge enthalten nur path, normalisierten status und oldPath für Umbenennungen oder Kopien. Das erforderliche filesStatus meldet die Vollständigkeit; complete ist false mit dem Grund max_files, max_pages oder unsupported, und returned spiegelt die tatsächlich zurückgegebenen gefilterten Einträge wider.

• Optionale ignored-Metadaten, wenn Ausschlüsse aktiv sind.

Vollständiges Ergebnis:

{
  "provider": "cloud",
  "pull_request_id": 123,
  "rawDiff": "diff --git ...",
  "rawDiffBytes": 128,
  "rawDiffSource": "provider_raw",
  "files": [],
  "filesStatus": { "available": true, "complete": true, "returned": 0 },
  "truncated": false
}

Begrenztes Teilergebnis:

{
  "provider": "cloud",
  "pull_request_id": 123,
  "rawDiff": "diff --git ...",
  "rawDiffBytes": 200000,
  "rawDiffSource": "provider_raw",
  "files": [{ "path": "src/service.ts", "status": "modified" }],
  "filesStatus": {
    "available": true,
    "complete": false,
    "returned": 1,
    "reason": "max_pages"
  },
  "truncated": true,
  "truncationReason": "output_limit"
}

Ein abgeschnittenes rawDiff ist ein UTF-8-sicheres Review-Präfix, nicht unbedingt eine vollständige Zeile, ein vollständiger Hunk oder ein anwendbarer Patch.

Strukturierte Dateiseiten werden verfolgt, bis sie vollständig sind oder bis eine konfigurierte Datei-/Seitengrenze erreicht ist, und dann zu kompakten Review-Metadaten normalisiert, anstatt Anbieter-Hashes, Links und doppelte Pfadstrukturen zurückzugeben. Ein nicht verfügbarer diffstat- oder changes-Endpunkt wird erst nach HTTP 404 gemeldet. Autorisierungs-, Rate-Limit-, Server-, Fehlantwort-, Timeout- und Transportfehler lassen den Tool-Aufruf fehlschlagen, anstatt Metadaten stillschweigend wegzulassen.

Cloud-rawDiff bewahrt die rohe Antwort des Anbieters. Server/Data Center verwendet die strukturierte /diff-Antwort und normalisiert deren Dateien, Hunks, Segmente und Zeilen zu Review-Text im Git-Stil; dies vermeidet versionsspezifische Fehler des separaten .diff-Exportwegs. rawDiffSource macht diese Unterscheidung explizit.

path wird für beide Anbieter unterstützt und ist der bevorzugte Weg, große Pull Requests dateiweise zu prüfen; die zurückgegebenen files-Metadaten sind auf denselben Pfad beschränkt. renames gibt es nur in Cloud. context wird auf Cloud-context und die contextLines von Server/Data Center abgebildet. ignore_whitespace wird auf Cloud-ignore_whitespace und whitespace=ignore-all von Server/Data Center abgebildet. Wenn diese Steuerelemente fehlen, ändern sie die Anbieterstandardwerte nicht.

Muster verwenden repository-relative Pfade und unterstützen *, ** und ?. Ein Muster ohne /, wie package-lock.json oder *.png, findet diesen Dateinamen überall. Ein abschließender Schrägstrich schließt ein Verzeichnis rekursiv aus. Wenn Ausschlüsse aktiv sind, enthält die Antwort ignored.patterns, ignored.files und ignored.rawDiffFiltered. Ein false-Wert bei rawDiffFiltered bedeutet, dass ein Cloud-Anbieter ein Nicht-Git-Diff-Format zurückgegeben hat, das nicht sicher gefiltert werden konnte; die Antwort wird beibehalten, anstatt Inhalte stillschweigend zu verwerfen.

add_pull_request_comment

Erstellt einen allgemeinen Kommentar, einen Kommentar auf Dateiebene oder einen Inline-Zeilenkommentar zu einem Pull Request. Dieser Schreibvorgang ist nur verfügbar, wenn BITBUCKET_ENABLE_WRITE_TOOLS=true in der MCP-Serverumgebung gesetzt ist.

Allgemeiner Kommentar:

{
  "name": "add_pull_request_comment",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123,
    "comment": "The implementation looks good. Please add a regression test for the empty input case."
  }
}

Inline-Kommentar zu einer hinzugefügten Zeile:

{
  "name": "add_pull_request_comment",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123,
    "comment": "Please handle an empty value here.",
    "file_path": "src/service.ts",
    "line": 42,
    "line_type": "added"
  }
}

Verwenden Sie die line_type-Werte added, removed oder context. Hinzugefügte Zeilen verwenden standardmäßig die new-Seite, entfernte Zeilen die old-Seite und Kontextzeilen new; setzen Sie line_side explizit, um einen Kontextkommentar auf old zu platzieren. Geben Sie file_path ohne Zeilenfelder für einen Kommentar auf Dateiebene an. Bei umbenannten Dateien in Server/Data Center kann source_file_path den vorherigen Pfad angeben.

Der authentifizierte Bitbucket-Benutzer wird zum Kommentarautor. Prüfen Sie den Ziel-Workspace, das Repository, die Pull-Request-ID und den Kommentartext, bevor Sie den Tool-Aufruf in Ihrem MCP-Client genehmigen.

Anbieterverhalten

Der URL-Host bestimmt den Anbieter. bitbucket.org und api.bitbucket.org verwenden Bitbucket Cloud; alle anderen Hosts verwenden Server/Data Center.

Cloud-URLs werden auf ein /2.0-API-Präfix normalisiert und verwenden:

• /repositories/{workspace}/{repository}/pullrequests/{id}

• /repositories/{workspace}/{repository}/pullrequests/{id}/diff

• /repositories/{workspace}/{repository}/pullrequests/{id}/diffstat

• /repositories/{workspace}/{repository}/pullrequests/{id}/comments (GET; POST, wenn aktiviert)

• /repositories/{workspace}/{repository}/pullrequests/{id}/commits (GET)

Die URLs von Server/Data Center erhalten einen Kontextpfad wie /bitbucket, normalisieren auf ein /rest/api/1.0-Präfix und verwenden:

• /projects/{project}/repos/{repository}/pull-requests/{id}

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff (strukturierter Diff, zu Review-Text im Git-Stil normalisiert)

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff/{path} (pfadbezogener strukturierter Diff)

• /projects/{project}/repos/{repository}/pull-requests/{id}/changes

• /projects/{project}/repos/{repository}/pull-requests/{id}/comments (GET; POST, wenn aktiviert)

• /projects/{project}/repos/{repository}/pull-requests/{id}/commits (GET)

Die optionale diffstat- oder changes-Anfrage meldet nach HTTP 404 filesStatus.reason: "unsupported". Andere HTTP-, Timeout-, Transport- und Parsing-Fehler lassen den Tool-Aufruf fehlschlagen, sodass unvollständige Metadaten nicht für eine vollständige Antwort gehalten werden.

Atlassian Rovo MCP

Atlassian dokumentiert die nur in der Cloud verfügbare Aktion bitbucketPullRequest.diff, veröffentlicht aber weder das Argumentschema noch die Ausgabestruktur noch einen Vertrag über Paginierung, Filterung oder Kürzung. Dieser Server behandelt deshalb die direkten Bitbucket-APIs weiterhin als maßgeblich. Ein Rovo-Adapter sollte erst nach der Validierung eines live abgefragten tools/list-Schemas und einer kontrollierten diff-Antwort hinzugefügt werden; er muss weiterhin explizit konfiguriert sein und kann die Unterstützung von Server/Data Center nicht ersetzen. Siehe Atlassians Seite zu unterstützten Tools.

Roadmap

Geplante Bereiche für zukünftige Versionen:

• Retry-Handling und klarere Rate-Limit-Diagnostik hinzufügen.

• Normalisierte Pull-Request-Ausgabe liefern, wobei der Zugriff auf anbieterspezifische Felder erhalten bleibt.

• Schreibgeschützte Tools zum Auflisten von Pull Requests und zum Abrufen der Build-Status hinzufügen.

• Optionalen Streamable-HTTP-Transport anbieten, wobei stdio weiterhin Standard ist.

• Versionierte Releases mit einfacheren Installations- und Upgrade-Pfaden veröffentlichen.

Schreiboperationen bleiben standardmäßig deaktiviert. Das Genehmigen, Zusammenführen und weitere Bitbucket-Operationen mit großer Auswirkung sind nicht geplant. Ideen und Implementierungsvorschläge sind über GitHub Issues willkommen.

Entwicklung

npm run dev        # Run directly from TypeScript
npm run build      # Compile to dist/
npm test           # Run the test suite once
npm run test:watch # Run tests in watch mode
npm run check      # Build and test, matching CI

Die Befehlsregistrierung hält jedes MCP-Tool unter src/tools isoliert. Siehe CONTRIBUTING.md, bevor du einen Pull Request eröffnest.

Sicherheit

Dieser Server verarbeitet Zugangsdaten und sendet sie ausschließlich an die konfigurierte BITBUCKET_URL. Prüfe diese URL sorgfältig, bevor du den Server startest. Wenn die Schreib-Tools aktiviert sind, können verbundene MCP-Clients PR-Kommentare als authentifizierter Bitbucket-Benutzer veröffentlichen. Um eine Sicherheitslücke vertraulich zu melden, folge den Anweisungen in SECURITY.md.

Lizenz

Veröffentlicht unter der MIT-Lizenz.