@nexus2520/bitbucket-mcp-server weekly downloads statistics

Bitbucket MCP Server

MCP server for Bitbucket — built for AI coding agents that need to work with remote repositories as if they were local clones: grep-fast code search, windowed file reads, compact token-efficient responses, and a transport layer that never trips Bitbucket's rate limits.

Supports Bitbucket Server / Data Center (primary target) and Bitbucket Cloud.

Why v3

	v2	v3
Content search in a repo	1 listing + up to 3,000 file GETs	1 archive call cold, 0–1 calls warm
Search completeness	silently partial under server throttling	complete, with every cap reported
PR diff tokens	per-line JSON (~4× larger)	raw unified diff
Read a 100-line window	2 calls, full file transferred	1 call, window only
Blame a window of a huge file	up to 100 calls	1 call
Rate-limit safety	none (burst → 429/403)	client-side pacing sized to DC's limiter
Tools	33	25 (~30% less definition context)

Measured on a live Data Center instance: a repeated content search went from 519 API calls / ~7s (finding 1 of 8 real matches under burst throttling) to 0 API calls / 24ms finding all 8. Full design and verified API research: REVAMP_PLAN.md.

Tools (25)

Search (search) — Server/DC only

• grep — search file contents with full regex, any branch, like ripgrep on a local clone. One archive download per repo+commit, streamed in constant memory, cached in-process, freshness-checked every call (responses carry as_of <commit>). Omit query for filename-only glob listing. Modes: content, files, count; glob, path, context, case_insensitive, max_results.
• search_code — index-backed exact-term search across a whole project in one call (default branch only, case-insensitive, no regex, files <512 KiB, ~1000-result window). Best for cross-repo identifier lookups; use grep for everything else.
• search_repositories — find repos by name/description.

Pull requests (pr_core)

• get_pull_request — metadata + reviewer status + merge info in 1 call; include_comments / include_file_changes (default true), include_tasks, comment_limit. Returns version for follow-up mutations.
• list_pull_requests — repo-scoped; omit repository (Server) for your PRs across all repos in one call (role filter).
• create_pull_request, update_pull_request, merge_pull_request, decline_pull_request — all mutations accept version from a prior read (saves a fetch; auto-refetch + retry once on 409 conflicts).

Comments & tasks (pr_comments)

• add_comment — general, threaded reply, inline (file_path + line_number, or code_snippet auto-resolution), code suggestion, or task (severity: "BLOCKER", Server). Attachments upload via the attachments param (Server).
• manage_comment — edit / delete / resolve / reopen / to_task / to_comment on any comment or task, one call with version.

Review (pr_review)

• get_pull_request_diff — raw unified diff text; scope with file_path (server-side), include_patterns/exclude_patterns, context_lines, ignore_whitespace.
• set_review_status — APPROVED / NEEDS_WORK / UNAPPROVED (mutually exclusive; one call).

Commits (commits)

• list_pr_commits, list_branch_commits (server-side since-rev/merges filters; bounded page-walk for client-side author/until/search), get_commit_detail (unified diff, or detail: "files" for the changed-file list without bodies).

Branches (branches)

• list_branches, get_branch (branch + its PRs), delete_branch (expected_head skips the lookup call).

Files (files)

• get_file_content — windowed server-side: start_line/line_count transfer only that window (≤5000 lines/call). full_content / negative start_line for whole-file or tail reads.
• get_file_blame — commit-span blame for a line window in 1 call (Server).
• list_directory_content — paginated, compact.

Attachments (attachments, Server) / Discovery (discovery)

• manage_attachments (download capped, delete), list_projects, list_repositories.

Output conventions

• Bulk content (diffs, files, grep results) is plain text, not JSON-escaped strings; lists are compact JSON without pretty-printing. Dates are ISO-8601.
• Content-derived responses carry as_of <commit> so the agent knows exactly which state it saw.
• Truncation is never silent — every cap produces an explicit warning with continuation guidance (next_start, "narrow the glob", etc.).
• Mutable entities include version, so mutations don't need a re-read.

Installation

Requires Node.js 22 or newer (18 and 20 are end-of-life and no longer receive security fixes).

Using npx (recommended)

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

For Bitbucket Cloud use BITBUCKET_APP_PASSWORD instead of BITBUCKET_TOKEN (and omit BITBUCKET_BASE_URL).

Credential walkthroughs: Cloud app password · Server/DC HTTP token.

From source

git clone https://github.com/pdogra1299/bitbucket-mcp-server.git
cd bitbucket-mcp-server
npm install && npm run build
# point your MCP config at: node <repo>/build/index.js

Configuration…