Bitbucket MCP server

Atlassian Bitbucket MCP Server provides a bridge between AI assistants (like Anthropic's Claude or Cursor AI) and your Atlassian Bitbucket instance through the Model Context Protocol (MCP). This allows AI tools to securely access and interact with your repositories, pull requests, and workspaces in real-time.

Installation

Prerequisites

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

Authentication Setup

Before using the server, you need to authenticate with Bitbucket. There are two authentication options:

Option 1: Bitbucket App Password (Recommended)

1. Generate an app password from Bitbucket App Passwords
2. Ensure it has these minimum permissions:
   • Workspaces: Read
   • Repositories: Read
   • Pull Requests: Read

Option 2: Atlassian API Token

Generate a token from Atlassian API Tokens

Configuring Credentials

You can provide credentials in two ways:

Method 1: MCP Config File (Recommended)

Create or edit ~/.mcp/configs.json:

Using Bitbucket App Password:

{
	"@aashari/mcp-server-atlassian-bitbucket": {
		"environments": {
			"ATLASSIAN_BITBUCKET_USERNAME": "<your_username>",
			"ATLASSIAN_BITBUCKET_APP_PASSWORD": "<your_app_password>"
		}
	}
}

Using Atlassian API Token:

{
	"@aashari/mcp-server-atlassian-bitbucket": {
		"environments": {
			"ATLASSIAN_SITE_NAME": "bitbucket",
			"ATLASSIAN_USER_EMAIL": "<your_email>",
			"ATLASSIAN_API_TOKEN": "<your_api_token>"
		}
	}
}

Method 2: Environment Variables

Pass credentials directly when running the server:

ATLASSIAN_BITBUCKET_USERNAME="<your_username>" \
ATLASSIAN_BITBUCKET_APP_PASSWORD="<your_app_password>" \
npx -y @aashari/mcp-server-atlassian-bitbucket

Connecting to AI Assistants

To connect your MCP-compatible AI assistant:

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

This configuration launches the server automatically when needed.

Using MCP Tools

The following tools are available when using this server with an MCP-compatible AI assistant. Note that MCP tools use snake_case for names and camelCase for parameters.

Workspace Management

list_workspaces

Lists all available Bitbucket workspaces:

{}

Or search for specific workspaces:

{ "query": "devteam" }

get_workspace

Get details for a specific workspace:

{ "workspaceSlug": "acme-corp" }

Repository Management

list_repositories

List repositories in a workspace:

{ "workspaceSlug": "acme-corp" }

With search:

{ "workspaceSlug": "acme-corp", "query": "api" }

get_repository

Get details of a specific repository:

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

Search Functionality

search

Search across different scopes:

Repositories:

{ "workspaceSlug": "acme-corp", "query": "api", "scope": "repositories" }

Pull Requests:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api",
	"query": "fix",
	"scope": "pullrequests"
}

Commits:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api",
	"query": "update",
	"scope": "commits"
}

Code:

{ "workspaceSlug": "acme-corp", "query": "function getUser", "scope": "code" }

Pull Request Operations

list_pull_requests

List pull requests in a repository:

{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "state": "OPEN" }

get_pull_request

Get detailed information about a pull request:

{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "prId": "42" }

list_pr_comments

List comments on a pull request:

{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "prId": "42" }

add_pr_comment

Add a general comment:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"prId": "42",
	"content": "Looks good."
}

Add an inline comment:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"prId": "42",
	"content": "Consider refactoring.",
	"inline": { "path": "src/utils.js", "line": 42 }
}

pull_requests_create

Create a new pull request:

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

Command Line Interface

The server can also be used directly from the command line.

Quick Usage with npx

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

npx -y @aashari/mcp-server-atlassian-bitbucket get-repository \
  --workspace-slug acme-corp \
  --repo-slug backend-api

Installing Globally

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

Then run directly:

mcp-atlassian-bitbucket list-workspaces

Getting Help

View all available commands:

mcp-atlassian-bitbucket --help

Get help for a specific command:

mcp-atlassian-bitbucket get-repository --help

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.