home / mcp / bitbucket mcp server

Bitbucket MCP Server

Provides programmatic access to Bitbucket workspaces, repositories, branches, PRs, and commits for LLM workflows.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "jlromano-bitbucket-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/bitbucket-mcp/dist/index.js"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

You can run a Bitbucket MCP Server to empower your large language model workflows with direct access to Bitbucket workspaces, repositories, branches, pull requests, and commits. This MCP server lets you programmatically explore and manage Bitbucket resources, making it easy to build intelligent assistants that analyze code, review changes, and automate repository tasks.

How to use

Use an MCP client to query and control Bitbucket resources through the server. You can list workspaces and repositories, fetch repository details, search code across repositories, view and compare branches, manage pull requests (list, create, approve, merge, and comment), and inspect commits and file contents. Typical workflows include asking your model to summarize repository structure, locate references across code, create and merge a pull request, or fetch a file’s content from a specific branch.

To interact, connect your MCP client to one or more MCP servers configured for Bitbucket. The server exposes a set of endpoints you can invoke from your LLM tooling to perform the actions described above.

How to install

Prerequisites: ensure you have Node.js 18 or higher and a Bitbucket account with an App Password.

Step 1 — Install the MCP server and dependencies:

npm install

Step 2 — Prepare environment variables. Create a file named .env with your Bitbucket credentials and workspace:

BITBUCKET_USERNAME=your-username-or-email
BITBUCKET_APP_PASSWORD=your-app-password
BITBUCKET_WORKSPACE=default-workspace (optional)

Step 3 — Build the project:

npm run build

Step 4 — Run the MCP server locally in stdio mode using the provided command from the example configuration: either run via Node pointing to the built script or use the bundled CLI if you installed the package globally.

Configuration and start options

You can configure the MCP server in your Claude Desktop or other MCP-compatible clients by providing the following stdio configuration blocks.

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp/dist/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

Using the CLI to start the server

If you installed the MCP server globally, you can start it with the following command.

bitbucket-mcp

Available tools

list_workspaces

List all available workspaces you have access to.

list_repositories

List repositories within a workspace.

get_repository

Get detailed information about a repository.

list_branches

List branches in a repository.

get_branch

Get details of a specific branch.

compare_branches

Compare two branches to see differences.

list_pull_requests

List pull requests with optional filters.

get_pull_request

Get details of a pull request.

create_pull_request

Create a new pull request.

approve_pull_request

Approve a pull request.

merge_pull_request

Merge a pull request.

add_pull_request_comment

Add a comment to a pull request.

list_commits

List commits in a repository.

get_commit

Get details of a commit.

get_file_content

Get file contents from a repository.

search_code

Search code across the workspace.