Name: Bitbucket Cloud API MCP Server
Author: aashari

LABSCO SUMMARY

The whole Bitbucket Cloud API, from your own computer.

For people who keep their code in Bitbucket Cloud, it lets an assistant make any call the Bitbucket API allows, from listing open pull requests to merging one or deleting a branch. Atlassian's own hosted server also covers Bitbucket, with its own ready-made tools, for workspaces linked to an Atlassian organization where an admin has turned on API-token access; this one runs on your computer and can reach any part of the Bitbucket API.

What it is

A server that runs on your own computer and connects your assistant to Bitbucket Cloud. Instead of one tool per task, it hands the assistant the Bitbucket API itself, so it can read, create, change or delete anything the API reaches, and clone a repository. It is built by an independent developer, aashari, not by Atlassian.

What you get

Workspaces, repositories, branches, commits and file contents, read on request
Open pull requests listed, with their diffs and comments
Pull requests created, commented on, approved and merged
Pull request titles, descriptions and reviewers updated, and repository settings changed
Branches, pull request comments and approvals removed
Branches and commits compared side by side
Issues, pipelines, deployments and any other part of the Bitbucket Cloud API
A repository cloned into a folder on your computer, over SSH or HTTPS
Replies cut to just the fields asked for

Requirements

A Bitbucket Cloud account; Bitbucket Server and Data Center are not supported.
An Atlassian API token made for Bitbucket under API tokens in your Atlassian account settings, with read scopes for repositories and workspaces, plus pull request scopes if you want it to work on pull requests.
The token goes in ATLASSIAN_API_TOKEN and your Atlassian email in ATLASSIAN_USER_EMAIL.
Node.js 18 or newer, since it starts with npx.

Setup effort

One command plus a key — npx -y @aashari/mcp-server-atlassian-bitbucket, then supply credentials

See installation options

USE CASES

Catching up on pull requests waiting for review

Ask for the open pull requests in a repository, read the changes in the one you pick, then approve it.

bb_getbb_post

Opening a pull request from the chat

Ask it to open a pull request from feature-login into main, then add a comment saying the tests passed.

bb_post

Seeing what changed between a branch and main

Compare your feature branch with main, or two commits with each other, and get the differences back.

bb_get

Keeping a pull request tidy

Change a pull request's title or reviewers, and delete its branch once the work is merged.

bb_patchbb_delete

Getting a repository onto your computer

Name the repository and a folder, and it is cloned there, over SSH if your keys are set up and HTTPS if not.

bb_clone

Explore all 6 tools

Measured by connecting to the server and asking it what it exposes.

bb_clone

Clone a Bitbucket repository to your local filesystem using SSH (preferred) or HTTPS.

Provide repoSlug and targetPath (absolute path). Clones into targetPath/repoSlug. SSH keys must be configured; falls back to HTTPS if unavailable.

bb_delete

Delete Bitbucket resources. Returns TOON format by default.

Output format: TOON (default) or JSON (outputFormat: "json")

Common operations:

Delete branch: /repositories/{workspace}/{repo}/refs/branches/{branch_name}
Delete PR comment: /repositories/{workspace}/{repo}/pullrequests/{pr_id}/comments/{comment_id}
Decline PR: /repositories/{workspace}/{repo}/pullrequests/{id}/decline
Remove PR approval: /repositories/{workspace}/{repo}/pullrequests/{id}/approve
Delete repository: /repositories/{workspace}/{repo} (caution: irreversible)

Note: Most DELETE endpoints return 204 No Content on success.

The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/

bb_get

Read any Bitbucket data. Returns TOON format by default (30-60% fewer tokens than JSON).

IMPORTANT - Cost Optimization:

ALWAYS use jq param to filter response fields. Unfiltered responses are very expensive!
Use pagelen query param to restrict result count (e.g., pagelen: "5")
If unsure about available fields, first fetch ONE item with pagelen: "1" and NO jq filter to explore the schema, then use jq in subsequent calls

Schema Discovery Pattern:

First call: path: "/workspaces", queryParams: {"pagelen": "1"} (no jq) - explore available fields
Then use: jq: "values[*].{slug: slug, name: name, uuid: uuid}" - extract only what you need

Output format: TOON (default, token-efficient) or JSON (outputFormat: "json")

Common paths:

/workspaces - list workspaces
/repositories/{workspace} - list repos in workspace
/repositories/{workspace}/{repo} - get repo details
/repositories/{workspace}/{repo}/pullrequests - list PRs
/repositories/{workspace}/{repo}/pullrequests/{id} - get PR details
/repositories/{workspace}/{repo}/pullrequests/{id}/comments - list PR comments
/repositories/{workspace}/{repo}/pullrequests/{id}/diff - get PR diff
/repositories/{workspace}/{repo}/refs/branches - list branches
/repositories/{workspace}/{repo}/commits - list commits
/repositories/{workspace}/{repo}/src/{commit}/{filepath} - get file content
/repositories/{workspace}/{repo}/diff/{source}..{destination} - compare branches/commits

Query params: pagelen (page size), page (page number), q (filter), sort (order), fields (sparse response)

Example filters (q param): state="OPEN", source.branch.name="feature", title~"bug"

JQ examples: values[*].slug, values[0], values[*].{name: name, uuid: uuid}

The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/

bb_patch

Partially update Bitbucket resources. Returns TOON format by default.

IMPORTANT - Cost Optimization: Use jq param to filter response fields.

Output format: TOON (default) or JSON (outputFormat: "json")

Common operations:

Update PR title/description: /repositories/{workspace}/{repo}/pullrequests/{id} body: {"title": "New title", "description": "Updated description"}

Update PR reviewers: /repositories/{workspace}/{repo}/pullrequests/{id} body: {"reviewers": [{"uuid": "{user-uuid}"}]}

Update repository properties: /repositories/{workspace}/{repo} body: {"description": "New description"}

Update comment: /repositories/{workspace}/{repo}/pullrequests/{pr_id}/comments/{comment_id} body: {"content": {"raw": "Updated comment"}}

The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/

bb_post

Create Bitbucket resources. Returns TOON format by default (token-efficient).

IMPORTANT - Cost Optimization:

Use jq param to extract only needed fields from response (e.g., jq: "{id: id, title: title}")
Unfiltered responses include all metadata and are expensive!

Output format: TOON (default) or JSON (outputFormat: "json")

Common operations:

Create PR: /repositories/{workspace}/{repo}/pullrequests body: {"title": "...", "source": {"branch": {"name": "feature"}}, "destination": {"branch": {"name": "main"}}}

Add PR comment: /repositories/{workspace}/{repo}/pullrequests/{id}/comments body: {"content": {"raw": "Comment text"}}

Approve PR: /repositories/{workspace}/{repo}/pullrequests/{id}/approve body: {}

Request changes: /repositories/{workspace}/{repo}/pullrequests/{id}/request-changes body: {}

Merge PR: /repositories/{workspace}/{repo}/pullrequests/{id}/merge body: {"merge_strategy": "squash"} (strategies: merge_commit, squash, fast_forward)

The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/

bb_put

Replace Bitbucket resources (full update). Returns TOON format by default.

IMPORTANT - Cost Optimization:

Use jq param to extract only needed fields from response
Example: jq: "{uuid: uuid, name: name}"

Output format: TOON (default) or JSON (outputFormat: "json")

Common operations:

Update repository: /repositories/{workspace}/{repo} body: {"description": "...", "is_private": true, "has_issues": true}

Create/update file: /repositories/{workspace}/{repo}/src Note: Use multipart form data for file uploads (complex - prefer PATCH for metadata)

Update branch restriction: /repositories/{workspace}/{repo}/branch-restrictions/{id} body: {"kind": "push", "pattern": "main", "users": [{"uuid": "..."}]}

The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/

BEFORE YOU INSTALL

What to know first

Tools you get

6 tools when we connected. Four of its six tools can create, change or delete Bitbucket data, and deleting a repository cannot be undone. For an assistant that only reads, give the token read scopes only.

Requires

Node.js 18 or newer
a Bitbucket Cloud account; Bitbucket Server and Data Center are not supported
an Atlassian API token made for Bitbucket. App passwords, which this project's README still describes, no longer work: Atlassian has switched them off for Bitbucket Cloud
for cloning a repository: git, with SSH keys set up for Bitbucket; without them it clones over HTTPS

INSTALLATION

Choose how to get started.

Add the block to your client, or run the command directly.

Direct Install

Config file

JSON

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@aashari/mcp-server-atlassian-bitbucket"
      ],
      "env": {
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_scoped_api_token"
      }
    }
  }
}

npx

TERMINAL

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

The author's launch command

Bitbucket Data Center MCP Server

Manage Bitbucket repositories, pull requests, and pipelines via the Bitbucket API for both Cloud and Server.

Github MCP Server Java

The GitHub API as MCP tools over HTTP/SSE — repositories, issues, pull requests, search and users, from a Spring AI server.

Bitbucket Server MCP

Manage pull requests on Bitbucket Server.

Custom GitLab MCP Server

Interact with GitLab repositories, issues, and merge requests through an MCP-compliant server.