Bitbucket MCP Plus

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.

This is a fork of bitbucket-mcp with extra tooling:

• Local image upload tools for PR comments (file path, clipboard, raw base64)
• Reviewer management on pull requests (updatePullRequestReviewers)
• Batch comment removal (deleteMyPullRequestComments, deletePullRequestComments)

Safety First

Destructive operations (e.g. delete tools) are gated behind BITBUCKET_ENABLE_DANGEROUS=true and are off by default, so there's no risk of accidental data loss. Every pull request is analyzed with CodeQL to ensure the code remains secure.

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-plus@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-plus@latest

Manual Installation

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

# Install globally
npm install -g bitbucket-mcp-plus

# Or install in your project
npm install bitbucket-mcp-plus

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" \
local-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" \
local-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 local-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 local-bitbucket-mcp

Configuration

Environment Variables

Configure the server using the following environment variables:

| Variable | Description | Required | | ---------------------------- | ------------------------------------------------------------------------------ | -------- | | BITBUCKET_URL | Bitbucket API base URL. Defaults to https://api.bitbucket.org/2.0 | No | | BITBUCKET_USERNAME | Your Bitbucket username | Yes* | | BITBUCKET_PASSWORD | Your Bitbucket app password | Yes* | | BITBUCKET_TOKEN | Your Bitbucket access token (alternative to username/password) | No | | BITBUCKET_WORKSPACE | Default workspace to use. If omitted and BITBUCKET_URL contains it, auto-set | No | | BITBUCKET_ENABLE_DANGEROUS | Set to true to enable dangerous tools (e.g., deletions). Default: disabled | No | | BITBUCKET_ENABLE_LOCAL_UPLOADS | Set to true to enable tools that read local image files or clipboard images | No | | BITBUCKET_LOG_DISABLE | Disable file logging when set to true/1 | No | | BITBUCKET_LOG_FILE | Absolute path to a specific log file | No | | BITBUCKET_LOG_DIR | Directory to store logs (defaults to OS-specific app log dir) | No | | BITBUCKET_LOG_PER_CWD | When true, nest logs under a per-working-directory subfolder | No |

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"

Atlassian API Key

1. Put the Atlassian API Key in the BITBUCKET_PASSWORD variable, not BITBUCKET_TOKEN
2. Use your Bitbucket email as BITBUCKET_USERNAME instead of your regular username

For reference you can check the API token documentation

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-plus@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",
    "BITBUCKET_ENABLE_LOCAL_UPLOADS": "true"
  },
  "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:

Pagination

Unless noted otherwise, listing tools accept the following optional parameters:

• pagelen: Number of items per page (Bitbucket pagelen). Defaults to 10 and is capped at 100.
• page: 1-based Bitbucket page number to fetch. When omitted, the first page is returned.
• all: When true (and page is not provided), the server automatically follows Bitbucket next links until all items are fetched or a safety cap of 1,000 entries is reached.
• limit: Deprecated alias for pagelen kept for backward compatibility.

Use these knobs to page through large collections without hitting CLI truncation.

Repository Operations

listRepositories

Lists repositories in a workspace.

Parameters:

• workspace (optional): Bitbucket workspace name
• name (optional): Filter repositories by partial name match
• Pagination controls described in Pagination

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)
• Pagination controls described in Pagination

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
• Pagination controls described in Pagination
• Pagination controls described in Pagination
• Pagination controls described in Pagination
• Pagination controls described in Pagination

updatePullRequest

Updates a pull request.

Parameters:

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

updatePullRequestReviewers

Replaces the list of reviewers on a pull request. Bitbucket's PUT replaces the entire reviewer set, so pass the full final list of reviewer UUIDs. Pass an empty array to clear all reviewers.

Parameters:

• workspace: Bitbucket workspace name
• repo_slug: Repository slug
• pull_request_id: Pull request ID
• reviewers: Array of reviewer UUIDs (e.g. ['{04776764-62c7-453b-b97e-302f60395ceb}']). Use [] to clear.

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,
});

uploadDownloadFile

Uploads a local screenshot/image file to a repository's Bitbucket Downloads.

Requires BITBUCKET_ENABLE_LOCAL_UPLOADS=true and a Bitbucket credential with repository write permission.

Parameters:

• workspace: Bitbucket workspace name
• repo_slug: Repository slug
• file_path: Absolute path to a local image file (.png, .jpg, .jpeg, .webp, or .gif)
• filename (optional): Upload filename. Defaults to a generated unique filename using the original extension.

commentPullRequestWithScreenshot

Uploads a local screenshot/image file to Bitbucket Downloads and creates a pull request comment with markdown image syntax.

Requires BITBUCKET_ENABLE_LOCAL_UPLOADS=true and a Bitbucket credential with repository write permission.

Parameters:

• workspace: Bitbucket workspace name
• repo_slug: Repository slug
• pull_request_id: Pull request ID
• file_path: Absolute path to a local image file (.png, .jpg, .jpeg, .webp, or .gif)
• content (optional): Markdown text to place before the screenshot
• filename (optional): Upload filename. Defaults to a generated unique filename using the original extension.

uploadClipboardScreenshot

Uploads the current macOS clipboard image to a repository's Bitbucket Downloads.

Requires BITBUCKET_ENABLE_LOCAL_UPLOADS=true, a Bitbucket credential with repository write permission, and pngpaste installed:

brew install pngpaste

Parameters:

• workspace: Bitbucket workspace name
• repo_slug: Repository slug
• filename (optional): Upload filename. Defaults to a generated PNG filename.

commentPullRequestWithClipboardScreenshot

Uploads the current macOS clipboard image to Bitbucket Downloads and creates a pull request comment with markdown image syntax.

Requires BITBUCKET_ENABLE_LOCAL_UPLOADS=true, a Bitbucket credential with repository write permission, and pngpaste installed.

Parameters:

• workspace: Bitbucket workspace name
• repo_slug: Repository slug
• pull_request_id: Pull request ID
• content (optional): Markdown text to place before the screenshot
• filename (optional): Upload filename. Defaults to a generated PNG filename.

uploadImageData

Uploads image bytes provided as raw base64 or a data:image/...;base64,... URL to a repository's Bitbucket Downloads. Useful when an AI agent passes a chat-attached image directly to the MCP tool without writing it to disk. Works on any OS and requires no extra apps.

Requires BITBUCKET_ENABLE_LOCAL_UPLOADS=true and a Bitbucket credential with repository write permission.

Parameters:

• workspace: Bitbucket workspace name
• repo_slug: Repository slug
• image_data: Raw base64 image bytes or a data:image/...;base64,... URL (.png, .jpg, .jpeg, .webp, or .gif)
• image_mime_type (optional): MIME type for raw base64 input (e.g. image/png). Ignored when image_data is a data URL.
• filename (optional): Upload filename. Defaults to a generated filename using the detected image extension.

commentPullRequestWithImageData

Uploads image bytes provided as raw base64 or a data:image/...;base64,... URL to Bitbucket Downloads and creates a pull request comment with markdown image syntax. Useful when an AI agent passes a chat-attached image directly to the MCP tool.

Requires BITBUCKET_ENABLE_LOCAL_UPLOADS=true and a Bitbucket credential with repository write permission.

Parameters:

• workspace: Bitbucket workspace name
• repo_slug: Repository slug
• pull_request_id: Pull request ID
• image_data: Raw base64 image bytes or a data:image/...;base64,... URL (.png, .jpg, .jpeg, .webp, or .gif)
• image_mime_type (optional): MIME type for raw base64 input (e.g. image/png). Ignored when image_data is a data URL.
• content (optional): Markdown text to place before the image
• filename (optional): Upload filename. Defaults to a generated filename using the detected image extension.

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

deleteMyPullRequestComments

Deletes every comment on a pull request that was authored by the authenticated user. The caller is identified via GET /user (UUID match), with BITBUCKET_USERNAME as a nickname/display_name fallback. Returns the IDs of deleted comments along with any failures. Considered a dangerous operation — requires BITBUCKET_ENABLE_DANGEROUS=true.

Parameters:

• workspace: Bitbucket workspace name
• repo_slug: Repository slug
• pull_request_id: Pull request ID
• dry_run (optional): If true, return the matched comments without deleting them.

deletePullRequestComments

Bulk-deletes pull request comments by filter. At least one filter is required; multiple filters are combined with AND. Considered a dangerous operation — requires BITBUCKET_ENABLE_DANGEROUS=true.

Parameters:

• workspace: Bitbucket workspace name
• repo_slug: Repository slug
• pull_request_id: Pull request ID
• comment_ids (optional): Specific comment IDs to target.
• author_uuid (optional): Match comments authored by this UUID (e.g. {04776764-62c7-453b-b97e-302f60395ceb}).
• author_nickname (optional): Match comments by nickname, username, or display_name (case-insensitive).
• resolved (optional): true to only delete resolved comments, false to only delete unresolved.
• include_replies (optional): Also delete reply comments whose ancestor matches the filter. Defaults to false.
• dry_run (optional): If true, return the matched comments without deleting them.

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
• Pagination controls described in Pagination
• 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
• Pagination controls described in Pagination

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/yunior8908/local-bitbucket-mcp.git
cd local-bitbucket-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Publishing to the MCP Registry

Use the official Model Context Protocol publishing guide when you are ready to make a new server release. The repository includes everything that guide expects:

1. Build the project so dist/index.js is up to date:

   npm run build

2. Generate the registry manifest (this reads package.json and emits registry/bitbucket-mcp-plus.manifest.json):

   npm run registry:manifest

3. Follow the publish-server guide to push the manifest with smithery publish or the recommended workflow from the guide.

The generated manifest captures the CLI command (node dist/index.js), all documented configuration options, and pointers back to this README for setup instructions, so it can be submitted directly to the MCP registry.

License

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

Links

• GitHub Repository
• npm Package
• Upstream bitbucket-mcp package (MatanYemini)
• Model Context Protocol
• Bitbucket REST API Documentation
• Bitbucket Cloud Documentation