Bitbucket MCP server

The Atlassian Bitbucket MCP Server allows AI systems like Claude or Cursor AI to securely interact with your Bitbucket repositories, pull requests, workspaces, and code in real time. It implements the Model Context Protocol (MCP) standard, enabling AI assistants to programmatically access and manipulate your Bitbucket data while running locally with your credentials.

Prerequisites

• Node.js (>=18.x): Download
• Bitbucket Cloud Account

Authentication Setup

Step 1: Choose an Authentication Method

Option A: Bitbucket App Password (Recommended)

Generate from Bitbucket App Passwords with these minimum permissions:

• Workspaces: Read
• Repositories: Read
• Pull Requests: Read

You can optionally set BITBUCKET_DEFAULT_WORKSPACE to specify a default workspace.

Option B: Atlassian API Token

Generate from Atlassian API Tokens.

Step 2: Configure Credentials

Option A: MCP Config File (Recommended)

Edit or create ~/.mcp/configs.json:

Using Bitbucket App Password:

{
	"bitbucket": {
		"environments": {
			"ATLASSIAN_BITBUCKET_USERNAME": "<your_username>",
			"ATLASSIAN_BITBUCKET_APP_PASSWORD": "<your_app_password>"
		}
	}
}

Using Atlassian API Token:

{
	"bitbucket": {
		"environments": {
			"ATLASSIAN_SITE_NAME": "bitbucket",
			"ATLASSIAN_USER_EMAIL": "<your_email>",
			"ATLASSIAN_API_TOKEN": "<your_api_token>"
		}
	}
}

Option B: Environment Variables

export ATLASSIAN_BITBUCKET_USERNAME="<your_username>"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="<your_app_password>"

Installation and Running

Quick Start with npx

npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces

Global Installation

npm install -g @aashari/mcp-server-atlassian-bitbucket
mcp-atlassian-bitbucket ls-workspaces

Transport Modes

STDIO Transport (Default for MCP)

• Traditional subprocess communication via stdin/stdout
• Ideal for local AI assistant integrations (Claude Desktop, Cursor AI)

# Run with STDIO transport
TRANSPORT_MODE=stdio npx @aashari/mcp-server-atlassian-bitbucket

# After installation
npm run mcp:stdio

HTTP Transport (Default for Server Mode)

• HTTP-based transport with Server-Sent Events (SSE)
• Supports multiple concurrent connections
• Runs on port 3000 by default (configurable via PORT env var)
• Endpoint: http://localhost:3000/mcp
• Health check: http://localhost:3000/

# Run with HTTP transport
TRANSPORT_MODE=http npx @aashari/mcp-server-atlassian-bitbucket

# After installation
npm run mcp:http

Environment Variables

Transport Configuration:

• TRANSPORT_MODE: Set to stdio or http (default: http for server mode, stdio for MCP clients)
• PORT: HTTP server port (default: 3000)
• DEBUG: Enable debug logging (default: false)

Authentication:

• ATLASSIAN_BITBUCKET_USERNAME: Your Bitbucket username
• ATLASSIAN_BITBUCKET_APP_PASSWORD: Your Bitbucket app password
• ATLASSIAN_API_TOKEN: Alternative API token
• BITBUCKET_DEFAULT_WORKSPACE: Default workspace (optional)

Connecting to AI Assistants

Configure your MCP-compatible client (e.g., Claude, Cursor AI):

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

MCP Tools

The server provides these MCP tools (invoked by AI assistants):

Workspace Management

• bb_ls_workspaces: Lists available workspaces
• bb_get_workspace: Gets workspace details

Repository Operations

• bb_ls_repos: Lists repositories
• bb_get_repo: Gets repository details
• bb_search: Searches Bitbucket content
• bb_clone_repo: Clones a repository

Pull Request Management

• bb_ls_prs: Lists pull requests
• bb_get_pr: Gets PR details with diffs
• bb_ls_pr_comments: Lists PR comments
• bb_add_pr_comment: Adds comment to PR
• bb_add_pr: Creates a PR

Code and Branch Operations

• bb_add_branch: Creates a branch
• bb_get_commit_history: Gets commit history
• bb_get_file: Gets file content
• bb_diff_branches: Shows diff between branches
• bb_diff_commits: Shows diff between commits
• bb_list_branches: Lists branches

CLI Commands

The server also provides a command-line interface using kebab-case commands:

Workspace and Repository Management

# List workspaces
mcp-atlassian-bitbucket ls-workspaces

# Get workspace details
mcp-atlassian-bitbucket get-workspace --workspace-slug acme-corp

# List repositories
mcp-atlassian-bitbucket ls-repos --workspace-slug acme-corp

# Get repository details
mcp-atlassian-bitbucket get-repo --workspace-slug acme-corp --repo-slug backend-api

Pull Request Operations

# List pull requests
mcp-atlassian-bitbucket ls-prs --workspace-slug acme-corp --repo-slug backend-api --state OPEN

# Get pull request details
mcp-atlassian-bitbucket get-pr --workspace-slug acme-corp --repo-slug backend-api --pr-id 42

# View PR comments
mcp-atlassian-bitbucket ls-pr-comments --workspace-slug acme-corp --repo-slug backend-api --pr-id 42

# Add a PR comment
mcp-atlassian-bitbucket add-pr-comment --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 --content "Looks good"

# Create a new PR
mcp-atlassian-bitbucket add-pr --workspace-slug acme-corp --repo-slug backend-api --title "New feature" --source-branch feature/login

Code and Branch Operations

# Get file content
mcp-atlassian-bitbucket get-file --workspace-slug acme-corp --repo-slug backend-api --file-path src/main.js

# Create a new branch
mcp-atlassian-bitbucket add-branch --workspace-slug acme-corp --repo-slug backend-api --new-branch-name feature/new

# Search for code
mcp-atlassian-bitbucket search --workspace-slug acme-corp --query "Logger" --scope code --language typescript

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "bitbucket" '{"command":"npx","args":["-y","@aashari/mcp-server-atlassian-bitbucket"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect