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

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