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.

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:

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@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:

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 desc