Bitbucket

Connect Bitbucket to AI assistants so you can ask questions about your code, inspect pull requests, search and review code, and automate workflows directly from your Bitbucket repositories using the MCP (Model Context Protocol). This enables instant AI-powered insights and streamlined collaboration across your development process.

How to use

You can use the MCP server to connect your Bitbucket cloud repositories to AI assistants such as Claude Desktop, Cursor AI, and other MCP-enabled clients. Once configured, you can ask questions like which was the latest commit in a repository, see open pull requests needing review, search for code containing specific functions, compare changes between branches, create or comment on pull requests, and automate routine actions.

How to install

Prerequisites: you need Node.js 18.0.0 or higher and a Bitbucket Cloud account. You should also choose a credential method (scoped API tokens are recommended for future-proofing). Then install and run the MCP server as described below.

Step 1. Prepare credentials (choose one method):

# Method 1: Scoped API Token (recommended - future-proof)
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_scoped_api_token"  # Token starting with ATATT

# OR Method 2: Legacy App Password (will be deprecated)
export ATLASSIAN_BITBUCKET_USERNAME="your_username"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="your_app_password"

Step 2. Try it instantly

# List your workspaces
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces" 

# List repositories in a workspace
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace" 

# Get pull requests for a repository
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace/your-repo/pullrequests" 

# Get repository details with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace/your-repo" --jq "{name: name, language: language}"

Step 3. Connect to an AI assistant

Configure your MCP client to run the MCP server. You can use a local, command-based setup or an explicit configuration file.

Claude Desktop setup

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_scoped_api_token"
      }
    }
  }
}

Claude Desktop legacy setup

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
      "env": {
        "ATLASSIAN_BITBUCKET_USERNAME": "your_username",
        "ATLASSIAN_BITBUCKET_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

For other AI assistants

Most MCP-enabled assistants can run the MCP server. You can either use the latest version via npx or install the package globally, then configure your assistant to connect to the MCP server using STDIO transport.

Alternative: system-wide configuration file

# Example with scoped API token
{
  "bitbucket": {
    "environments": {
      "ATLASSIAN_USER_EMAIL": "your.email@company.com",
      "ATLASSIAN_API_TOKEN": "your_scoped_api_token",
      "BITBUCKET_DEFAULT_WORKSPACE": "your_main_workspace"
    }
  }
}

# Example with legacy app password
{
  "bitbucket": {
    "environments": {
      "ATLASSIAN_BITBUCKET_USERNAME": "your_username",
      "ATLASSIAN_BITBUCKET_APP_PASSWORD": "your_app_password",
      "BITBUCKET_DEFAULT_WORKSPACE": "your_main_workspace"
    }
  }
}

Notes on credentials and environments

The system supports both scoped API tokens and Bitbucket app passwords. Use scoped API tokens for future-proofing and active maintenance. App passwords are legacy and will be deprecated by June 2026.

Troubleshooting and tips

1. Ensure the correct authentication method is used and the token is active with the required scopes. 2) Test credentials with the CLI before connecting to an AI assistant. 3) Enable DEBUG mode to see detailed request/response data. 4) Verify API paths are correct and case-sensitive.

Security and data handling

All interactions stay on your local machine. The MCP server uses your Bitbucket credentials and only accesses resources you allow, with no data sent to third parties.

Migration note

This MCP server supports modern, explicit path-based tools and TOON output by default, enabling efficient token usage and flexible access to Bitbucket API endpoints.

Getting help

If you encounter issues, start with the troubleshooting tips above, check examples of typical setups, and share your environment details when seeking help from the community.

Available tools

bb_get

GET to any Bitbucket API endpoint to read data; supports path, queryParams, jq, and outputFormat

bb_post

POST to a Bitbucket endpoint to create resources; supports path, body, queryParams, jq, and outputFormat

bb_put

PUT to a Bitbucket endpoint to replace resources; supports path, body, queryParams, jq, and outputFormat

bb_patch

PATCH to a Bitbucket endpoint for partial updates; supports path, body, queryParams, jq, and outputFormat

bb_delete

DELETE a Bitbucket resource; supports path, queryParams, jq, and outputFormat

bb_clone

Clone a repository locally with workspace and repository slugs