Bitbucket MCP Server

Bitbucket MCP Server (Python)

Connect Claude Code, OpenAI Codex, Cursor, VS Code (GitHub Copilot), and any MCP-compatible AI assistant to your Bitbucket Cloud repositories. Review pull requests, monitor pipelines, and manage your code — all through natural language.

Features

• 60+ MCP tools — repositories, pull requests, comments, tasks, diffs, pipelines (runtime + config), build statuses, reviewers, draft PRs, batch review, issue tracker, commits, source/file browsing
• MCP 2025 tool annotations — every tool advertises readOnlyHint / destructiveHint / idempotentHint / openWorldHint + a human-readable title, so clients (Claude Code, Cursor) auto-include read-only tools and warn before destructive operations
• Slim responses — stripped API noise for lower LLM token usage
• Configurable — enable/disable tools via configs/tools.json or BITBUCKET_TOOLS_CONFIG env var
• Secure credentials — environment variables or system keychain

Quick Start

1. Install

The recommended way to run the server is via uvx (zero install, isolated environment):

# Always latest version

uvx --from bitbucket-mcp-py bitbucket-mcp

Pin a specific version

uvx --from bitbucket-mcp-py==1.8.1 bitbucket-mcp

Why `--from`? The PyPI package is bitbucket-mcp-py but the command entry point is bitbucket-mcp. The --from flag tells uvx which package to install.

Alternative install methods

2. Configure credentials

Set the following environment variables — in your MCP client's env block, as shown above, or in the system keychain (see Credentials):

Get your API token at: https://id.atlassian.com/manage-profile/security/api-tokens

⚠️ Use a scoped token, not a global one. When creating the token, select specific scopes (e.g. Repositories: Read, Pull requests: Read/Write). Global tokens without explicit scopes do not work with this MCP server.

3. Configure your AI assistant

Claude Code (recommended)

Option A — CLI (fastest):

claude mcp add bitbucket-mcp \

-e BITBUCKET_USERNAME=your-email@example.com \ -e BITBUCKET_TOKEN=your-api-token \ -e BITBUCKET_WORKSPACE=your-workspace \ -- uvx --from bitbucket-mcp-py bitbucket-mcp

Option B — JSON config (~/.claude.json or project .mcp.json):

{

"mcpServers": { "bitbucket-mcp": { "type": "stdio", "command": "uvx", "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"], "env": { "BITBUCKET_USERNAME": "your-email@example.com", "BITBUCKET_TOKEN": "your-api-token", "BITBUCKET_WORKSPACE": "your-workspace" } } } }

OpenAI Codex

Option A — CLI (fastest):

codex mcp add bitbucket-mcp \

--env BITBUCKET_USERNAME=your-email@example.com \ --env BITBUCKET_TOKEN=your-api-token \ --env BITBUCKET_WORKSPACE=your-workspace \ -- uvx --from bitbucket-mcp-py bitbucket-mcp

Option B — TOML config (~/.codex/config.toml):

[mcp_servers.bitbucket-mcp]

command = "uvx" args = ["--from", "bitbucket-mcp-py", "bitbucket-mcp"] env = { BITBUCKET_USERNAME = "your-email@example.com", BITBUCKET_TOKEN = "your-api-token", BITBUCKET_WORKSPACE = "your-workspace" }

Cursor

Add to ~/.cursor/mcp.json:

{

"mcpServers": { "bitbucket-mcp": { "command": "uvx", "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"], "env": { "BITBUCKET_USERNAME": "your-email@example.com", "BITBUCKET_TOKEN": "your-api-token", "BITBUCKET_WORKSPACE": "your-workspace" } } } }

VS Code (GitHub Copilot)

Add to .vscode/mcp.json (workspace) or ~/Library/Application Support/Code/User/mcp.json (global, macOS):

{

"servers": { "bitbucket-mcp": { "type": "stdio", "command": "uvx", "args": ["--from", "bitbucket-mcp-py", "bitbucket-mcp"], "env": { "BITBUCKET_USERNAME": "your-email@example.com", "BITBUCKET_TOKEN": "your-api-token", "BITBUCKET_WORKSPACE": "your-workspace" } } } }

Available Tools

Disabled by default: merge_pull_request (safety), stop_pipeline (safety), get_pull_request_patch (git am format — not useful for AI review), convert_pull_request_to_draft (not supported by Bitbucket API), delete_issue (safety), delete_issue_comment (safety), add_commit_comment (write op), create_pipeline_variable / update_pipeline_variable / delete_pipeline_variable (write ops), create_pipeline_schedule / update_pipeline_schedule / delete_pipeline_schedule (write ops), delete_pipeline_cache (safety), create_environment / delete_environment / create_deployment_variable / update_deployment_variable / delete_deployment_variable (write ops), create_branch_restriction / update_branch_restriction / delete_branch_restriction (write ops). Enable in configs/tools.json.

Governance scopes — Branch restriction read tools need the repository scope (repository:admin may be required depending on repo config); the write tools need repository:admin. Workspace member/permission tools need the account scope. The /members endpoint lists users without a per-user permission (use list_workspace_permissions for roles).

Deployments scopes — the read tools (list_environments, get_environment, list_deployments, get_deployment, list_deployment_variables) need the deployment scope; the write tools need deployment:write. Bitbucket has no server-side filter for deployments by environment (BCLOUD-18729) — filter on the environment field of list_deployments instead. There is no update_environment tool: Bitbucket exposes no PUT for environments (only POST .../changes for locking).

Custom tool configuration

By default the server reads configs/tools.json bundled with the package. You can point to a custom file at runtime without rebuilding:

export BITBUCKET_TOOLS_CONFIG=/path/to/my-tools.json

Fallback chain (first match wins):

1. BITBUCKET_TOOLS_CONFIG environment variable
2. Built-in configs/tools.json

Fail-safe behaviour — If BITBUCKET_TOOLS_CONFIG is set but the file is missing or contains invalid JSON, the server raises an error on startup (explicit failure rather than silently ignoring the override). If the built-in default is missing, all tools are enabled.

Token tip — get_pull_request_diff accepts an optional path parameter to filter the diff to a single file, reducing token usage by ~95% on large PRs:

`

get_pull_request_diff(repo_slug, pull_request_id, path="src/services/myService.ts")

`

Token tip — get_pipeline_step_logs returns only the trailing 100 KiB of a step log by

default (raw logs run to several MB on long steps). The response carries a truncated flag;

widen the window with the absolute byte range start / end, or pass max_bytes=null for

the whole log. Pass a service container UUID as log_uuid to read that service's log

instead of the build container's. This endpoint needs a real pipeline UUID — resolve it

via get_pipeline_run if you only have a build number.

`

get_pipeline_step_logs(repo_slug, pipeline_uuid="{adab6a1f-...}", step_uuid="{84fc6465-...}")

`

MCP Prompts

The server also exposes MCP Prompts — parameterised templates that compatible clients (Claude Code, Cursor, ...) surface as slash commands. Instead of remembering tool names, you invoke a prompt and the assistant orchestrates the right tools for you. They appear in the client's prompt picker (prompts/list).

| review_pull_request | repo_slug, pull_request_id | Full AI revie