Bitbucket Cloud MCP Server

A Model Context Protocol (MCP) server for the Bitbucket Cloud REST API v2.0. Works with any MCP client — Claude Code, GitHub Copilot, OpenAI Codex, and more. Provides 32 tools across 5 toolsets with safety controls and compact LLM-optimized output.

Setup

Prerequisites

• Node.js v24+
• Atlassian API token (see below)

Create an API Token

1. Go to Atlassian API Tokens
2. Click "Create API token with scopes"
3. Name the token (e.g., "Bitbucket MCP") and set expiration
4. Select app: Bitbucket
5. Enable the scopes listed below
6. Click Create and copy the token

Read-only scopes (6 scopes — sufficient when using BITBUCKET_READONLY=true):

Scope	Enables
read:user:bitbucket	bb_whoami
read:workspace:bitbucket	bb_list_workspaces
read:repository:bitbucket	bb_list_repositories, bb_get_repository, bb_list_branches, bb_list_commits, bb_get_file, bb_list_directory, bb_search_code
read:pullrequest:bitbucket	bb_list_pull_requests, bb_get_pull_request, bb_get_pull_request_diff, bb_get_pull_request_diffstat, bb_list_pull_request_activity
read:issue:bitbucket	bb_list_issues, bb_get_issue
read:pipeline:bitbucket	bb_list_pipelines, bb_get_pipeline

Write scopes (add these 4 for full access):

Scope	Enables
write:repository:bitbucket	bb_create_commit_files, bb_create_branch, bb_delete_branch
write:pullrequest:bitbucket	bb_create_pull_request, bb_update_pull_request, bb_add_pull_request_comment, bb_approve_pull_request, bb_request_changes_pull_request, bb_merge_pull_request, bb_decline_pull_request
write:issue:bitbucket	bb_create_issue, bb_comment_issue
write:pipeline:bitbucket	bb_trigger_pipeline

Add to Your MCP Client

Claude Code

One command — no clone or build needed:

claude mcp add bitbucket \
  -e ATLASSIAN_USER_EMAIL=your-email@example.com \
  -e ATLASSIAN_API_TOKEN=your-api-token \
  -e BITBUCKET_READONLY=false \
  -- npx -y @or2ooo/bitbucket-mcp@latest

Verify with:

claude mcp list

GitHub Copilot (VS Code)

Add to .vscode/mcp.json in your project root:

{
  "servers": {
    "bitbucket": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@or2ooo/bitbucket-mcp@latest"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "your-api-token",
        "BITBUCKET_READONLY": "false"
      }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.bitbucket]
command = "npx"
args = ["-y", "@or2ooo/bitbucket-mcp@latest"]
env = { ATLASSIAN_USER_EMAIL = "your-email@example.com", ATLASSIAN_API_TOKEN = "your-api-token", BITBUCKET_READONLY = "false" }

From source (for development)

git clone https://github.com/or2ooo/bitbucket-mcp.git
cd bitbucket-mcp
npm install && npm run build

claude mcp add bitbucket \
  -e ATLASSIAN_USER_EMAIL=your-email@example.com \
  -e ATLASSIAN_API_TOKEN=your-api-token \
  -e BITBUCKET_READONLY=true \
  -- node $(pwd)/dist/index.js

Environment Variables

Variable	Required	Description
ATLASSIAN_USER_EMAIL	Yes	Atlassian account email
ATLASSIAN_API_TOKEN	Yes	Atlassian API token (see Create an API Token)
BITBUCKET_DEFAULT_WORKSPACE	No	Default workspace slug
BITBUCKET_ALLOWED_WORKSPACES	No	Comma-separated allowlist of workspace slugs
BITBUCKET_ALLOWED_REPOS	No	Comma-separated allowlist (slug or workspace/slug)
BITBUCKET_READONLY	No	true to block all write operations
BITBUCKET_BASE_URL	No	Override API base URL

Safety Controls

• Readonly mode: Set BITBUCKET_READONLY=true to prevent any write operations.
• Workspace allowlist: Restrict access to specific workspaces.
• Repository allowlist: Restrict access to specific repositories.
• Destructive action confirmation: Merge PR, decline PR, and delete branch tools require explicit confirm: true.

Tool Reference

Context (2 tools)

Tool	Description
bb_whoami	Get current authenticated user
bb_list_workspaces	List accessible workspaces

Repositories (10 tools)

Tool	Description
bb_list_repositories	List repositories in a workspace
bb_get_repository	Get repository details
bb_list_branches	List branches
bb_list_commits	List commits (optionally for a branch/tag)
bb_get_file	Get file content at a specific revision
bb_create_commit_files	Create a commit with file changes (write)
bb_create_branch	Create a new branch (write)
bb_delete_branch	Delete a branch (destructive, requires confirm)
bb_list_directory	List directory contents at a specific revision
bb_search_code	Search for code in a workspace or repository

Pull Requests (12 tools)

Tool	Description
bb_list_pull_requests	List PRs with optional state filter
bb_get_pull_request	Get PR details
bb_create_pull_request	Create a new PR (write)
bb_update_pull_request	Update PR title, description, or reviewers (write)
bb_get_pull_request_diff	Get PR diff (raw text)
bb_get_pull_request_diffstat	Get PR diffstat summary
bb_list_pull_request_activity	List PR activity (comments, approvals, updates)
bb_add_pull_request_comment	Add a comment to a PR (write)
bb_approve_pull_request	Approve a PR (write)
bb_request_changes_pull_request	Request changes on a PR (write)
bb_merge_pull_request	Merge a PR (destructive, requires confirm)
bb_decline_pull_request	Decline a PR (destructive, requires confirm)

Issues (4 tools)

Tool	Description
bb_list_issues	List issues with optional query
bb_get_issue	Get issue details
bb_create_issue	Create a new issue (write)
bb_comment_issue	Add a comment to an issue (write)

Pipelines (3 tools)

Tool	Description
bb_list_pipelines	List recent pipelines
bb_get_pipeline	Get pipeline details
bb_trigger_pipeline	Trigger a pipeline run (write)

Development

npm test         # Run tests
npm run lint     # Lint
npm run build    # Compile

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Security

See SECURITY.md for reporting vulnerabilities.

License

MIT