Bitbucket MCP Server

Ein MCP-Server (Model Context Protocol), der Tools für die Interaktion mit der Bitbucket-API bereitstellt und sowohl Bitbucket Cloud als auch Bitbucket Server unterstützt.

Funktionen

Verfügbare Tools (insgesamt 29)

PR Core (pr_core)

• get_pull_request - Vollständige PR-Details inklusive Kommentaren, Dateiänderungen und Merge-Informationen

• list_pull_requests - PRs auflisten mit Filtern (Status, Autor, Paginierung)

• create_pull_request - Neue Pull Requests erstellen

• update_pull_request - PR-Details aktualisieren (Titel, Beschreibung, Reviewer, Ziel-Branch)

• merge_pull_request - Pull Requests mit verschiedenen Strategien mergen

• decline_pull_request - Einen Pull Request ablehnen

PR-Kommentare (pr_comments)

• add_comment - Allgemeine, Inline-, Threaded- oder Vorschlagskommentare zu einem PR hinzufügen

• delete_comment - Einen Kommentar aus einem Pull Request löschen

Code Review (pr_review)

• get_pull_request_diff - Strukturierter zeilenweiser Diff mit ADDED/REMOVED/CONTEXT-Typen

• set_pr_approval - Einen PR genehmigen (approved: true) oder die Genehmigung zurückziehen (approved: false)

• set_review_status - Änderungen anfordern (request_changes: true) oder die Anforderung entfernen (false)

PR-Aufgaben — nur Bitbucket Server (pr_tasks)

• list_pr_tasks - Alle Aufgaben eines Pull Requests auflisten

• create_pr_task - Eine neue Aufgabe für einen Pull Request erstellen

• update_pr_task - Den Text einer bestehenden Aufgabe aktualisieren

• set_pr_task_status - Eine Aufgabe als erledigt markieren (done: true) oder wieder öffnen (done: false)

• delete_pr_task - Eine Aufgabe aus einem Pull Request löschen

• convert_pr_item - Einen Kommentar in eine Aufgabe umwandeln (direction: "to_task") oder umgekehrt ("to_comment")

Commits (commits)

• list_pr_commits - Alle Commits in einem Pull Request auflisten

• list_branch_commits - Commits in einem Branch auflisten mit Datums-/Autor-/Nachrichtenfiltern

• get_commit_detail - Den strukturierten Diff für einen bestimmten Commit per SHA abrufen

Branches (branches)

• list_branches - Branches auflisten mit Filterung und Paginierung

• get_branch - Detaillierte Branch-Informationen inklusive zugehöriger PRs und Statistiken

• delete_branch - Einen Branch löschen

Dateien (files)

• list_directory_content - Dateien und Verzeichnisse in einem Repository-Pfad auflisten

• get_file_content - Dateiinhalt abrufen mit intelligenter Kürzung für große Dateien

• search_files - Nach Dateien per Glob-Muster suchen (Groß-/Kleinschreibung ignoriert, wie VS Code Strg+P)

Suche — nur Bitbucket Server (search)

• search_code - Code über Repositories hinweg durchsuchen

• search_repositories - Nach Repositories anhand von Name oder Beschreibung suchen

Discovery (discovery)

• list_projects - Alle zugänglichen Bitbucket-Projekte/Workspaces auflisten

• list_repositories - Repositories in einem Projekt oder über alle zugänglichen Projekte hinweg auflisten

Token-Optimierung

v2.0.0 führt signifikante Token-Einsparungen bei jeder LLM-Anfrage ein:

Bitbucket Cloud blendet die 10 Server-only-Tools automatisch aus, ohne dass eine Konfiguration erforderlich ist.

BITBUCKET_TOOL_GROUPS ermöglicht es Ihnen, nur die für Ihren Workflow relevanten Gruppen freizugeben — siehe Tool-Gruppenfilterung unten.

Related MCP server: MCP Server

Installation

Verwendung von npx (Empfohlen)

Der einfachste Weg, diesen MCP-Server zu nutzen, ist direkt über npx:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Für Bitbucket Server:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

Aus dem Quellcode

1. Klonen oder laden Sie dieses Repository herunter

2. Abhängigkeiten installieren:

   npm install

3. TypeScript-Code bauen:

   npm run build

Authentifizierungseinrichtung

Dieser Server verwendet Bitbucket-App-Passwörter für die Authentifizierung.

Erstellen eines App-Passworts

1. Melden Sie sich bei Ihrem Bitbucket-Konto an

2. Navigieren Sie zu: https://bitbucket.org/account/settings/app-passwords/

3. Klicken Sie auf "App-Passwort erstellen"

4. Geben Sie eine beschreibende Bezeichnung ein (z. B. "MCP Server")

5. Wählen Sie die folgenden Berechtigungen:

   • Konto: Lesen

   • Repositories: Lesen, Schreiben

   • Pull Requests: Lesen, Schreiben

6. Klicken Sie auf "Erstellen"

7. Wichtig: Kopieren Sie das generierte Passwort sofort (Sie können es später nicht mehr sehen!)

Ausführen des Setup-Skripts

node scripts/setup-auth.js

Dies führt Sie durch den Authentifizierungsprozess.

Konfiguration

Fügen Sie den Server zu Ihrer MCP-Einstellungsdatei hinzu (normalerweise unter ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Ersetzen Sie:

• /absolute/path/to/bitbucket-mcp-server durch den tatsächlichen Pfad zu diesem Verzeichnis

• your-username durch Ihren Bitbucket-Benutzernamen (nicht die E-Mail-Adresse)

• your-app-password durch das von Ihnen erstellte App-Passwort

Für Bitbucket Server verwenden Sie:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

Wichtig für Bitbucket Server-Benutzer:

• Verwenden Sie Ihre vollständige E-Mail-Adresse als Benutzernamen (z. B. "john.doe@company.com")

• Dies ist erforderlich, damit Genehmigungs-/Review-Aktionen korrekt funktionieren

Tool-Gruppenfilterung

Reduzieren Sie die Anzahl der Tools, die bei jeder Anfrage an das LLM gesendet werden, indem Sie BITBUCKET_TOOL_GROUPS auf eine kommagetrennte Liste von Gruppennamen setzen. Nur Tools in den aufgeführten Gruppen werden freigegeben.

Verfügbare Gruppen

Beispiel-Voreinstellungen

PR-Review-Workflow (~2.100 Token):

"env": {
  "BITBUCKET_TOOL_GROUPS": "pr_core,pr_review,files"
}

Vollständiges PR-Management (~3.500 Token):

"env": {
  "BITBUCKET_TOOL_GROUPS": "pr_core,pr_comments,pr_review,pr_tasks"
}

Nur Code-Erkundung (~1.400 Token):

"env": {
  "BITBUCKET_TOOL_GROUPS": "files,search,discovery"
}

Wenn BITBUCKET_TOOL_GROUPS nicht gesetzt ist, werden alle anwendbaren Tools freigegeben (Standardverhalten). Bitbucket Cloud-Benutzer haben immer automatisch die Server-only-Tools ausgeblendet, unabhängig von dieser Einstellung.

Verwendung

Sobald konfiguriert, können Sie die verfügbaren Tools verwenden:

Pull Request abrufen

{
  "tool": "get_pull_request",
  "arguments": {
    "workspace": "PROJ",  // Required - your project key
    "repository": "my-repo",
    "pull_request_id": 123
  }
}

Gibt detaillierte Informationen über den Pull Request zurück, einschließlich:

• Titel und Beschreibung

• Autor und Reviewer

• Quell- und Ziel-Branch

• Genehmigungsstatus

• Links zur Web-UI und zum Diff

• Merge-Commit-Details (wenn der PR gemergt wurde):

  • merge_commit_hash: Der Hash des Merge-Commits

  • merged_by: Wer den Merge durchgeführt hat

  • merged_at: Wann der Merge stattfand

  • merge_commit_message: Die Merge-Commit-Nachricht

• Aktive Kommentare mit verschachtelten Antworten (ungelöste Kommentare, die Aufmerksamkeit erfordern):

  • active_comments: Array aktiver Kommentare (bis zu 20 der neuesten Top-Level-Kommentare)

    • Kommentartext und Autor

    • Erstellungsdatum

    • Ob es sich um einen Inline-Kommentar handelt (mit Dateipfad und Zeilennummer)

    • Verschachtelte Antworten (für Bitbucket Server):

      • replies: Array von Antwortkommentaren mit gleicher Struktur

      • Antworten können mehrfach tief verschachtelt sein

    • Eltern-Referenz (für Bitbucket Cloud):

      • parent_id: ID des Elternkommentars für Antworten

  • active_comment_count: Gesamtzahl der ungelösten Kommentare (einschließlich verschachtelter Antworten)

  • total_comment_count: Gesamtzahl aller Kommentare (einschließlich gelöster und Antworten)

• Dateiänderungen:

  • file_changes: Array aller im PR geänderten Dateien

    • Dateipfad

    • Status (hinzugefügt, geändert, entfernt oder umbenannt)

    • Alter Pfad (für umbenannte Dateien)

  • file_changes_summary: Zusammenfassende Statistiken

    • Gesamtzahl der geänderten Dateien

• Und mehr...

Code suchen

Suchen Sie nach Code in Bitbucket-Repositories (derzeit nur für Bitbucket Server unterstützt):

// Search in a specific repository
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "search_query": "TODO",
    "limit": 50
  }
}

// Search across all repositories in a workspace
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "search_query": "deprecated",
    "file_pattern": "*.java",  // Optional: filter by file pattern
    "limit": 100
  }
}

// Search with file pattern filtering
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "repository": "frontend-app",
    "search_query": "useState",
    "file_pattern": "*.tsx",  // Only search in .tsx files
    "start": 0,
    "limit": 25
  }
}

Gibt Suchergebnisse zurück mit:

• Dateipfad und Name

• Repository- und Projektinformationen

• Übereinstimmende Zeilen mit:

  • Zeilennummer

  • Vollständiger Zeileninhalt

  • Hervorgehobene Segmente, die exakte Übereinstimmungen zeigen

• Paginierungsinformationen

Beispielantwort:

{
  "message": "Code search completed successfully",
  "workspace": "PROJ",
  "repository": "my-repo",
  "search_query": "TODO",
  "results": [
    {
      "file_path": "src/utils/helper.js",
      "file_name": "helper.js",
      "repository": "my-repo",
      "project": "PROJ",
      "matches": [
        {
          "line_number": 42,
          "line_content": "    // TODO: Implement error handling",
          "highlighted_segments": [
            { "text": "    // ", "is_match": false },
            { "text": "TODO", "is_match": true },
            { "text": ": Implement error handling", "is_match": false }
          ]
        }
      ]
    }
  ],
  "total_count": 15,
  "start": 0,
  "limit": 50,
  "has_more": false
}

Hinweis: Dieses Tool funktioniert derzeit nur mit Bitbucket Server. Unterstützung für Bitbucket Cloud ist für ein zukünftiges Release geplant.

Pull Requests auflisten

{
  "tool": "list_pull_requests",
  "arguments": {
    "workspace": "PROJ",  // Required - your project key
    "repository": "my-repo",
    "state": "OPEN",  // Optional: OPEN, MERGED, DECLINED, ALL (default: OPEN)
    "author": "username",  // Optional: filter by author (see note below)
    "limit": 25,  // Optional: max results per page (default: 25)
    "start": 0  // Optional: pagination start index (default: 0)
  }
}

Gibt eine paginierte Liste von Pull Requests zurück mit:

• Array von Pull Requests mit denselben Details wie bei get_pull_request

• Gesamtzahl der passenden PRs

• Paginierungsinformationen (has_more, next_start)

Hinweis zum Autor-Filter:

• Für Bitbucket Cloud: Verwenden Sie den Benutzernamen (z. B. "johndoe")

• Für Bitbucket Server: Verwenden Sie die vollständige E-Mail-Adresse (z. B. "john.doe@company.com")

Pull Request erstellen

{
  "tool": "create_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "title": "Add new feature",
    "source_branch": "feature/new-feature",
    "destination_branch": "main",
    "description": "This PR adds a new feature...",  // Optional
    "reviewers": ["john.doe", "jane.smith"],  // Optional
    "close_source_branch": true  // Optional (default: false)
  }
}

Pull Request aktualisieren

{
  "tool": "update_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "title": "Updated title",  // Optional
    "description": "Updated description",  // Optional
    "destination_branch": "develop",  // Optional
    "reviewers": ["new.reviewer"]  // Optional - see note below
  }
}

Wichtiger Hinweis zu Reviewern:

• Wenn Sie einen PR aktualisieren, ohne den Parameter reviewers anzugeben, bleiben bestehende Reviewer und ihr Genehmigungsstatus erhalten

• Wenn Sie den Parameter reviewers angeben:

  • Die Reviewer-Liste wird durch die neue Liste ersetzt

  • Für Reviewer, die bereits im PR vorhanden sind, bleibt der Genehmigungsstatus erhalten

  • Neue Reviewer werden ohne Genehmigungsstatus hinzugefügt

• Dies verhindert das versehentliche Entfernen von Reviewern, wenn Sie nur die PR-Beschreibung oder den Titel aktualisieren möchten

Kommentar hinzufügen

Fügen Sie einen Kommentar zu einem Pull Request hinzu, entweder als allgemeiner Kommentar oder Inline zu spezifischem Code:

// General comment
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Great work on this PR!"
  }
}

// Inline comment on specific line
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Consider extracting this into a separate function",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT"  // ADDED, REMOVED, or CONTEXT
  }
}

// Reply to existing comment
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "I agree with this suggestion",
    "parent_comment_id": 456
  }
}

// Add comment with code suggestion (single line)
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This variable name could be more descriptive.",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT",
    "suggestion": "const userAuthenticationToken = token;"
  }
}

// Add comment with multi-line code suggestion
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This function could be simplified using array methods.",
    "file_path": "src/utils/calculations.js",
    "line_number": 50,
    "suggestion_end_line": 55,
    "line_type": "CONTEXT",
    "suggestion": "function calculateTotal(items) {\n  return items.reduce((sum, item) => sum + item.price, 0);\n}"
  }
}

Die Vorschlagsfunktion formatiert Kommentare mithilfe von Markdown-Vorschlagsblöcken im GitHub-Stil, die Bitbucket rendern kann. Beim Hinzufügen eines Vorschlags:

• suggestion ist erforderlich und enthält den Ersatzcode

• file_path und line_number sind bei Verwendung von Vorschlägen erforderlich

• suggestion_end_line ist optional und wird für mehrzeilige Vorschläge verwendet (Standard ist line_number)

• Der Kommentar wird mit einem suggestion Markdown-Block formatiert, der in der Bitbucket-UI anwendbar sein kann

Verwendung von Code-Snippets anstelle von Zeilennummern

Das Tool add_comment unterstützt jetzt das automatische Finden von Zeilennummern mithilfe von Code-Snippets. Dies ist besonders nützlich, wenn KI-Tools Diffs analysieren und Schwierigkeiten mit exakten Zeilennummern haben könnten:

// Add comment using code snippet
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This variable name could be more descriptive",
    "file_path": "src/components/Button.res",
    "code_snippet": "let isDisabled = false",
    "search_context": {
      "before": ["let onClick = () => {"],
      "after": ["setLoading(true)"]
    }
  }
}

// Handle multiple matches with strategy
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Consider extracting this",
    "file_path": "src/utils/helpers.js",
    "code_snippet": "return result;",
    "search_context": {
      "before": ["const result = calculate();"],
      "after": ["}"]
    },
    "match_strategy": "best"  // Auto-select highest confidence match
  }
}

Code-Snippet-Parameter:

• code_snippet: Die exakte Codezeile, die gefunden werden soll (Alternative zu line_number)

• search_context: Optionaler Kontext zur Unterscheidung mehrerer Übereinstimmungen

  • before: Array von Zeilen, die vor dem Ziel erscheinen sollten

  • after: Array von Zeilen, die nach dem Ziel erscheinen sollten

• match_strategy: Wie mit mehreren Übereinstimmungen umgegangen werden soll

  • "strict" (Standard): Fehler mit Anzeige aller Übereinstimmungen

  • "best": Automatische Auswahl der Übereinstimmung mit der höchsten Konfidenz

Fehlerantwort bei mehreren Übereinstimmungen (Strict-Modus):

{
  "error": {
    "code": "MULTIPLE_MATCHES_FOUND",
    "message": "Code snippet 'return result;' found in 3 locations",
    "occurrences": [
      {
        "line_number": 42,
        "file_path": "src/utils/helpers.js",
        "preview": "  const result = calculate();\n> return result;\n}",
        "confidence": 0.9,
        "line_type": "ADDED"
      },
      // ... more matches
    ],
    "suggestion": "To resolve, either:\n1. Add more context...\n2. Use match_strategy: 'best'...\n3. Use line_number directly"
  }
}

Diese Funktion ist besonders nützlich für:

• KI-gestützte Code-Review-Tools, die Diffs analysieren

• Skripte, die automatisch Kommentare basierend auf Codemustern hinzufügen

• Vermeidung von Verwirrung bei Zeilennummern in großen Diffs

Hinweis zu Kommentar-Antworten:

• Verwenden Sie parent_comment_id, um auf einen Kommentar zu antworten (allgemein oder Inline)

• In `get_