@droplinkperformance/bitbucket-mcp-server

Name: bitbucket mcp server
Author: droplinkperformance

Provider-agnostic, AI-review-first Model Context Protocol (MCP) server for Bitbucket Cloud.

The primary value of this server is AI-powered code review and pull request analysis, not CRUD against the Bitbucket API. Every major dependency (SCM access, cache, token storage, rate limiting, LLM, events) is hidden behind a provider-agnostic interface so the same business logic can later target GitHub / GitLab / Azure DevOps and OpenAI / Anthropic / Gemini / Bedrock without changes to use-cases, agents, or domain contracts.

Status: Phase 1. See Roadmap.

Features (Phase 1)

Dual transports: stdio (Cursor / Claude Desktop) and Streamable HTTP (Node http, for remote/production).
Auto-discovered tools via a ToolRegistry — no manual registration.
Explicit BitbucketContext (workspace + optional repository) on every tool — multi-workspace ready.
Resilient BitbucketClient: auth injection, auto-pagination, retry/backoff, rate-limit handling, caching, secret masking.
Two auth strategies: OAuth 2.0 (Authorization Code, with rotating refresh-token persistence) and Bearer token.
AI code review (analyze_pull_request) backed by a CodeReviewAgent that chunks large PRs and returns a standard ReviewResult.
Pluggable LLM provider (OpenAI / Anthropic / Gemini / Bedrock), cache (memory / Redis), and token store (file / memory / Redis).

Tools

Tool	Description
`get_current_user`	Authenticated user.
`list_pull_requests`	List PRs (filter by state/query).
`get_pull_request`	Fetch a PR by id.
`create_pull_request`	Open a PR.
`get_pull_request_diff`	Raw unified diff.
`get_pull_request_files`	Changed files + line stats.
`get_pull_request_comments`	PR comments.
`comment_pull_request`	Add a (optionally inline) comment.
`analyze_pull_request`	AI review returning a standard `ReviewResult`.

All tool inputs accept workspace (optional if BITBUCKET_DEFAULT_WORKSPACE is set) and, where applicable, repository.

Architecture

src/
  index.ts            entry: chooses transport
  container.ts        composition root (the only place wiring concretes)
  mcp/                McpServer + ToolRegistry (auto-discovery) + transports
  tools/              thin MCP adapters (*.tool.ts) -> call exactly one use-case
  application/        use-cases (CQRS-ish: command|query) with Input/Output DTOs
  agents/             autonomous workflows implementing Agent<TInput,TOutput>
  domain/             provider-agnostic types, repository contracts, ReviewResult
  repositories/bitbucket/  Bitbucket implementations of the contracts
  clients/bitbucket/  resilient REST client
  auth/               AuthProvider (+ token/oauth) and TokenStore implementations
  cache/              CacheProvider (+ memory/redis)
  ratelimit/          RateLimitStrategy (+ bitbucket)
  llm/                LlmProvider (+ openai/anthropic/gemini/bedrock)
  events/             EventBus (+ in-memory)
  services/           reusable services (masking, chunking)
  telemetry/          OpenTelemetry bootstrap + metrics
  infrastructure/     config, logger, http, attachments
  shared/             errors, result envelope, http-status, BitbucketContext

Flow: tool -> use-case -> (agent | repository contract) -> repositories/bitbucket -> BitbucketClient. Agents may also use the LlmProvider and EventBus. Tools never contain business logic.

Requirements

Node.js 23+

Install

Published as @droplinkperformance/bitbucket-mcp-server.

npx -y @droplinkperformance/bitbucket-mcp-server

From source:

npm install
npm run build

Release

Merges to main run .github/workflows/release.yml: tests, build, then semantic-release. Version and npm publish happen only when the merge includes Conventional Commits:

Commit	Bump
`fix:`	patch
`feat:`	minor
`BREAKING CHANGE` / `feat!:`	major

Other messages skip publish. The GitHub secret NPM_TOKEN (npm Automation token for the droplinkperformance org) is required.

After a successful npm release, the same workflow publishes metadata to the MCP Registry as io.github.droplinkperformance/bitbucket-mcp-server (OIDC, no extra secret). github.com/mcp syncs from that registry; if the server does not appear, email partnerships@github.com.

To stay on 0.x for the first release, tag the current commit (git tag v0.1.0 && git push origin v0.1.0) before the first conventional merge; otherwise semantic-release starts at 1.0.0.

Configuration

Copy .env.example to .env and fill in values. Load it with Node's built-in flag:

node --env-file=.env dist/index.js

Key variables:

Variable	Default	Notes
`MCP_TRANSPORT`	`stdio`	`stdio` or `http`.
`HTTP_HOST` / `HTTP_PORT`	`0.0.0.0` / `3000`	HTTP transport bind.
`BITBUCKET_DEFAULT_WORKSPACE`	–	Fallback when a tool omits `workspace`.
`BITBUCKET_ACCESS_TOKEN`	–	API token (ATATT…), app password, or OAuth access token
`BITBUCKET_EMAIL`	–	Required with API tokens (ATATT…) — your Atlassian account email
`BITBUCKET_CLIENT_ID` / `BITBUCKET_CLIENT_SECRET`	–	Required for OAuth (when no access token).
`BITBUCKET_REFRESH_TOKEN`	–	Optional seed for headless OAuth.
`TOKEN_STORE`	`file`	`file` \| `memory` \| `redis`.
`CACHE_PROVIDER`	`memory`	`memory` \| `redis`.
`LLM_PROVIDER`	`openai`	`openai` \| `anthropic` \| `gemini` \| `bedrock`.
`MAX_FILES_PER_CHUNK` / `MAX_DIFF_LINES_PER_CHUNK`	`50` / `5000`	Large-PR chunking thresholds.
`OTEL_ENABLED`	`false`	No-op metrics unless enabled.

Authentication

Bearer (OAuth access token): set BITBUCKET_ACCESS_TOKEN only (non-ATATT tokens).

API token (recommended, ATATT…): set BITBUCKET_ACCESS_TOKEN and BITBUCKET_EMAIL (your Atlassian account email from Bitbucket → Personal settings → Email aliases). API tokens use HTTP Basic auth, not Bearer.

App password (legacy, until June 2026): set BITBUCKET_ACCESS_TOKEN and BITBUCKET_USERNAME (your Bitbucket username).

OAuth 2.0 (Authorization Code): set BITBUCKET_CLIENT_ID / BITBUCKET_CLIENT_SECRET. Tokens are persisted by the configured TOKEN_STORE; Bitbucket rotates refresh tokens, and the server persists the new one on every refresh. For headless boot, provide a previously obtained BITBUCKET_REFRESH_TOKEN.

Bitbucket OAuth endpoints used: authorize https://bitbucket.org/site/oauth2/authorize, token https://bitbucket.org/site/oauth2/access_token. The authorize URL can be built from OAuthProvider.buildAuthorizeUrl() and the returned ?code= exchanged via OAuthProvider.loginWithCode(code).

LLM provider

Set LLM_PROVIDER and the matching key:

LLM_PROVIDER=openai      # OPENAI_API_KEY
LLM_PROVIDER=anthropic   # ANTHROPIC_API_KEY
LLM_PROVIDER=gemini      # GEMINI_API_KEY
LLM_PROVIDER=bedrock     # AWS creds + BEDROCK_MODEL_ID (needs @aws-sdk/client-bedrock-runtime)

ioredis (Redis providers) and @aws-sdk/client-bedrock-runtime (Bedrock) are optional and loaded lazily — only needed when selected.

Running

stdio

MCP_TRANSPORT=stdio node --env-file=.env dist/index.js

Streamable HTTP

MCP_TRANSPORT=http HTTP_PORT=3000 node --env-file=.env dist/index.js
# health:   GET  http://localhost:3000/health
# endpoint: POST http://localhost:3000/mcp

MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Cursor

~/.cursor/mcp.json (or project .cursor/mcp.json):

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@droplinkperformance/bitbucket-mcp-server"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BITBUCKET_ACCESS_TOKEN": "ATATT-your-api-token",
        "BITBUCKET_EMAIL": "you@company.com",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace",
        "LLM_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@droplinkperformance/bitbucket-mcp-server"],
      "env": {
        "BITBUCKET_ACCESS_TOKEN": "your-token",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace",
        "LLM_PROVIDER": "anthropic",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Development

npm run dev          # tsx watch (stdio)
npm run typecheck
npm run lint
npm test
npm run test:coverage

Roadmap

Phase 1 (this release): auth, abstractions, BitbucketClient, tool auto-discovery, PR tools, analyze_pull_request.
Phase 2: Pipelines + full-text paginated logs, pipeline-investigator agent, auto_review_pull_request (dry-run / publish inline comments).
Phase 3: Remaining CRUD — repositories, commits, branches, tags, issues, workspaces, members, search.
Phase 4: analyze_dotnet_pull_request (dotnet-review agent), advanced agents, automation workflows.
Phase 5: Docker, Compose, Helm, production deploy guide.

License

MIT