Bitbucket DC MCP Server

A Model Context Protocol (MCP) server that exposes Bitbucket Data Center REST API v1.0 as tools for AI assistants.

Overview

This server lets MCP-compatible clients (Claude Desktop, VS Code, IDEs, custom apps) interact with a Bitbucket Data Center instance through 55 tools covering:

• Projects — list, get, create, update

• Repositories — list, get, create, fork, default branch

• Pull Requests — CRUD, merge, decline, reopen, approve, reviewers, can-merge

• PR Comments — list, add, get, update, delete (inline + general)

• PR Diff & Changes — diffs, file changes, conflict markers

• PR Activity — activity feed, participants, watchers

• PR Tasks — blocker comment tasks

• Branches & Tags — list, create, delete

• Commits — list, get, changes, diff (whole commit or one file via path)

• Files — browse, read, edit, recursive listing

• Build Status — build statuses per commit, build statistics

• Merge Queue — enqueue, view, and process per-repository merge queues

graph LR
    A[AI Client] <-->|MCP| B[bitbucket-dc-mcp]
    B <-->|REST API v1.0| C[Bitbucket Data Center]

Example Prompts

Once connected, try asking your AI assistant:

• "List all repositories in the PROJ project"

• "Show me open pull requests in repo X"

• "What changed in PR #42? Summarize the diff"

• "Create a branch called feature/login from main in PROJ/my-repo"

• "Add a comment on PR #15 suggesting a fix for the null check on line 23"

• "What's the build status for the latest commit on main?"

• "Show me the last 10 commits on the develop branch"

• "Read the contents of src/index.ts from the main branch"

• "Are there any unresolved tasks blocking PR #8 from merging?"

• "Who approved PR #21 and what comments were left?"

• "Enqueue PR #5 into the merge queue for PROJ/my-repo"

• "Show me the merge queue for PROJ/my-repo"

• "Process the merge queue for PROJ/my-repo"

Related MCP server: bitbucket-standalone-mcp

Installation

Global install

npm install -g @shibainu16/bitbucket-dc-mcp

Using npx (no install required)

BITBUCKET_URL=https://bitbucket.example.com \
BITBUCKET_TOKEN=your-token \
MCP_TRANSPORT=stdio \
npx @shibainu16/bitbucket-dc-mcp

Prerequisites

• Node.js >= 22

• A Bitbucket Data Center instance with API access

• A personal access token or username/password credentials

Quick Start

1. Configure environment

Create a .env file (or export variables in your shell):

# Required — your Bitbucket DC base URL
BITBUCKET_URL=https://bitbucket.example.com

# Authentication (choose one)
BITBUCKET_TOKEN=your-personal-access-token
# OR
BITBUCKET_USERNAME=your-username
BITBUCKET_PASSWORD=your-password

# Optional
BITBUCKET_DEFAULT_PROJECT=MYPROJ
BITBUCKET_ENABLE_DANGEROUS=false
MCP_TRANSPORT=http
PORT=3000

2. Run

# If installed globally
bitbucket-dc-mcp

# Or via npx
npx @shibainu16/bitbucket-dc-mcp

The server starts in HTTP mode by default at http://localhost:3000/mcp.

Configuration

Environment Variables

* Either BITBUCKET_TOKEN or both BITBUCKET_USERNAME + BITBUCKET_PASSWORD are required.

Token Squeeze

Every tool result is shrunk before it reaches the model: compact JSON, links/link/avatarUrl and null/empty fields removed (false, 0 and an empty values page are kept), and long text capped at BITBUCKET_MAX_CHARS. List tools also return field-trimmed summaries. Set BITBUCKET_VERBOSE=true for raw output.

Transport Modes

HTTP Mode (Default)

Streamable HTTP transport for web deployments and remote access:

MCP_TRANSPORT=http bitbucket-dc-mcp

Endpoints:

• GET /mcp — SSE stream for server-initiated messages

• POST /mcp — JSON-RPC requests

• DELETE /mcp — Session termination

• GET /health — Health check

Each client gets its own MCP session (mcp-session-id header), so any number of clients can connect at once. Sessions with no POST/DELETE for MCP_SESSION_IDLE_TTL_MS expire (an open SSE stream does not keep them alive; clients re-initialize on 404), and when MCP_MAX_SESSIONS is reached new initialize requests get 503 with Retry-After.

Stdio Mode

Traditional stdio transport for local clients like Claude Desktop:

MCP_TRANSPORT=stdio bitbucket-dc-mcp

Client Integration

VS Code / GitHub Copilot

Add to your VS Code settings (settings.json) or workspace .vscode/mcp.json:

{
  "servers": {
    "bitbucket-dc-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@shibainu16/bitbucket-dc-mcp"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.example.com",
        "BITBUCKET_TOKEN": "your-token",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

If using settings.json directly, nest it under "mcp":

{
  "mcp": {
    "servers": {
      "bitbucket-dc-mcp": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@shibainu16/bitbucket-dc-mcp"],
        "env": {
          "BITBUCKET_URL": "https://bitbucket.example.com",
          "BITBUCKET_TOKEN": "your-token",
          "MCP_TRANSPORT": "stdio"
        }
      }
    }
  }
}

Claude Code

Add to your project's .mcp.json, or configure via the CLI:

claude mcp add bitbucket-dc-mcp \
  -e BITBUCKET_URL=https://bitbucket.example.com \
  -e BITBUCKET_TOKEN=your-token \
  -e MCP_TRANSPORT=stdio \
  -- npx -y @shibainu16/bitbucket-dc-mcp

Or manually create/edit .mcp.json in your project root:

{
  "mcpServers": {
    "bitbucket-dc-mcp": {
      "command": "npx",
      "args": ["-y", "@shibainu16/bitbucket-dc-mcp"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.example.com",
        "BITBUCKET_TOKEN": "your-token",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Development

git clone https://github.com/lvluu/bitbucket-dc-mcp.git
cd bitbucket-dc-mcp
bun install
bun run build

Testing

Unit tests (src/**/*.test.ts):

just test        # or: bun test src

End-to-end tests boot the built server and drive every tool through a real MCP client against a fake Bitbucket DC REST API (test/e2e/stub-bitbucket.mjs):

just e2e         # or: bun run test:e2e

Run the fake Bitbucket DC as a Docker container and test against it:

just e2e-docker  # or: bun run e2e:docker

The stub is a zero-dependency Node HTTP server (test/e2e/), so no license or large Atlassian image is needed. The e2e report is written to test/e2e/.last-run.json.

Releasing

Releases are automated with release-please. On every push to main, release-please opens/updates a release PR containing a generated CHANGELOG.md and a version bump derived from Conventional Commits. Merging that PR tags the release and publishes to npm with provenance — no manual npm publish.

One-time setup: add an npm automation token as the NPM_TOKEN repository secret (Settings → Secrets and variables → Actions).

Agents and contributors: see CLAUDE.md.

Troubleshooting

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, commands, and the Conventional Commits/release workflow, and CODE_OF_CONDUCT.md for community expectations. Please report security issues privately per SECURITY.md.

License

MIT — see LICENSE.

Resources

• Model Context Protocol Documentation

• Bitbucket Data Center REST API

• MCP Inspector