home / mcp / bitbucket mcp server

Bitbucket MCP Server

Bitbucket MCP - A Model Context Protocol (MCP) server for integrating with Bitbucket Cloud and Server APIs

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "matanyemini-bitbucket-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "bitbucket-mcp@latest"
      ],
      "env": {
        "BITBUCKET_URL": "https://api.bitbucket.org/2.0",
        "BITBUCKET_TOKEN": "your-access-token",
        "BITBUCKET_PASSWORD": "your-app-password",
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

This MCP server enables AI assistants to interact with Bitbucket data and operations, including repositories, pull requests, and pipelines, without risking data loss. It provides safe, read-only access for most actions and integrates smoothly with clients like Cursor to enhance your Bitbucket workflows.

How to use

Connect your MCP client to the Bitbucket MCP server by configuring the MCP configuration for the client. You will typically specify the MCP command, environment variables for authentication and target workspace, and then run the MCP tool through your client. In practice, you can use a local or remote MCP setup to list repositories, fetch pull requests, view pipeline runs, and more.

How to install

Prerequisites: you need Node.js 18 or higher and a package manager such as npm or yarn.

# Prerequisites
node -v
npm -v

# Option A: Using NPX (recommended)
BITBUCKET_URL="https://api.bitbucket.org/2.0" \
BITBUCKET_WORKSPACE="your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx -y bitbucket-mcp@latest

# Option B: Legacy-compatible (web URL only, workspace auto-extracted)
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx -y bitbucket-mcp@latest

# Installing globally
npm install -g bitbucket-mcp

# Running after global install (Option A)
BITBUCKET_URL="https://api.bitbucket.org/2.0" \
BITBUCKET_WORKSPACE="your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
bitbucket-mcp

# Running after global install (Option B - legacy-compatible)
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
bitbucket-mcp

# Running in your project (Option A)
BITBUCKET_URL="https://api.bitbucket.org/2.0" \
BITBUCKET_WORKSPACE="your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx bitbucket-mcp

# Running in your project (Option B - legacy-compatible)
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx bitbucket-mcp

Configuration and security basics

Configure the server with environment variables to authenticate and select the Bitbucket workspace. Use a Bitbucket app password with read permissions for repositories and pull requests. Optional tokens can be used as an alternative to username/password.

Important environment variables you will configure include BITBUCKET_URL, BITBUCKET_USERNAME, BITBUCKET_PASSWORD, and BITBUCKET_WORKSPACE. If you prefer token-based authentication, you can use BITBUCKET_TOKEN in place of the username/password pair.

Cursor integration example

If you use Cursor to access Bitbucket data through MCP, add a new MCP configuration in Cursor with the following structure. This enables you to run Bitbucket actions from Cursor using a simple command.

"bitbucket": {
  "command": "npx",
  "env": {
    "BITBUCKET_URL": "https://api.bitbucket.org/2.0",
    "BITBUCKET_WORKSPACE": "your-workspace",
    "BITBUCKET_USERNAME": "your-username",
    "BITBUCKET_PASSWORD": "your-app-password"
  },
  "args": ["-y", "bitbucket-mcp@latest"]
}

Local development build for Cursor testing

For development, you can run a local build and point Cursor at your built distribution. Use the following configuration when testing locally.

"bitbucket-local": {
  "command": "node",
  "env": {
    "BITBUCKET_URL": "https://api.bitbucket.org/2.0",
    "BITBUCKET_WORKSPACE": "your-workspace",
    "BITBUCKET_USERNAME": "your-username",
    "BITBUCKET_PASSWORD": "your-app-password"
  },
  "args": ["/path/to/your/local/bitbucket-mcp/dist/index.js"]
}

Available tools

listRepositories

Lists repositories in a workspace with optional filters and pagination controls.

getRepository

Retrieves details for a specific repository within a workspace.

getPullRequests

Fetches pull requests for a repository with optional state and pagination.

createPullRequest

Creates a new pull request with title, description, source, target, and optional reviewers.

getPullRequest

Gets details for a specific pull request.

mergePullRequest

Merges a specified pull request with optional message and strategy.

addPullRequestComment

Adds a general or inline comment to a pull request.

getPullRequestDiff

Retrieves the diff for a pull request.

listPipelineRuns

Lists pipeline runs for a repository with optional filters.

runPipeline

Triggers a new pipeline run with optional variables.