Bitbucket MCP server for AI agents

The Atlassian Bitbucket MCP Server enables AI systems to securely interact with your Bitbucket repositories, pull requests, workspaces, and code in real-time through the Model Context Protocol (MCP) standard. It provides a secure local interface for AI assistants to programmatically access your Bitbucket data.

Installation and Setup

Prerequisites

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

Authentication

Choose one of the following authentication methods:

Option A: Bitbucket App Password (Recommended)

Generate an app password from Bitbucket App Passwords. Minimum permissions needed:

Workspaces: Read
Repositories: Read
Pull Requests: Read

You can set BITBUCKET_DEFAULT_WORKSPACE to specify a default workspace.

Option B: Atlassian API Token

Generate a token from Atlassian API Tokens.

Configure Credentials

Using MCP Config File (Recommended)

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

With Bitbucket App Password:

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

With Atlassian API Token:

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

Using Environment Variables

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

Install and Run

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

Connect to AI Assistant

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

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

Using the MCP Tools

MCP tools use snake_case names, camelCase parameters, and return Markdown-formatted responses.

Available Tools

bb_ls_workspaces: Lists available workspaces
bb_get_workspace: Gets workspace details
bb_ls_repos: Lists repositories
bb_get_repo: Gets repository details
bb_search: Searches Bitbucket content
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
bb_add_branch: Creates a branch
bb_clone_repo: Clones a repository
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

Example Tool Usage

Listing Workspaces

{}

or with search:

{ "query": "devteam" }

Getting Repository Details

{ "workspaceSlug": "acme-corp", "repoSlug": "backend-api" }

Searching Code

{
	"workspaceSlug": "acme-corp",
	"query": "Logger",
	"scope": "code",
	"language": "typescript"
}

Creating a Pull Request

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"title": "Add login screen",
	"sourceBranch": "feature/login"
}

Getting File Content

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api",
	"filePath": "src/main/java/com/acme/service/Application.java",
	"revision": "main"
}

Command Line Interface

CLI commands use kebab-case. Run --help for details on any command.

Basic Commands

# List all workspaces
mcp-atlassian-bitbucket ls-workspaces

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

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

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

Working with Pull Requests

# List open pull requests
mcp-atlassian-bitbucket ls-prs --workspace-slug acme-corp --repo-slug frontend-app --state OPEN

# Get details of a pull request
mcp-atlassian-bitbucket get-pr --workspace-slug acme-corp --repo-slug frontend-app --pr-id 42

# Add a comment to a pull request
mcp-atlassian-bitbucket add-pr-comment --workspace-slug acme-corp --repo-slug frontend-app --pr-id 42 --content "Looks good to merge."

# Create a new pull request
mcp-atlassian-bitbucket add-pr --workspace-slug acme-corp --repo-slug frontend-app --title "Add login screen" --source-branch feature/login

Code and Branch Management

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

# Create a new branch
mcp-atlassian-bitbucket add-branch --workspace-slug acme-corp --repo-slug frontend-app --new-branch-name feature/new-feature --source-branch-or-commit main

# Compare branches
mcp-atlassian-bitbucket diff-branches --workspace-slug acme-corp --repo-slug web-app --source-branch develop --target-branch main

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.

Bitbucket MCP server