home / mcp / bitbucket mcp server

Bitbucket MCP Server

Provides an MCP server that lets AI assistants interact with Bitbucket Cloud repositories, PRs, comments, tasks, and branches via a standardized API.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "bobmaertz-bitbucket-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/bitbucket_mcp/packages/bitbucket-mcp-server/dist/index.js"
      ],
      "env": {
        "LOG_LEVEL": "info",
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_APP_PASSWORD": "your-app-password",
        "BITBUCKET_DEFAULT_REPO": "my-repo"
      }
    }
  }
}

You run a dedicated MCP (Model Context Protocol) server that exposes Bitbucket Cloud data to AI assistants. It lets your AI workflows list and inspect pull requests, manage comments and tasks, and browse branches through a standardized interface, enabling seamless conversational access to Bitbucket Cloud resources.

How to use

Configure your MCP client to connect to the Bitbucket MCP Server, then ask your AI assistant to perform repository operations. You can list pull requests, inspect diffs, read or add comments, manage tasks, and explore branches using natural language prompts. The server handles authenticating with Bitbucket Cloud via the app password you provide and translates your requests into Bitbucket REST API calls.

How to install

Prerequisites: install Node.js 18 or higher, and a package manager such as npm or pnpm. You also need a Bitbucket Cloud account and an app password to access the REST API.

Step 1. Clone the MCP server repository and set up the workspace.

git clone <repository-url>
cd bitbucket_mcp

Step 2. Install dependencies for the monorepo.

npm install

Step 3. Build the packages to produce the runnable server artifacts.

npm run build

Step 4. Run the MCP server in development or production mode.

# Development
cd packages/bitbucket-mcp-server
npm run dev

# Production
node packages/bitbucket-mcp-server/dist/index.js

Step 5. Provide required environment variables. Create a .env file (or export variables in your environment) with the values shown below.

BITBUCKET_WORKSPACE=your-workspace
BITBUCKET_USERNAME=your-username
BITBUCKET_APP_PASSWORD=your-app-password

# Optional
BITBUCKET_DEFAULT_REPO=your-default-repo
LOG_LEVEL=info

Additional guidance on running the MCP server with the client

If you are wiring this up to an MCP client such as Claude Desktop, provide the absolute path to the compiled server entry script and the required environment variables. The client will invoke the server in a local process and pass requests through the MCP protocol.

Configuration

Environment variables are required for authentication and operation. Create a .env file or set these in your environment before starting the server.

# Required
BITBUCKET_WORKSPACE=your-workspace
BITBUCKET_USERNAME=your-username
BITBUCKET_APP_PASSWORD=your-app-password

# Optional
BITBUCKET_DEFAULT_REPO=your-default-repo
LOG_LEVEL=info

Bitbucket App Password setup

Follow these steps to create an app password for Bitbucket Cloud access:

1. Go to Bitbucket Settings > Personal Bitbucket settings > App passwords
2. Click "Create app password"
3. Give it a label (e.g., "MCP Server")
4. Select the required permissions:
   - Repositories: Read, Write
   - Pull requests: Read, Write
   - Issues: Read (if using tasks)
5. Copy the generated password

Claude Desktop configuration example

Configure Claude Desktop to connect to the MCP server by adding the following configuration snippet.

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

Available tools

bitbucket_list_pull_requests

List pull requests for a repository. Requires workspace and repo_slug; optionally filter by state (OPEN, MERGED, DECLINED).

bitbucket_get_pull_request

Get details of a specific pull request by PR ID within a workspace and repository.

bitbucket_get_pr_commits

Retrieve commits associated with a pull request.

bitbucket_get_pr_diff

Get the diff for a specific pull request.

bitbucket_list_pr_comments

List all comments on a pull request.

bitbucket_create_comment

Create a new comment on a pull request.

bitbucket_list_pr_tasks

List all tasks on a pull request.

bitbucket_update_task

Update a task's state (RESOLVED or UNRESOLVED).

bitbucket_list_branches

List repository branches.

bitbucket_get_branch

Get details of a specific branch.