Bitbucket MCP Server

<img src="./images/logo.jpg" alt="Bitbucket MCP Logo" width="640" height="320">

A Model Context Protocol (MCP) server that provides tools for interacting with Bitbucket repositories, pull requests, issues, and more.

Safety

This server is read-heavy and non-destructive — no DELETE operations are used against the Bitbucket API, so there is no risk of accidental data loss. Write operations are limited to creating and updating resources (e.g., pull requests, comments, pipelines).

Quick Start

Using NPX (Recommended)

Run directly without cloning the repository:

BITBUCKET_USERNAME="your-email@example.com" \
BITBUCKET_API_TOKEN="your-api-token" \
npx -y -p bitbucket-mcp-server@latest bitbucket-mcp

The -p ... bitbucket-mcp flag tells npx which bin to run. The package ships two binaries — bitbucket-mcp (the MCP server) and bb (the CLI) — so the bin name must be specified explicitly.

From Source

1. Install and Build:

   npm install
   npm run build
   

2. Configure Environment: Set the required variables (see Configuration):

   export BITBUCKET_API_TOKEN="your-api-token"
   export BITBUCKET_USERNAME="your-email@example.com"
   

3. Run the Server:

   npm start
   

CLI

This package also ships a bb CLI alongside the MCP server. After installing globally:

npm install -g bitbucket-mcp-server
bb --help

The CLI shares the same core logic as the MCP server, providing terminal access to repositories, pull requests, issues, pipelines, and more. See docs/cli.md for the full reference, including authentication, output formats, exit codes, and command-by-command examples.

Quick example—list open PRs in JSON:

BITBUCKET_WORKSPACE=acme bb --json pr list -r api --state OPEN

Features

This MCP server provides comprehensive tools for Bitbucket integration:

• Repository Management: List and inspect repositories in a workspace.
• Pull Requests: Full lifecycle support—list, get details, create, update, diff, and comment.
• Issues: Query and filter repository issues.
• Source Code: Explore branches and commits.
• Pipelines: List, get, and trigger Bitbucket pipelines for CI/CD.
• System & Search: Cross-resource search and health monitoring.

For a full list of available tools and their parameters, see the Tool Reference.

Available Tools

Repository & code

• repositories — List repositories in a workspace, or fetch details for a single repository when repo_slug is provided.
• commits — List recent commits, or fetch a single commit when commit_hash is provided.
• list-branches — List branches for a repository.
• search — Full-text search across a repository.

Pull requests

• pull-requests — List PRs, or fetch a single PR when pr_id is provided.
• create-pull-request — Create a new pull request.
• update-pr-description — Update an existing PR's description.
• get-pr-diff — Fetch the diff for a PR.

PR comments

• pr-comments — List PR comments, or fetch a single comment when comment_id is provided.
• create-pr-comment — Add a comment (or inline comment, or reply) to a PR.

Issues

• list-issues — List issues for a repository.

Pipelines

• pipelines — List pipelines, or fetch a single pipeline when pipeline_uuid is provided.
• trigger-pipeline — Trigger a new pipeline run.
• pipeline-steps — Pipeline step operations. Use action: "list" | "get" | "log" to select behavior; step_uuid is required for get and log.

System

• health-check — Server health status.
• get-metrics — Request metrics.

Migrating from v1.x to v2.0

v2.0 consolidates 24 tools into 16. Update tool names and parameters as follows:

Old (v1.x)	New (v2.0)	Parameter changes
list-repositories	repositories	Same parameters; repo_slug optional
get-repository	repositories	Pass repo_slug
list-pull-requests	pull-requests	Same parameters; pr_id optional
get-pull-request	pull-requests	Pass pr_id (previously pull_request_id — rename)
list-pr-comments	pr-comments	pull_request_id → pr_id (matches pull-requests); comment_id optional
get-pr-comment	pr-comments	pull_request_id → pr_id; pass comment_id
get-commits	commits	Same parameters; commit_hash optional
get-commit	commits	Pass commit_hash
list-pipelines	pipelines	Same parameters; pipeline_uuid optional
get-pipeline	pipelines	Pass pipeline_uuid
list-pipeline-steps	pipeline-steps	Add action: "list"
get-pipeline-step	pipeline-steps	Add action: "get"
get-pipeline-step-log	pipeline-steps	Add action: "log"

All other tools retain their v1.x names and parameters.

Installation

1. Clone or download this repository.
2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

The server is configured via environment variables. For detailed setup instructions and client-specific examples (Claude Desktop, etc.), please refer to the Configuration Guide.

Essential Variables

Variable	Description
BITBUCKET_API_TOKEN	(Required) Your User API token or Workspace/Project token
BITBUCKET_USERNAME	(Required for User API tokens) Your Atlassian account email
BITBUCKET_WORKSPACE	Default workspace used when the parameter is omitted

Note: If you are using a Workspace or Project access token, you can omit BITBUCKET_USERNAME.

Advanced Settings

Additional configuration options for timeouts, caching, metrics, and retries are documented in CONFIGURATION.md.

MCP Client Configuration

Add this server to your MCP client configuration (e.g., claude_desktop_config.json). See CONFIGURATION.md for full examples for macOS, Linux, and Windows.

Using NPX (recommended):

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "npx",
      "args": ["-y", "-p", "bitbucket-mcp-server@latest", "bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-email@example.com",
        "BITBUCKET_API_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

Using local build:

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/bitbucket_mcp/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your-email@example.com",
        "BITBUCKET_API_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

Usage Examples

List Repositories

List all repositories in the 'myworkspace' workspace

Create Pull Request

Create a pull request from feature/my-feature to main in myworkspace/myrepo with title "My Feature PR"

Search Workspace

Search for "authentication" across all repositories and pull requests

See more examples for PRs, issues, and commits in the Tool Reference.

Prerequisites

• Node.js 20.19.x or >= 22.12.0
• npm (included with Node.js)

Development

• Build: npm run build
• Dev Mode: npm run dev
• Test: npm test
• Coverage: npm run test:coverage

Troubleshooting

Refer to the Troubleshooting section in CONFIGURATION.md for common issues related to authentication, permissions, and rate limiting.

License

ISC

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Links

• npm Package
• GitHub Repository
• Model Context Protocol
• Bitbucket REST API Documentation
• Bitbucket Cloud Documentation