bitbucket-standalone-mcp
Provides tools for interacting with a Bitbucket Server / Data Center instance, enabling management of projects, repositories, branches, pull requests, comments, diffs, commits, files, search, and build statuses.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@bitbucket-standalone-mcp show open pull requests in the PROJ project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
bitbucket-standalone-mcp
A standalone Model Context Protocol (MCP)
server that exposes the REST v1.0 API of a Bitbucket Server / Data Center
(standalone) instance as MCP tools. Built for the local VCS at
http://vcs.tiddev.com (Bitbucket Server 7.12.1).
Runtime: Node.js 18+ (ESM, TypeScript)
Transport: stdio MCP
Auth: HTTP Basic (
BITBUCKET_USERNAME/BITBUCKET_PASSWORD)API base:
/rest/api/1.0(Bitbucket Server 7.x)
Why standalone
Bitbucket Server / Data Center (the "standalone" on-prem product, formerly
Bitbucket Server) speaks REST /rest/api/1.0 with Basic auth — not the
/rest/api/2.0 + HTTP-API-token flow of Bitbucket Cloud. This server targets
the Server product only.
Related MCP server: Bitbucket MCP Server
Build
npm install
npm run buildOutput lands in dist/. The entrypoint is dist/index.js.
Run
BITBUCKET_URL=http://vcs.tiddev.com \
BITBUCKET_USERNAME=<user> \
BITBUCKET_PASSWORD=<app-password> \
node dist/index.jsBITBUCKET_URL defaults to http://vcs.tiddev.com when unset.
Smoke test (no credentials required)
tools/list needs no auth, so the server can be verified offline:
node scripts/smoke.mjsPrints OK: 40 tools and lists every tool name. Tool invocations (e.g.
bb_list_projects) do require valid credentials.
Inspector (interactive)
npm run inspectRegistering with opencode
The server is registered in D:\Work\.opencode\opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"bitbucket-standalone-mcp": {
"type": "local",
"command": ["node", "D:\\Work\\bitbucket-standalone-mcp\\dist\\index.js"],
"enabled": true,
"environment": {
"BITBUCKET_URL": "http://vcs.tiddev.com",
"BITBUCKET_USERNAME": "<user>",
"BITBUCKET_PASSWORD": "<app-password>"
}
}
}
}Replace
REPLACE_WITH_USERNAME/REPLACE_WITH_PASSWORDin the real config with actual credentials before use. After editingopencode.json, quit and restart opencode — config is loaded once at startup and not hot-reloaded.
Catalog
~30 tools, namespaced bb_*. Replies are JSON or raw diff/file text.
Projects & repositories
Tool | Purpose |
| List projects (filter, paginated) |
| List repos (per-project or server-wide, filter, paginated) |
| Full repo details: state, default branch, clone URLs, web link |
| Create repo under a project (fork support) |
Branches
bb_list_branches, bb_get_branch, bb_create_branch, bb_delete_branch
Pull requests
bb_list_pull_requests (state/author/reviewer/text filters),
bb_get_pull_request, bb_create_pull_request, bb_update_pull_request
(title/description/reviewers), bb_merge_pull_request (noFF / fastForward /
squash / rebase / squashAndRebase / mergeAndLog / rebaseMessageMerge),
bb_decline_pull_request, bb_approve_pull_request,
bb_unapprove_pull_request
Comments
bb_list_pull_request_comments, bb_create_pull_request_comment (inline
anchors via anchoredTo or replies via parentCommentId),
bb_update_comment, bb_delete_comment, bb_resolve_comment
Diffs
bb_get_diff(from, until), bb_get_diff_summary, bb_get_pull_request_diff,
bb_get_pull_request_diff_summary
Commits
bb_get_commit, bb_list_commits (per-branch), bb_get_commit_diff,
bb_get_commit_parents
Files (in-repo read/write)
bb_list_directory, bb_get_file, bb_raw_file (full content),
bb_get_file_metadata, bb_create_file, bb_update_file, bb_delete_file
Search
bb_search_repositories, bb_search_code (text + project/repo/branch/path/date filters)
Builds / pipeline
bb_list_commit_builds (CI status per commit)
Admin
bb_application_properties (server version / connectivity check)
Pagination
List tools accept limit (default 25, max 100) and start (zero-based
offset). The first page is returned in one call; fetch the next page by
passing start = values.length.
Repository layout
bitbucket-standalone-mcp/
├─ src/
│ ├─ index.ts # McpServer wiring: registers every tool
│ ├─ client.ts # REST client (Basic auth, pagination, paths helper)
│ └─ tools/
│ ├─ types.ts # AnyToolDefinition contract + repoKeys helper
│ ├─ admin.ts branches.ts commits.ts comments.ts diffs.ts
│ ├─ files.ts pipelines.ts pull-requests.ts repos.ts search.ts
├─ dist/ # compiled JS (output of `npm run build`)
└─ scripts/smoke.mjs # offline tools/list smoke testCloud vs. Server: what's not here
This targets Server/Data Center only. Bitbucket Cloud features
(.rest/api/2.0 HTTP-token auth, branch status, pullrequest-task, GSSO) are
out of scope. npm run inspect + git clone the server for live
exploration.
Available Tools
41 toolsbb_application_propertiesA
Read server-wide application properties (read-only; modifications require admin). Useful for confirming connectivity and server version.
Inputs: no named parameters.
bb_approve_pull_requestB
Approve a PR as the authenticated user. Idempotent — re-approving is a no-op.
Inputs: id (required), repoSlug (required), projectKey (required).
bb_create_branchA
Create a new branch from a given start point (branch name or commit SHA).
Inputs: branch (required), repoSlug (required), projectKey (required), start.
bb_create_fileA
Create a new file at 'path' on 'branch' with 'content'. Optional 'message' is the commit message (default = 'Create '). Returns the new commit id and file path.
Inputs: path (required), branch (required), content (required), repoSlug (required), +2 more.
bb_create_pull_requestA
Create a new PR from a source branch to a destination branch. 'reviewer' is optional (username). Returns the created PR with its id.
Inputs: title (required), repoSlug (required), toBranch (required), fromBranch (required), +3 more.
bb_create_pull_request_commentA
Add a comment on a PR. Inline code comments need 'anchoredTo' (file path + line number + lineType). Plain text goes in 'text'. Returns the created comment.
Inputs: prId (required), text (required), repoSlug (required), projectKey (required), +14 more.
bb_create_repositoryA
Create a new repository under an existing project. Defaults: empty repo with initial 'master' branch, private. Set 'forkFrom' to fork from another repo.
Inputs: repoSlug (required), projectKey (required), name, forkFrom, +3 more.
bb_decline_pull_requestA
Decline an OPEN PR (closes it without merging). Returns the declined PR.
Inputs: id (required), repoSlug (required), projectKey (required).
bb_delete_branchA
Delete a branch from a repository. Refuses to delete the default branch.
Inputs: branch (required), repoSlug (required), projectKey (required).
bb_delete_commentC
Delete a comment. Returns confirmation.
Inputs: prId (required), repoSlug (required), commentId (required), projectKey (required).
bb_delete_fileA
Remove a file from 'branch' with a commit. The commit message is 'Delete ' by default.
Inputs: path (required), branch (required), repoSlug (required), projectKey (required), +1 more.
bb_detect_repoA
Given a project folder (relative to CWD or absolute), find its .git directory, read git remote get-url origin, and parse out the Bitbucket project key + repo slug. When the folder isn't itself a git repo, it searches the folder's children (up to 2 levels) for a git repo. If more than one is found, it lists the candidates and you must re-invoke with one of them. Returns { projectKey, repoSlug, remoteUrl, resolvedDir }.
Inputs: dir (required).
bb_get_branchA
Get details for one branch: name, latest commit id and author, relation to default branch.
Inputs: branch (required), repoSlug (required), projectKey (required).
bb_get_commitA
Get details for a single commit: message, author, date, parents, and relevant PRs. 'slug' can be a full SHA, short SHA, or 'HEAD'.
Inputs: commitId (required), repoSlug (required), projectKey (required).
bb_get_commit_diffA
Get the raw diff introduced by a single commit (the changes the commit makes relative to its parent).
Inputs: commitId (required), repoSlug (required), projectKey (required).
bb_get_commit_parentsA
Get the parent commits of a commit (usually one; two for a merge commit).
Inputs: commitId (required), repoSlug (required), projectKey (required).
bb_get_diffA
Get the full diff between two refs (commit SHA or branch name). 'until' defaults to the default branch. On this server the diff is reconstructed by walking /commits//diff along the branch lineage from until down to (but not including) from. Returns per-file entries with status, +N/−N counts and the unified diff body.
Inputs: from (required), repoSlug (required), projectKey (required), until.
bb_get_diff_summaryA
Get a per-file summary of the diff between two refs (commit SHA or branch name). 'until' defaults to the default branch. On this server it is reconstructed by walking /commits//diff along the branch lineage from until down to (but not including) from. Each entry: path, status, +N/−N counts, and a short preview (first ~400 chars of the file's diff).
Inputs: from (required), repoSlug (required), projectKey (required), until.
bb_get_fileA
Read the full content of a file at a ref. Returns the text content as-is (no wrapping).
Inputs: at (required), path (required), repoSlug (required), projectKey (required).
bb_get_file_metadataA
Get metadata about a file: name, parent directory, and commit that last touched it. Use for existence checks and audit trails.
Inputs: at (required), path (required), repoSlug (required), projectKey (required).
bb_get_pull_requestA
Get full details for a single PR: state, branches (from/to), author, reviewers, participants, version, and web link.
Inputs: id (required), repoSlug (required), projectKey (required).
bb_get_pull_request_diffA
Get the full unified diff for a PR (all changed files as one large diff text).
Inputs: prId (required), repoSlug (required), projectKey (required).
bb_get_pull_request_diff_summaryA
Get a per-file summary of what a PR changes: status, +N/−N counts, first hunk.
Inputs: prId (required), repoSlug (required), projectKey (required).
bb_get_repositoryA
Get full details for a single repository: project key, slug, name, state, default branch, fork source, clone URLs and web link.
Inputs: repoSlug (required), projectKey (required).
bb_list_branchesA
List branches in a repository. For each branch: name, latest commit, and how far it is behind/ahead of the default branch (when available). Paginated.
Inputs: repoSlug (required), projectKey (required), text, limit, +1 more.
bb_list_commit_buildsA
List build statuses for a commit (from CI providers reporting to Bitbucket). Each build: key, state (SUCCESS/FAILED/RUNNING/QUEUED), and URL.
Inputs: commitId (required), repoSlug (required), projectKey (required).
bb_list_commitsA
List commits on a branch in newest-to-oldest order. Each: short SHA, full SHA, message, author, date. 'branch' defaults to default branch. Paginated.
Inputs: repoSlug (required), projectKey (required), limit, start, +1 more.
bb_list_directoryA
List immediate children of a directory in a repo at a given ref (default branch or commit SHA). Each item: name, type (FILE/DIRECTORY), and path.
Inputs: repoSlug (required), projectKey (required), at, path.
bb_list_projectsA
List Bitbucket Server projects visible to the authenticated user. Returns project key, name, description, visibility and lock state. Paginated.
Inputs: limit, start, filter.
bb_list_pull_request_commentsA
List comments on a PR (including global and inline code comments). Each comment: id, text, author, state (OPEN/RESOLVED), anchored-to line/lineType, and web link. Paginated.
Inputs: prId (required), repoSlug (required), projectKey (required), path, +2 more.
bb_list_pull_requestsA
List pull requests in a repository. Filter by state (OPEN default, MERGED, DECLINED), author, reviewer, or text match on title/description. Paginated. Note: projectKey must be the exact uppercase key (e.g. 'USDMF'), not lowercase.
Inputs: repoSlug (required), projectKey (required), text, limit, +4 more.
bb_list_repositoriesA
List GIT repositories, either all at server level (no filter) or scoped to one project. Each item: project key, slug, name, state. Paginated.
Inputs: limit, start, filter, projectKey.
bb_merge_pull_requestB
Merge an OPEN PR. Strategy: 'noFF' (default three-way merge), 'fastForward', 'squash', 'rebase', or a custom variant string. Returns the merged PR.
Inputs: id (required), repoSlug (required), projectKey (required), version, +2 more.
bb_raw_fileA
Fetch the raw bytes of a file at a ref and return as plain text. Use this to read files. Binary files will be base64-encoded.
Inputs: at (required), path (required), repoSlug (required), projectKey (required).
bb_resolve_commentB
Mark a comment as resolved. Resolving a parent resolves the whole thread.
Inputs: prId (required), repoSlug (required), commentId (required), projectKey (required).
bb_search_codeA
Not available on this Bitbucket Server (v7.12.1). The code-search endpoint is disabled; use get_file / list_directory instead.
Inputs: text (required), path, repo, limit, +5 more.
bb_search_repositoriesA
Search repositories across the server by name/description. Returns project key, slug, name, and description for each match.
Inputs: text (required), limit, start, projectKey.
bb_unapprove_pull_requestB
Remove the authenticated user's approval from a PR.
Inputs: id (required), repoSlug (required), projectKey (required).
bb_update_commentB
Edit the text of an existing comment. Returns the updated comment.
Inputs: prId (required), text (required), repoSlug (required), commentId (required), +1 more.
bb_update_fileA
Replace the full content of an existing file on 'branch'. 'message' is the commit message (default = 'Update '). Returns the new commit id.
Inputs: path (required), branch (required), content (required), repoSlug (required), +2 more.
bb_update_pull_requestA
Update title/description/reviewers of a PR. Omitted fields are left unchanged. Returns the updated PR.
Inputs: id (required), repoSlug (required), projectKey (required), title, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 41 tools
Most tools map to a clear resource+action (repositories, branches, pull requests, files, commits), and the bb_ prefix plus descriptive names help separate them. The main ambiguities are bb_get_file vs bb_raw_file, which both read file content, and the several diff tools, but their parameter scopes and descriptions are usually enough to disambiguate.
All tools share a consistent bb_ prefix and overwhelmingly follow a verb_noun pattern such as list_repositories, create_pull_request, and delete_file. Minor deviations like bb_raw_file, bb_application_properties, and bb_detect_repo break the pattern slightly but remain understandable.
41 tools is well into the heavy range for a single MCP server, and the count is inflated by overlapping file readers, multiple diff variants, and a nonfunctional bb_search_code tool. While each tool is individually scoped, the surface is larger than an agent needs for most workflows.
The tool set covers the core developer lifecycle well: project/repo listing, branches, full pull request management with comments, diffs, commits, file read/write, build statuses, and local repo detection. Notable gaps such as repository/project update/delete, tags, and code search are present but do not block the primary Bitbucket workflows.
Maintenance
Related MCP Connectors
A MCP server built for developers enabling Git based project management with project and personal…
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Unofficial GitLab MCP — wraps the GitLab REST API v4 (BYO API key)
Manage Pipefork API projects, drafts, connections, secrets, and deployments through MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Bitbucket Server/Data Center (Stash) for project and repository discovery, pull request management, code review, and code search.10 npmMIT
- AlicenseBqualityBmaintenanceMCP server for Bitbucket Server integration, enabling project, repository, pull request, source code, branch, and code review operations via the Bitbucket Server APIs.2759 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Bitbucket Cloud REST API 2.0, supporting pull requests, pipelines, logs, and repository cloning through MCP tools.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with Bitbucket Server (Data Center) via MCP, supporting reading pull requests and diffs, drafting and submitting reviews with verdicts, posting tasks, browsing code and commits, and managing pull requests.1ISC