bitbucket-mcp

MatanYemini/bitbucket-mcp

3.5
cloud_platforms

If you are the rightful owner of bitbucket-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

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

Bitbucket MCP

A Model Context Protocol (MCP) server for integrating with Bitbucket Cloud and Server APIs. This MCP server enables AI assistants like Cursor to interact with your Bitbucket repositories, pull requests, and other resources.

Safety First

This is a safe and responsible package — no DELETE operations are used, so there's no risk of data loss. Every pull request is analyzed with CodeQL to ensure the code remains secure.

CodeQL GitHub Repository License: MIT npm version

Overview

Checkout out the official npm package This server implements the Model Context Protocol standard to provide AI assistants with access to Bitbucket data and operations. It includes tools for:

  • Listing and retrieving repositories
  • Getting repository details
  • Fetching pull requests
  • And more...

Installation

-- Since it has been asked, in many cases we have seen - "BITBUCKET_USERNAME" is usually your email

Using NPX (Recommended)

The easiest way to use this MCP server is via NPX, which allows you to run it without installing it globally:

# Option A (recommended): API URL + explicit workspace
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 is auto-extracted
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
npx -y bitbucket-mcp@latest

Manual Installation

Alternatively, you can install it globally or as part of your project:

# Install globally
npm install -g bitbucket-mcp

# Or install in your project
npm install bitbucket-mcp

Then run it with:

# If installed globally (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

# If installed globally (Option B - legacy-compatible)
BITBUCKET_URL="https://bitbucket.org/your-workspace" \
BITBUCKET_USERNAME="your-username" \
BITBUCKET_PASSWORD="your-app-password" \
bitbucket-mcp

# If installed 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

# If installed 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

Environment Variables

Configure the server using the following environment variables:

VariableDescriptionRequired
BITBUCKET_URLBitbucket API base URL. Defaults to https://api.bitbucket.org/2.0No
BITBUCKET_USERNAMEYour Bitbucket usernameYes*
BITBUCKET_PASSWORDYour Bitbucket app passwordYes*
BITBUCKET_TOKENYour Bitbucket access token (alternative to username/password)No
BITBUCKET_WORKSPACEDefault workspace to use. If omitted and BITBUCKET_URL contains it, auto-setNo
BITBUCKET_ENABLE_DANGEROUSSet to true to enable dangerous tools (e.g., deletions). Default: disabledNo
BITBUCKET_LOG_DISABLEDisable file logging when set to true/1No
BITBUCKET_LOG_FILEAbsolute path to a specific log fileNo
BITBUCKET_LOG_DIRDirectory to store logs (defaults to OS-specific app log dir)No
BITBUCKET_LOG_PER_CWDWhen true, nest logs under a per-working-directory subfolderNo

Either BITBUCKET_TOKEN or both BITBUCKET_USERNAME and BITBUCKET_PASSWORD must be provided.

Creating a Bitbucket App Password

  1. Log in to your Bitbucket account
  2. Go to Personal Settings > App Passwords
  3. Create a new app password with the following permissions:
    • Repositories: Read
    • Pull requests: Read, Write
    • Pipelines: Read (required for pipeline operations)
  4. Copy the generated password and use it as the BITBUCKET_PASSWORD environment variable

Troubleshooting

401 Authentication Errors

If you're getting 401 authentication errors, check the following:

  1. Verify your app password: Make sure you're using an App Password, not your regular Bitbucket password
  2. Verify app password permissions: Your app password needs at least "Repositories: Read" permission
  3. Try the API URL format: If you're still getting 401 errors, try using the direct API URL format:
BITBUCKET_URL="https://api.bitbucket.org/2.0"
  1. Test API access: Verify your credentials work by testing the Bitbucket API directly:
# Test with curl (replace with your actual values)
curl -u "your-username:your-app-password" \
  "https://api.bitbucket.org/2.0/repositories/your-workspace"
  1. Atlassian API Key: Put the Atlassian API Key in the BITBUCKET_PASSWORD variable, not BITBUCKET_TOKEN.

Getting Help

If you encounter issues:

  1. Check the Bitbucket REST API documentation for API details
  2. Review the Bitbucket Cloud documentation for general help

Integration with Cursor

To integrate this MCP server with Cursor:

  1. Open Cursor
  2. Go to Settings > Extensions
  3. Click on "Model Context Protocol"
  4. Add a new MCP configuration:
"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"]
}
  1. Save the configuration
  2. Use the "/bitbucket" command in Cursor to access Bitbucket repositories and pull requests

Using a Local Build with Cursor

If you're developing locally and want to test your changes:

"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

This MCP server provides tools for interacting with Bitbucket repositories and pull requests. Below is a comprehensive list of the available operations:

Repository Operations

listRepositories

Lists repositories in a workspace.

Parameters:

  • workspace (optional): Bitbucket workspace name
  • limit (optional): Maximum number of repositories to return
getRepository

Gets details for a specific repository.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug

Pull Request Operations

getPullRequests

Gets pull requests for a repository.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • state (optional): Pull request state (OPEN, MERGED, DECLINED, SUPERSEDED)
  • limit (optional): Maximum number of pull requests to return
createPullRequest

Creates a new pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • title: Pull request title
  • description: Pull request description
  • sourceBranch: Source branch name
  • targetBranch: Target branch name
  • reviewers (optional): List of reviewer usernames
  • draft (optional): Whether to create the pull request as a draft
getPullRequest

Gets details for a specific pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
updatePullRequest

Updates a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • Various optional update parameters (title, description, etc.)
getPullRequestActivity

Gets the activity log for a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
approvePullRequest

Approves a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
unapprovePullRequest

Removes an approval from a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
declinePullRequest

Declines a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • message (optional): Reason for declining
mergePullRequest

Merges a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • message (optional): Merge commit message
  • strategy (optional): Merge strategy (merge-commit, squash, fast-forward)
requestChanges

Requests changes on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
removeChangeRequest

Removes a change request from a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
createDraftPullRequest

Creates a new draft pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • title: Pull request title
  • description: Pull request description
  • sourceBranch: Source branch name
  • targetBranch: Target branch name
  • reviewers (optional): List of reviewer usernames

Note: This is equivalent to calling createPullRequest with draft: true.

publishDraftPullRequest

Publishes a draft pull request to make it ready for review.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
convertTodraft

Converts a regular pull request to draft status.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID

Pull Request Comment Operations

getPullRequestComments

Lists comments on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
addPullRequestComment

Creates a comment on a pull request (general or inline).

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • content: Comment content in markdown format
  • inline (optional): Inline comment information for commenting on specific lines

Inline Comment Format:

The inline parameter allows you to create comments on specific lines of code in the pull request diff:

{
  "path": "src/file.ts",
  "to": 15, // Line number in NEW version (for added/modified lines)
  "from": 10 // Line number in OLD version (for deleted/modified lines)
}

Examples:

  • General comment: Omit the inline parameter for a general pull request comment
  • Comment on new line: Use only to parameter
  • Comment on deleted line: Use only from parameter
  • Comment on modified line: Use both from and to parameters

Usage:

// General comment
addPullRequestComment(workspace, repo, pr_id, "Great work!");

// Inline comment on new line 25
addPullRequestComment(workspace, repo, pr_id, "Consider error handling here", {
  path: "src/service.ts",
  to: 25,
});
getPullRequestComment

Gets a specific comment on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • comment_id: Comment ID
updatePullRequestComment

Updates a comment on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • comment_id: Comment ID
  • content: Updated comment content
deletePullRequestComment

Deletes a comment on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • comment_id: Comment ID
resolveComment

Resolves a comment thread on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • comment_id: Comment ID
reopenComment

Reopens a resolved comment thread on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • comment_id: Comment ID

Pull Request Diff Operations

getPullRequestDiff

Gets the diff for a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
getPullRequestDiffStat

Gets the diff statistics for a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
getPullRequestPatch

Gets the patch for a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID

Pull Request Task Operations

getPullRequestTasks

Lists tasks on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
createPullRequestTask

Creates a task on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • content: Task content
  • comment (optional): Comment ID to associate with the task
  • pending (optional): Whether the task is pending
getPullRequestTask

Gets a specific task on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • task_id: Task ID
updatePullRequestTask

Updates a task on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • task_id: Task ID
  • content (optional): Updated task content
  • state (optional): Updated task state
deletePullRequestTask

Deletes a task on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
  • task_id: Task ID

Other Pull Request Operations

getPullRequestCommits

Lists commits on a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID
getPullRequestStatuses

Lists commit statuses for a pull request.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pull_request_id: Pull request ID

Pipeline Operations

listPipelineRuns

Lists pipeline runs for a repository.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • limit (optional): Maximum number of pipelines to return
  • status (optional): Filter pipelines by status (PENDING, IN_PROGRESS, SUCCESSFUL, FAILED, ERROR, STOPPED)
  • target_branch (optional): Filter pipelines by target branch
  • trigger_type (optional): Filter pipelines by trigger type (manual, push, pullrequest, schedule)
getPipelineRun

Gets details for a specific pipeline run.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pipeline_uuid: Pipeline UUID
runPipeline

Triggers a new pipeline run.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • target: Pipeline target configuration (object with ref_type, ref_name, and optional commit_hash, selector_type, selector_pattern)
  • variables (optional): Array of pipeline variables (objects with key, value, and optional secured fields)
stopPipeline

Stops a running pipeline.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pipeline_uuid: Pipeline UUID
getPipelineSteps

Lists steps for a pipeline run.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pipeline_uuid: Pipeline UUID
getPipelineStep

Gets details for a specific pipeline step.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pipeline_uuid: Pipeline UUID
  • step_uuid: Step UUID
getPipelineStepLogs

Gets logs for a specific pipeline step.

Parameters:

  • workspace: Bitbucket workspace name
  • repo_slug: Repository slug
  • pipeline_uuid: Pipeline UUID
  • step_uuid: Step UUID

Development

Prerequisites

  • Node.js 18 or higher
  • npm or yarn

Setup

# Clone the repository
git clone https://github.com/MatanYemini/bitbucket-mcp.git
cd bitbucket-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

License

This project is licensed under the MIT License - see the file for details.

Links

Related MCP Servers

View all cloud_platforms servers →
google-docs-mcp

google-docs-mcp

4.8

by a-bonus

The Ultimate Google Docs MCP Server connects Claude Desktop or other MCP clients to Google Docs, enabling advanced document manipulation through the Model Context Protocol (MCP) and the fastmcp library.

ai_chatbot
edgeone-pages-mcp

edgeone-pages-mcp

4.7

by TencentEdgeOne

An MCP service for deploying HTML content, folder, and zip file to EdgeOne Pages and obtaining a publicly accessible URL.

cloud_platforms
notion-mcp-server

notion-mcp-server

4.3

by makenotion

This project implements an MCP server for the Notion API, allowing integration with LLMs.

databases
mcp-grafana

mcp-grafana

4.3

by grafana

A Model Context Protocol (MCP) server for Grafana providing access to your Grafana instance and its ecosystem.

monitoring
firecrawl-mcp-server

firecrawl-mcp-server

4.2

by firecrawl

Firecrawl MCP Server is a Model Context Protocol server that integrates with Firecrawl for web scraping capabilities.

browser_automation
mcp-replicate

mcp-replicate

4.0

by deepfates

A Model Context Protocol server implementation for Replicate, allowing users to run Replicate models through a simple tool-based interface.

cloud_platforms
mem0-mcp

mem0-mcp

4.0

by mem0ai

This demonstrates a structured approach for using an MCP server with mem0 to manage coding preferences efficiently.

developer_tools
mcp-server

mcp-server

3.9

by keboola

Keboola MCP Server connects AI agents and MCP clients to Keboola, enabling data access and transformations without glue code.

cloud_platforms
NASA-MCP-server

NASA-MCP-server

3.9

by ProgramComputer

A Model Context Protocol (MCP) server for NASA APIs, providing a standardized interface for AI models to interact with NASA's vast array of data sources.

research_and_data
hyper-mcp

hyper-mcp

3.9

by tuananh

hyper-mcp is a fast, secure MCP server that extends its capabilities through WebAssembly plugins.

ai_chatbot
MCP-Doc

MCP-Doc

3.9

by MeterLong

A Docx document processing service based on the FastMCP library, supporting the creation, editing, and management of Word documents using AI assistants in Cursor.

cloud_platforms
mkp

mkp

3.8

by StacklokLabs

MKP is a Model Context Protocol (MCP) server for Kubernetes that allows LLM-powered applications to interact with Kubernetes clusters.

cloud_platforms
Aspire.MCP.Sample

Aspire.MCP.Sample

3.8

by elbruno

Sample MCP Server and MCP client using Aspire.

communication
k8m

k8m

3.7

by weibaohui

K8M is an AI-driven lightweight Kubernetes dashboard designed to simplify cluster management.

ai_chatbot
mcp-jetbrains

mcp-jetbrains

3.7

by JetBrains

The JetBrains MCP Proxy Server facilitates communication between client applications and JetBrains IDEs by acting as a proxy server.

developer_tools
qgis_mcp

qgis_mcp

3.7

by jjsantos01

QGISMCP connects QGIS to Claude AI through the Model Context Protocol, enabling direct interaction and control over QGIS.

cloud_platforms
kubernetes-mcp-server

kubernetes-mcp-server

3.7

by containers

The Kubernetes MCP Server is a powerful and flexible implementation of the Model Context Protocol (MCP) server, designed to interact directly with Kubernetes and OpenShift environments.

cloud_platforms
chroma-mcp

chroma-mcp

3.7

by chroma-core

Chroma MCP Server is an open-source embedding database server that facilitates the integration of LLM applications with external data sources using the Model Context Protocol.

databases
ros-mcp-server

ros-mcp-server

3.7

by robotmcp

The ROS MCP Server bridges large language models (LLMs) with robot control, allowing users to issue natural language commands that are translated into ROS/ROS2 instructions.

cloud_platforms
cloud-run-mcp

cloud-run-mcp

3.7

by GoogleCloudPlatform

This is the repository of an MCP server to deploy code to Cloud Run, enabling MCP-compatible AI agents to deploy apps to Cloud Run.

cloud_platforms
mcp-gsuite

mcp-gsuite

3.7

by MarkusPfundstein

MCP server to interact with Google products, specifically Gmail and Calendar.

communication
mcp-server-azure-devops

mcp-server-azure-devops

3.6

by Tiberriver256

A Model Context Protocol (MCP) server implementation for Azure DevOps, allowing AI assistants to interact with Azure DevOps APIs through a standardized protocol.

cloud_platforms
mcp-sse

mcp-sse

3.6

by sidharthrajaram

This document describes an SSE-based MCP server and client setup for weather data retrieval using the Model Context Protocol.

cloud_platforms
openalex-mcp

openalex-mcp

3.6

by hbiaou

OpenAlex MCP Server is a Node.js server using Express and Axios to proxy queries to the OpenAlex API.

developer_tools
code-sandbox-mcp

code-sandbox-mcp

3.6

by Automata-Labs-team

A secure sandbox environment for executing code within Docker containers. This MCP server provides AI applications with a safe and isolated environment for running code while maintaining security through containerization.

security
emcee

emcee

3.6

by mattt

emcee is a tool that provides a Model Context Protocol (MCP) server for any web application with an OpenAPI specification.

developer_tools
codehooks-mcp-server

codehooks-mcp-server

3.6

by RestDB

This MCP server provides tools for interacting with codehooks.io projects through AI agents like Claude.

developer_tools