How do I use bitbucket-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@bitbucket-mcp show the diff for pull request #42" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

bitbucket-mcp

by matt-nann

Overview Schema Source Related Servers Discussions Admin

Python

Hybrid

bitbucket-mcp

A Model Context Protocol server for Bitbucket Cloud. Review, manage, and merge pull requests, assign reviewers by name, read files at a ref, and inspect pipeline status — from any MCP client (Claude Desktop, Cursor, Claude Code) or a hosted HTTP endpoint.

It talks to the Bitbucket Cloud REST API v2.0 with a single access token. All read paths are paginated and capped; write tools (create/merge PR, comments, reviewers) are explicit.

Tools

All tools are prefixed bb_.

Tool	What it does
`bb_list_pull_requests`	List PRs in a repo, filtered by state
`bb_get_pull_request`	Full detail for one PR
`bb_get_pull_request_diff`	Unified diff for a PR
`bb_get_pull_request_comments`	All comments on a PR (inline + general)
`bb_get_pull_request_status`	Aggregated build/status checks for a PR
`bb_get_pipeline_status`	Commit statuses for an arbitrary ref
`bb_create_pull_request`	Open a PR (optionally with reviewers)
`bb_merge_pull_request`	Merge a PR (merge_commit / squash / fast_forward)
`bb_create_pull_request_comment`	Add a comment (optionally inline on a file/line)
`bb_edit_pull_request_comment`	Edit one of your comments
`bb_delete_pull_request_comment`	Delete one of your comments
`bb_add_pull_request_reviewers`	Assign reviewers by name or UUID
`bb_list_workspace_members`	Inspect the local known-members directory
`bb_get_file`	Read a file's contents at a branch/commit

Assigning reviewers by name

Bitbucket's /workspaces/{workspace}/members endpoint requires the account scope (which PR tokens don't carry), so you can't resolve a person's name to their account UUID over the API. This server keeps a small local directory of known members so bb_add_pull_request_reviewers accepts a plain name (e.g. "Jane Doe") and resolves it offline. Raw account UUIDs always work too.

Seed people in either place (both use the same JSON shape; the env var merges on top of the file):

tools/bitbucket/directory.json — copy directory.example.json and fill it in. This file is git-ignored so real account UUIDs never get committed.
BITBUCKET_KNOWN_MEMBERS env var — handy for hosted deploys.

{
  "your-workspace-slug": [
    { "uuid": "{00000000-0000-0000-0000-000000000000}", "display_name": "Jane Doe", "nickname": "Jane" }
  ]
}

Related MCP server: Bitbucket MCP

Configuration

Set via environment variables (see .env.example). Prefix BITBUCKET_.

Variable	Required	Description
`BITBUCKET_API_KEY`	✅	Access token (Bearer) or app password
`BITBUCKET_USERNAME`	—	Set only when using an app password (switches to Basic auth)
`BITBUCKET_WORKSPACE`	—	Default workspace slug, so tools don't need it each call
`BITBUCKET_DEFAULT_REPO`	—	Default repo slug
`BITBUCKET_KNOWN_MEMBERS`	—	JSON of extra known members (merged over `directory.json`)
`BITBUCKET_MAX_PAGES`	—	Pagination cap (default `10`)
`BITBUCKET_TIMEOUT`	—	HTTP timeout in seconds (default `30`)

Tools are always listed but return a clear "not configured" error if BITBUCKET_API_KEY is missing, so the server starts cleanly without secrets.

Quick start (local, stdio)

Requires Python 3.11+.

git clone https://github.com/matt-nann/bitbucket-mcp.git
cd bitbucket-mcp
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export BITBUCKET_API_KEY=your-token
python server.py            # stdio (default)

Wire it into an MCP client

Claude Desktop (claude_desktop_config.json) / Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "bitbucket": {
      "command": "python",
      "args": ["/absolute/path/to/bitbucket-mcp/server.py"],
      "env": {
        "BITBUCKET_API_KEY": "your-token",
        "BITBUCKET_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

Claude Code:

claude mcp add bitbucket \
  --env BITBUCKET_API_KEY=your-token \
  --env BITBUCKET_WORKSPACE=your-workspace-slug \
  -- python /absolute/path/to/bitbucket-mcp/server.py

Hosting (HTTP)

The same server runs over streamable HTTP for a shared/hosted deployment. It binds dual-stack IPv6 and honors $PORT, so it works on Railway (and Fly/Heroku/Docker) out of the box:

MCP_TRANSPORT=http PORT=8000 python server.py --http
# MCP endpoint: http://localhost:8000/mcp   health: /health

⚠️ HTTP mode has no built-in authentication and every request uses the one BITBUCKET_API_KEY identity. Don't expose it publicly without an auth proxy in front. See HOSTING.md for the full Railway walkthrough, Docker instructions, and the security model.

Provenance

Extracted from a larger internal multi-tool MCP server into a standalone, self-contained package. No internal identifiers or shared auth layers are included; the member directory ships only as a placeholder example.

License

MIT

Available Tools

9 tools

bb_create_pull_requestB

Create a new Bitbucket pull request.

Args: title: PR title. source_branch: Source branch name. destination_branch: Destination branch name (default "main"). description: PR description (Markdown). reviewers: List of Bitbucket account UUIDs. close_source_branch: Delete source branch after merge. workspace: Bitbucket workspace slug. repo: Repository slug.

Inputs: title (required), source_branch (required), repo, reviewers, +4 more. Returns: object

bb_create_pull_request_commentA

Add a comment to a Bitbucket pull request — general or inline on a specific file/line.

Args: pull_request_id: The PR id (number). content: Comment body (Markdown). inline_path: File path for inline comment. inline_to: Line number in new version. inline_from: Line number in old version. workspace: Bitbucket workspace slug. repo: Repository slug.

Inputs: content (required), pull_request_id (required), repo, inline_to, +3 more. Returns: object

bb_delete_pull_request_commentA

Delete a comment from a Bitbucket pull request.

Permanently removes the comment. Only the comment's author may delete it — deleting someone else's comment fails with an authorization error. Get comment ids from bb_get_pull_request_comments. Returns a confirmation with the deleted comment id.

Args: pull_request_id: The PR id (number). comment_id: The id of the comment to delete. workspace: Bitbucket workspace slug. repo: Repository slug.

Inputs: comment_id (required), pull_request_id (required), repo, workspace. Returns: object

bb_edit_pull_request_commentA

Edit the body of an existing Bitbucket pull request comment.

Replaces the comment's content with content and returns the updated comment. Only the comment's author may edit it — editing someone else's comment fails with an authorization error. Get comment ids from bb_get_pull_request_comments.

Args: pull_request_id: The PR id (number). comment_id: The id of the comment to edit. content: New comment body (Markdown), replaces the old one. workspace: Bitbucket workspace slug. repo: Repository slug.

Inputs: content (required), comment_id (required), pull_request_id (required), repo, +1 more. Returns: object

bb_get_pull_requestA

Get a Bitbucket PR's metadata: title, description, author, branches, reviewers, state.

Args: pull_request_id: The PR id (number). workspace: Bitbucket workspace slug. repo: Repository slug.

Inputs: pull_request_id (required), repo, workspace. Returns: object

bb_get_pull_request_commentsA

Get the review discussion on a Bitbucket PR (general and inline comments).

Args: pull_request_id: The PR id (number). workspace: Bitbucket workspace slug. repo: Repository slug.

Inputs: pull_request_id (required), repo, workspace. Returns: object

bb_get_pull_request_diffB

Get the unified diff for a Bitbucket PR. Returns raw diff text.

Args: pull_request_id: The PR id (number). file_path: Optional file path filter. workspace: Bitbucket workspace slug. repo: Repository slug.

Inputs: pull_request_id (required), repo, file_path, workspace. Returns: result

bb_get_pull_request_statusA

Get CI/build status for a Bitbucket PR's latest commit.

Args: pull_request_id: The PR id (number). workspace: Bitbucket workspace slug. repo: Repository slug.

Inputs: pull_request_id (required), repo, workspace. Returns: object

bb_list_workspace_membersA

List known workspace members to resolve a person's name to their UUID.

Members come from the local known-members directory (see directory.py). Bitbucket's live members API is not used: it requires the account scope the MCP token doesn't carry, so it only ever returned 403. The directory is the single source of truth — seed people into directory.json or the BITBUCKET_KNOWN_MEMBERS env var.

You usually don't need to call this before bb_add_pull_request_reviewers — that tool resolves names against the same directory itself. Use this to inspect who is known, or when a name is ambiguous. If more than one member matches, present the candidates rather than guessing.

Args: query: Optional case-insensitive name filter (display name or nickname). workspace: Bitbucket workspace slug.

Inputs: query, workspace. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-07-22 05:33 across 9 tools

Disambiguation5/5

Each tool targets a distinct action on pull requests or workspace members. No two tools overlap in purpose; create, get, diff, status, and comment operations are clearly separated.

Naming Consistency5/5

All tools follow a consistent 'bb_verb_noun' pattern (e.g., bb_create_pull_request, bb_get_pull_request_comments). The naming is uniform and predictable across the entire set.

Tool Count5/5

With 9 tools, the server is well-scoped for Bitbucket pull request management. It covers core operations without being overly broad or too sparse.

Completeness3/5

While comment CRUD is fully covered, missing operations like listing, updating, merging, or declining pull requests create gaps for a complete PR workflow. The workspace members list is a helpful auxiliary tool.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

neverinfamous-memory-journal-mcp
ai.smithery
A MCP server built for developers enabling Git based project management with project and personal…
Version Control Developer Tools Project Management
321
https://server.smithery.ai/@neverinfamous/memory-journal-mcp/mcp
JFrog Remote MCP Server
io.github.jfrog
MCP Server for JFrog, providing tools for development and artifact management.
Developer Tools CI/CD & DevOps Cloud Platforms
215
https://myPlatform.jfrog.github.io/mcp
Azure DevOps (ADO)
io.github.PremierInc
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
CI/CD & DevOps Version Control Project Management
22,087
https://mcp.dev.azure.com
Appcircle MCP
io.appcircle
MCP server for Appcircle mobile CI/CD platform.
CI/CD & DevOps Developer Tools
2
https://mcp.appcircle.io

Related MCP Servers

Bitbucket MCP Server
Version Control CI/CD & DevOps Developer Tools
pdogra1299
A
license
B
quality
C
maintenance
An MCP server that enables interaction with Bitbucket repositories through the Model Context Protocol, supporting both Bitbucket Cloud and Server with features for PR lifecycle management and code review.
Updated 18 days ago (2026-10-26 12:05 UTC)
20
8,411 npm
30
MIT
Bitbucket MCP
Version Control Developer Tools
inconcept
A
license
B
quality
D
maintenance
An MCP server for Bitbucket Cloud that enables managing pull requests, branches, and repositories in natural language from any MCP-capable client.
Updated 6 months ago (2026-05-23 14:13 UTC)
23
387 npm
4
MIT
Bitbucket MCP Server
Version Control Developer Tools
nbhson
A
license
B
quality
B
maintenance
MCP server for Bitbucket Server integration, enabling project, repository, pull request, source code, branch, and code review operations via the Bitbucket Server APIs.
Updated 11 days ago (2026-11-02 01:32 UTC)
27
89 npm
MIT
bitbucket-mcp
Version Control CI/CD & DevOps
Zomino
F
license
C
quality
D
maintenance
An MCP server for Bitbucket Cloud, covering pull requests, pull request comments, and pipelines.
Updated 4 months ago (2026-07-16 18:04 UTC)
26
-

bitbucket-mcp

Tools

Assigning reviewers by name

Configuration

Quick start (local, stdio)

Wire it into an MCP client

Hosting (HTTP)

Provenance

License

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Bitbucket MCP Server

Bitbucket MCP

Bitbucket MCP Server

bitbucket-mcp