Bitbucket MCP Server

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="[email protected]" \
BITBUCKET_API_TOKEN="your-api-token" \
npx -y bitbucket-mcp-server@latest

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="[email protected]"

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", "bitbucket-mcp-server@latest"],
      "env": {
        "BITBUCKET_USERNAME": "[email protected]",
        "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": "[email protected]",
        "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