使用说明

Atlassian Bitbucket MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Atlassian Bitbucket for pull request reviews, code search, and repository operations.

Features

Pull Request Management: Review PRs, add/resolve comments, approve changes
Batched Reviews: Queue comments and tasks as pending, then publish them in one review — the API equivalent of Bitbucket's Start review / Finish review
Code Search: Search code across repositories and commits
Repository Operations: List repos, browse branches, view file content
Dual Instance Support: Works with both Bitbucket Cloud and self-hosted Data Center/Server
Secure: Built with security in mind, avoiding compromised npm packages
Type-Safe: Full TypeScript implementation with strict type checking
Caching: Smart caching layer for frequently accessed static data
Local-First: Designed for NPX-based local usage with Personal Access Tokens
CI Helper: atlassian-bitbucket-mcp/helper subpath export for direct programmatic use in CI scripts — no MCP client required

Requirements

Node.js >= 20.0.0
pnpm
Bitbucket Personal Access Token (Cloud or Server/Data Center)
Access to a Bitbucket instance (Cloud or self-hosted)

Quick Start

1. Environment Setup

Copy the example environment file and configure it:

cp .env.example .env

Edit .env and set the required variables:

BITBUCKET_URL=https://bitbucket.juspay.net # Cloud: https://bitbucket.org
BITBUCKET_TOKEN=BBDC-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
BITBUCKET_DEFAULT_PROJECT=BZ # your default project key

For a self-hosted Server/DC instance, set BITBUCKET_URL to the base URL only (e.g. https://bitbucket.juspay.net) — the server appends /rest/api/1.0 itself. A repo such as https://bitbucket.juspay.net/projects/BZ/repos/nimble has project key BZ and repo slug nimble.

2. Installation

Beta channel: the current release stream is 1.0.0-beta.0 on the npm beta dist-tag. Install with:
npm install atlassian-bitbucket-mcp@beta
# or
pnpm add atlassian-bitbucket-mcp@beta
The latest dist-tag is not published yet.

pnpm install

3. Build

pnpm run build

4. Usage with MCP Client

Configure your MCP client (e.g., Claude Desktop) to use this server:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "atlassian-bitbucket-mcp"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.juspay.net",
        "BITBUCKET_TOKEN": "BBDC-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "BITBUCKET_DEFAULT_PROJECT": "BZ",
        "BITBUCKET_ALLOWED_PROJECTS": "BZ",
        "BITBUCKET_ALLOWED_REPOS": "BZ/nimble"
      }
    }
  }
}

BITBUCKET_ALLOWED_PROJECTS and BITBUCKET_ALLOWED_REPOS are optional — omit them to allow all projects/repos the token can access, or set them to restrict the server to specific scopes.

This is the stdio transport: the MCP client launches the server per session. No port is involved.

5. Run as an HTTP MCP (local service)

The server can instead run as a long-lived Streamable HTTP server and be registered as a Claude HTTP MCP. Set MCP_TRANSPORT=http and it listens on http://127.0.0.1:3900/mcp (configurable via MCP_HTTP_PORT / MCP_HTTP_HOST; GET /health returns a readiness probe). Set MCP_TRANSPORT=https to serve the same endpoint over TLS — see below.

Security: the HTTP endpoint is unauthenticated and sits in front of your Bitbucket token — keep MCP_HTTP_HOST on loopback (127.0.0.1) and never expose it to a network interface.

On macOS, install it as an always-on login service (launchd LaunchAgent):

# Builds, installs globally, writes ~/.config/bitbucket-mcp/env (chmod 600),
# and loads a LaunchAgent bound to 127.0.0.1:3900.
./scripts/install-macos-service.sh
# then put your real BITBUCKET_TOKEN in ~/.config/bitbucket-mcp/env and:
launchctl kickstart -k gui/$(id -u)/com.juspay.bitbucket-mcp

claude mcp add --scope user --transport http bitbucket http://127.0.0.1:3900/mcp
claude mcp list # bitbucket ... ✔ Connected

Serving over TLS (MCP_TRANSPORT=https). The HTTP transport can serve TLS itself: set MCP_TRANSPORT=https plus MCP_HTTP_TLS_CERT_FILE and MCP_HTTP_TLS_KEY_FILE (paths to PEM files — both are required in https mode and ignored otherwise). Everything else (/mcp endpoint, sessions, /health) is identical to http mode. For a locally-trusted certificate, use mkcert:

mkcert -install && mkcert localhost 127.0.0.1

MCP_TRANSPORT=https
MCP_HTTP_TLS_CERT_FILE=/absolute/path/to/localhost+1.pem
MCP_HTTP_TLS_KEY_FILE=/absolute/path/to/localhost+1-key.pem

TLS adds encryption, not authentication — the endpoint is still unauthenticated, so keep MCP_HTTP_HOST on loopback in https mode too.

Self-hosted TLS / internal CA. If your Bitbucket uses an internal CA, the outbound HTTPS calls need to trust it. Set NODE_EXTRA_CA_CERTS=/path/to/ca.pem in the env-file. Avoid Node's --use-system-ca for the background service — it hangs under launchd because macOS keychain access requires an interactive session. (--use-system-ca is fine for a foreground/stdio run.)

Configuration

Environment Variables

All configuration is done through environment variables. See .env.example for the complete list.

Required

BITBUCKET_URL - Your Bitbucket instance URL
BITBUCKET_TOKEN - Personal Access Token
BITBUCKET_DEFAULT_PROJECT - Default project key

Optional

BITBUCKET_ALLOWED_ACTIONS - Comma-separated list of allowed tool actions
BITBUCKET_ALLOWED_PROJECTS - Comma-separated allow-list of project keys the server may touch (empty = all). Case-insensitive.
BITBUCKET_ALLOWED_REPOS - Comma-separated allow-list of repositories (empty = all). Each entry is PROJECT/REPO or a bare REPO slug. Case-insensitive.
BITBUCKET_CACHE_ENABLED - Enable/disable caching (default: true)
BITBUCKET_CACHE_TTL_REPOS - Repository cache TTL in seconds (default: 3600)
MCP_TRANSPORT - stdio (default), http, or https
MCP_HTTP_PORT / MCP_HTTP_HOST - HTTP transport bind (default 3900 / 127.0.0.1)
MCP_HTTP_TLS_CERT_FILE / MCP_HTTP_TLS_KEY_FILE - PEM certificate/key paths, both required when MCP_TRANSPORT=https (ignored otherwise)
NODE_EXTRA_CA_CERTS - PEM path for a self-hosted internal CA (outbound TLS)
BITBUCKET_MCP_CONFIG, BITBUCKET_MCP_MAX_OUTPUT_TOKENS, BITBUCKET_MCP_CONFIG_DIR — output-token-limit governor (see Per-tool output-token limits)
See .env.example for all options

Creating a Personal Access Token

Bitbucket Cloud

Go to Personal settings > Personal Access Tokens
Click Create token
Give it a name and select permissions:
- Repositories: Read, Write
- Pull requests: Read, Write
Click Create and copy the token

Bitbucket Server/Data Center

Go to Profile > Manage account > Personal access tokens
Click Create a token
Give it a name and select permissions:
- Project permissions: Read
- Repository permissions: Read, Write
Click Create and copy the token

Per-tool output-token limits

The server can withhold oversize tool responses and return an actionable guidance error instead of streaming a wall of content that blows past the caller's context budget. When enabled (it is, by default, at 25,000 tokens), each tool's response is estimated with gpt-tokenizer's o200k_base encoding scaled by 1.2× (Claude runs ~15–20% higher than GPT-4o for prose) and compared against a configurable per-tool limit.

Discovery precedence

The governor loads config from the first available source:

BITBUCKET_MCP_CONFIG env var — absolute path. Errors at startup if the file does not exist.
./bitbucket-mcp.config.json — in the current working directory.
$XDG_CONFIG_HOME/bitbucket-mcp/config.json — or ~/.config/bitbucket-mcp/config.json if $XDG_CONFIG_HOME is unset. $BITBUCKET_MCP_CONFIG_DIR overrides the directory portion of this lookup.
Built-in default (25,000 tokens across all tools).

Environment variables

BITBUCKET_MCP_CONFIG — absolute path to the config file.
BITBUCKET_MCP_MAX_OUTPUT_TOKENS — integer > 0. Overrides defaults.maxOutputTokens from the file. Never overrides a per-tool value.
BITBUCKET_MCP_CONFIG_DIR — overrides the XDG config directory used for the fallback config path.

JSON config shape

bitbucket-mcp.config.json:

{
  "$schema": "./bitbucket-mcp.config.schema.json",
  "defaults": { "maxOutputTokens": 25000 },
  "tools": {
    "bitbucket_list_pull_requests": { "maxOutputTokens": 10000 },
    "bitbucket_search_code": { "maxOutputTokens": 10000 }
  }
}

The schema is strict — unknown keys fail startup, so typos in the config are caught immediately. bitbucket-mcp.config.schema.json is committed at repo root and can be regenerated with pnpm run schema:gen after any change to serverConfigSchema.

Per-tool tools.<name>.maxOutputTokens always wins over the default and cannot be overridden by env.

Scaffolding

atlassian-bitbucket-mcp init writes a starter config to the XDG default location. Flags: --config-path <path>, --max-output-tokens <n>, -y (overwrite existing).

atlassian-bitbucket-mcp help prints usage, discovery order, env vars, and JSON shape — offline reference for the same information above.

What the guidance error looks like

When a tool's response exceeds its limit, the caller receives an isError: true result whose text names the tool, the estimated token count, the configured limit, narrowing suggestions (reduce limit, filter by project/repo, call a single-item retrieval tool), and both ways to raise the ceiling (per-tool config entry or the env var). The full response is withheld — nothing is truncated silently.

Available MCP Tools

This server provides the following tools for interacting with Bitbucket:

Pull Request Tools

bitbucket_list_pull_requests - List PRs for a repository
bitbucket_get_pull_request - Get detailed PR information
bitbucket_get_pr_diff - Get PR changes/diff
bitbucket_get_pr_commits - Get commits in a PR
bitbucket_get_pr_activities - Get PR comments and activities
bitbucket_add_pr_comment - Add a general comment (pending: true queues it in your review session instead of posting it)
bitbucket_add_pr_inline_comment - Add a per-file, per-line inline code comment on any author's PR (path + line + lineType; diffType defaults to EFFECTIVE on Server/DC; supports pending)
bitbucket_reply_to_comment - Reply to a comment (supports pending)
bitbucket_resolve_comment - Resolve a comment thread
bitbucket_update_comment - Edit a comment
bitbucket_update_pull_request - Update a PR's title and/or description (Server/DC only, requires current version for optimistic locking)
bitbucket_approve_pr - Approve a pull request
bitbucket_create_pr_task - Create a checklist task (blocker-severity comment) on a PR, optionally as a reply to an existing comment (Server/DC only; supports pending)
bitbucket_list_pr_tasks - List checklist tasks on a PR (Server/DC only)
bitbucket_resolve_pr_task - Set a task to OPEN or RESOLVED (Server/DC only)
bitbucket_delete_pr_task - Delete a task (Server/DC only)

PR Review Session Tools

Server/DC 7.7+ only. See Batched reviews.

bitbucket_start_pr_review - Begin a batched review: reports what is already pending in your session and how to add more
bitbucket_get_pr_review - List the pending, unpublished comments in your session (visible only to you)
bitbucket_publish_pr_review - Publish every pending comment at once, with an optional overview commentText and reviewer participantStatus
bitbucket_discard_pr_review - Delete every pending comment without notifying the author

Repository Tools

bitbucket_list_projects - List accessible projects
bitbucket_list_repositories - List repos in a project
bitbucket_get_repository - Get repository details
bitbucket_get_branches - List repository branches
bitbucket_get_commits - Get commit history
bitbucket_get_file_content - Get file content at ref

Code Search Tools

bitbucket_search_code - Search code across repositories
bitbucket_search_commits - Search commits by message

See docs/TOOLS.md for detailed tool documentation (coming soon).

Batched reviews (Start review / Finish review)

Bitbucket Server/DC 7.7+ lets a reviewer queue feedback privately and release it in one go — Start review, then Publish or Discard review in the web UI. The server models this as comments in PENDING state, scoped to (pull request, authenticated user), so the same session is shared by the web UI and this MCP server and survives restarts of either.

There is no "start review" endpoint: Bitbucket opens the session the moment you create the first pending comment, and closes it on publish or discard.

bitbucket_start_pr_review        # optional: shows what is already pending
  ↓
bitbucket_add_pr_inline_comment  { ..., pending: true }   # repeat as needed
bitbucket_create_pr_task         { ..., pending: true }
  ↓
bitbucket_get_pr_review          # read back everything queued, edit if needed
  ↓
bitbucket_publish_pr_review      { commentText?, participantStatus? }
   or bitbucket_discard_pr_review

Notes:

pending defaults to false, so every existing call site keeps posting immediately. Nothing changes unless you opt in.
Pending comments are invisible to the PR author and to other reviewers until published; bitbucket_get_pr_activities will not show them.
Queued comments can be edited (bitbucket_update_comment) or deleted while still pending — a pending comment carries an ordinary comment id/version.
bitbucket_publish_pr_review returns { "publishedCommentCount": N }. participantStatus is one of UNAPPROVED, NEEDS_WORK, APPROVED; omit it to publish without changing your verdict. Supplying it requires the manage_pr action, since it changes approval state.
bitbucket_discard_pr_review deletes all pending comments for the PR — it is not undoable, and the author is never notified.
On Bitbucket Cloud, and on Server/DC older than 7.7, the /review endpoints do not exist and these four tools return a 404-derived error.

Programmatic usage (CI)

Besides running as an MCP server, the package exposes the Bitbucket API layer directly as a library via the atlassian-bitbucket-mcp/helper subpath export — useful for CI jobs that need to comment on a PR without an MCP client in the loop. There is no permission or scope gating on this path: the script holds the token, so it can do whatever the token can.

import { createBitbucketHelper } from 'atlassian-bitbucket-mcp/helper';

// Explicit options override env; anything omitted falls back to
// BITBUCKET_URL / BITBUCKET_TOKEN / BITBUCKET_DEFAULT_PROJECT.
const helper = createBitbucketHelper({
  url: 'https://bitbucket.juspay.net',
  token: process.env.BITBUCKET_TOKEN,
  defaultProject: 'BZ',
});

const pr = await helper.pullRequests.get('BZ', 'nimble', 42);
await helper.pullRequests.addComment('BZ', 'nimble', 42, `CI passed for "${pr.title}"`);

Notes:

helper.pullRequests, helper.repositories and helper.search group the API by resource — the same operations as the MCP tools (list/get PRs, diffs, commits, comments, tasks, review sessions, approve, branches, file content, code/commit search). Every method is pre-bound, so destructuring is safe (const { addComment } = helper.pullRequests).
helper.client is the escape hatch for raw REST calls (client.requestJson(endpoint, { method, body, queryParams })); helper.config is the resolved effective config — it contains the token, so never log or serialize it.
Error classes (BitbucketApiError, NetworkError, TimeoutError) and the relevant Bitbucket types are re-exported from the same subpath for instanceof checks and typing.
Optional tuning: requestTimeout, maxRetries, rateLimitDelay options (or BITBUCKET_REQUEST_TIMEOUT / BITBUCKET_MAX_RETRIES / BITBUCKET_RATE_LIMIT_DELAY). Caching is always disabled in helper mode.
The package is ESM-only ("type": "module") — use import, not require.

Development

VSCode Setup (Recommended)

This project includes VSCode workspace settings and extension recommendations. When you open the project in VSCode, you'll be prompted to install:

ESLint - Code linting
Prettier - Code formatting
Markdownlint - Markdown style checking

All formatting and linting happens automatically on save.

Development Commands

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Watch mode for development
pnpm run watch

# Run with local changes
pnpm link --global

# Code quality checks
pnpm run format:all # Format all files
pnpm run lint:all   # Lint all files (markdown + code)
pnpm run typecheck  # Type check with TypeScript
pnpm run validate   # Run all checks (format + lint + typecheck)

Git Hooks

This project uses Husky for Git hooks to maintain code quality and consistency:

Pre-commit Hook

Automatically runs before each commit:

Prettier - Formats all code
ESLint - Lints and auto-fixes issues
TypeScript - Type checks the code
Build - Ensures project compiles

This ensures all committed code meets quality standards.

Commit Message Hook

Enforces Conventional Commits format
Valid formats: <type>(<optional-scope>): <description>
Allowed types: feat, fix, docs, style, refactor, test, chore, ci, build, perf, revert
Examples:
- feat: add user authentication
- fix(auth): resolve login bug
- docs: update README

Pre-push Hook

Validates branch naming convention
Allowed patterns:
- main, master, develop, dev
- feature/<description>, feat/<description>
- bugfix/<description>, fix/<description>
- hotfix/<description>
- release/<version>
- chore/<description>, docs/<description>
Examples:
- feature/user-authentication
- fix/login-bug
- release/v1.0.0

Project Structure

atlassian-bitbucket-mcp/
├── .husky/              # Git hooks
│   ├── commit-msg       # Conventional commits validation
│   ├── pre-commit       # Code quality checks
│   └── pre-push         # Branch name validation
├── docs/                # Documentation
│   ├── ARCHITECTURE.md  # System architecture and design
│   ├── CODING-STANDARDS.md  # Coding standards and best practices
│   ├── BRANCH-MANAGEMENT.md  # Branch naming and management
│   └── SECURITY.md      # Security policy
├── scripts/             # Utility scripts
│   ├── check-package-security.sh
│   ├── pre-commit.sh    # Pre-commit validation script
│   ├── pre-push.sh      # Pre-push validation script
│   ├── commit-msg.sh    # Commit message validation
│   ├── validate-branch-name.sh  # Branch name validator
│   └── setup-vscode.sh  # VSCode workspace setup
├── types/               # Shared TypeScript type definitions
│   ├── index.ts         # Type re-exports
│   ├── bitbucket.ts     # Bitbucket API types
│   ├── mcp.ts           # MCP protocol types
│   ├── config.ts        # Configuration types
│   ├── cache.ts         # Cache types
│   ├── logger.ts        # Logging types
│   └── common.ts        # Common utility types
├── src/                 # MCP server implementation
│   ├── index.ts         # Entry point
│   ├── server.ts        # MCP server setup
│   ├── config.ts        # Configuration
│   ├── cache.ts         # Caching layer
│   ├── logger.ts        # Centralized logging
│   ├── tools/           # MCP tool implementations
│   └── bitbucket/       # Bitbucket API client
├── openapi/             # OpenAPI specifications (future)
│   ├── bitbucket-cloud.yaml
│   └── bitbucket-server.yaml
├── package.json
├── tsconfig.json
└── README.md

Security

This project follows security best practices:

All dependencies are checked against known compromised packages
Minimal dependency footprint
Regular security audits
See docs/SECURITY.md for detailed security policy

Before Installing Packages

# Check if a package is safe
./scripts/check-package-security.sh <package-name>

License

This project is licensed under the GNU General Public License v3.0.

Documentation

For detailed information about this project, see:

Architecture Documentation - System architecture, components, and design decisions
Coding Standards - TypeScript standards, logging, and best practices
Branch Management - Branch naming conventions and workflow
Security Policy - Security guidelines and vulnerability reporting

Contributing

Contributions are welcome! Please ensure:

All new dependencies are verified against compromised package lists
Code follows the Coding Standards
Types use type (not interface) and are placed in types/ directory
Centralized logger is used at all critical paths
OpenAPI YAML files are updated alongside type changes
Tests are included for new features
Git hooks pass (branch naming, format, lint, typecheck, build)