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:

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