MCP SERVERWork a remote Bitbucket repo like a local clone — regex grep, windowed file reads, PR review and merge.
LABSCO SUMMARY
The decision that matters is treating the repository as something you scan instead of something you page through: one archive fetch backs real regex grep on any branch, cached and freshness-checked every call, and file reads transfer only the line window you asked for. Content responses carry the commit they were taken at, and no cap cuts results quietly — a truncated answer arrives with the warning and the way to continue.
A Bitbucket client built for coding agents. It greps file contents with real regex on any branch, reads file windows without transferring the whole file, and covers pull requests end to end — comments, tasks, review status, diffs, merge. Bitbucket Server and Data Center are the primary target, with Cloud supported.
BITBUCKET_USERNAME plus a credential, and for Server or Data Center a BITBUCKET_BASE_URL. On Server and Data Center that credential is an HTTP access token in BITBUCKET_TOKEN; on Cloud it is an app password in BITBUCKET_APP_PASSWORD and the base URL is omitted. Runs over stdio through npx @nexus2520/bitbucket-mcp-server. Requests are paced client-side to Data Center's per-user limiter — BITBUCKET_RATE_LIMIT_RPS defaults to 5 and the burst to 50 — so set BITBUCKET_RATE_LIMIT_RPS=0 only when your service account holds an admin rate-limit exemption. The grep cache is capped by BITBUCKET_SNAPSHOT_MAX_MB, default 256. BITBUCKET_TOOL_GROUPS exposes only the groups you name, enforced at dispatch. Search, blame, attachments and cross-repo PR listing are Server and Data Center only.
One command plus credentials — npx -y @nexus2520/bitbucket-mcp-server, then supply credentials
USE CASES
Grep with a real regex on the branch you care about, scoped by glob, with context lines around each hit.
Read the PR with its comments and changed files in one call, then take the diff as unified text scoped to the files that matter.
Add an inline comment on the file and line, attach a code suggestion or raise a BLOCKER task, then set your review status.
Fetch a line window server-side instead of transferring the whole file, or tail it with a negative start line.
Blame the window in one call, then pull that commit's diff.
List your pull requests across every repository in one call, filtered by role.
Merge with the strategy and commit message you want, passing the version you already hold, then delete the source branch.
Run the index-backed exact-term search across the whole project, then narrow it with grep.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
add_commentAdd a PR comment: general, threaded reply (parent_comment_id), inline (file_path + line_number), code suggestion (suggestion), or task (severity BLOCKER, Server only). code_snippet auto-resolves line_number from exact diff text when line_number is unknown.
create_pull_requestCreate a pull request.
decline_pull_requestDecline a pull request, optionally with a comment. Pass version to save a fetch (Server).
delete_branchDelete a branch. Pass expected_head (commit SHA) to skip the lookup call (Server).
get_branchGet a branch with its latest commit and open PRs (include_merged_prs adds merged ones).
get_commit_detailGet a commit diff as raw unified diff text, or detail:"files" for just the changed-file list (no diff bodies).
get_file_blamePer-line blame as commit spans (one call per ≤5000-line window — pass start_line/line_count for big files). Pair commit ids with get_commit_detail. Server only.
get_file_contentRead a file. Windowed by default (start_line/line_count fetch ONLY that window server-side; ≤5000 lines per call). full_content=true or negative start_line (tail) fetches the whole file — prefer windows.
get_pull_requestGet a pull request: metadata, reviewer status, merge info, comments and changed files. Set include_comments/include_file_changes false for a 1-call metadata read; include_tasks lists open/resolved tasks. Response carries version for follow-up mutations.
get_pull_request_diffGet a PR diff as raw unified diff text (line numbers derive from @@ headers; +/- prefixes mark ADDED/REMOVED). Scope with file_path (server-side) or include/exclude glob patterns.
grepSearch file CONTENTS in a repo with full regex, like ripgrep on a local clone — any branch, no index gaps. One archive fetch per repo+commit, cached in memory and freshness-checked every call (responses show as_of commit). Omit query to list files by glob only. Modes: content (matches), files (paths), count. Scope with glob and/or path to keep scans fast. Server only.
list_branch_commitsList commits on a branch. since (as a rev) and include_merge_commits filter server-side; author/until/search and date-valued since filter client-side over a bounded page walk (noted when more pages exist).
list_branchesList branches (most recently modified first on Server).
list_directory_contentList files and directories at a repository path.
list_pr_commitsList commits in a pull request.
list_projectsList accessible projects/workspaces.
list_pull_requestsList pull requests in a repository. Omit repository (Server only) to list YOUR PRs across all repos in one call (filter with role).
list_repositoriesList repositories in a project (or all accessible on Server).
manage_attachmentsDownload or delete a repository attachment by numeric id (Server only). Upload via the attachments param on add_comment/create_pull_request/update_pull_request. No list API exists.
manage_commentEdit/delete/resolve/reopen a PR comment or task, or convert between comment and task (to_task/to_comment are Server-only). Pass version (from get_pull_request output) to save a fetch (Server).
merge_pull_requestMerge a pull request. Pass version to save a fetch.
search_codeIndex-backed exact-term code search across a whole PROJECT in one call (default branch only, files <512KiB, punctuation except . and _ ignored, case-insensitive, no regex, max ~1000 results). Best for cross-repo identifier lookups; for one repo, regex, or feature branches use grep.
search_repositoriesFind repositories by name/description across the instance. Server only.
set_review_statusSet YOUR reviewer status on a PR: APPROVED, NEEDS_WORK (request changes), or UNAPPROVED (clear). One call; the three states are mutually exclusive.
update_pull_requestUpdate a pull request. Reviewers/approvals are preserved unless reviewers is passed. Pass version (from get/list) to save a fetch.
BEFORE YOU INSTALL
25 tools when we connected. BITBUCKET_TOOL_GROUPS limits tools to named groups. The search group, get_file_blame and manage_attachments work only on Bitbucket Server/Data Center, not Cloud; v2 names such as find_in_files and list_pr_tasks were removed.
CONTEXT COST
Rated by the size of the 25 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Add the block to your client, or run the command directly.
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": [
"-y",
"@nexus2520/bitbucket-mcp-server"
],
"env": {
"BITBUCKET_USERNAME": "<YOUR_BITBUCKET_USERNAME>",
"BITBUCKET_TOKEN": "<YOUR_BITBUCKET_TOKEN>",
"BITBUCKET_BASE_URL": "<YOUR_BITBUCKET_BASE_URL>"
}
}
}
}The server reads BITBUCKET_USERNAME and a credential from its environment: on Bitbucket Server / Data Center, BITBUCKET_TOKEN (an HTTP access token) and BITBUCKET_BASE_URL; on Bitbucket Cloud, BITBUCKET_APP_PASSWORD (an app password) and no base URL.
npx -y @nexus2520/bitbucket-mcp-serverMCP servers
Ibrahimogod
garc33
ddukbg
AstroMined