Skip to main content
Glama
bitbucket-standalone-mcp

bitbucket-standalone-mcp

by jabdon00

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 build

Output 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.js

BITBUCKET_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.mjs

Prints OK: 40 tools and lists every tool name. Tool invocations (e.g. bb_list_projects) do require valid credentials.

Inspector (interactive)

npm run inspect

Registering 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_PASSWORD in the real config with actual credentials before use. After editing opencode.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

bb_list_projects

List projects (filter, paginated)

bb_list_repositories

List repos (per-project or server-wide, filter, paginated)

bb_get_repository

Full repo details: state, default branch, clone URLs, web link

bb_create_repository

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

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 test

Cloud 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 tools
bb_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

    B3.4/5.0

    Scored across 41 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Bitbucket Server/Data Center (Stash) for project and repository discovery, pull request management, code review, and code search.
      10 npm
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      MCP server for Bitbucket Server integration, enabling project, repository, pull request, source code, branch, and code review operations via the Bitbucket Server APIs.
      27
      59 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      1
      ISC