MCP server for Bitbucket – manage pull requests, comments, reviews, and diffs via AI assistants.

These details have not been verified by PyPI

Project description

Bitbucket LLM Bridge

An MCP (Model Context Protocol) server for Bitbucket. Connect Cursor, Claude Desktop, or any MCP-compatible client to your Bitbucket instance and let an AI assistant create PRs, review code, comment on diffs, and more -- all through natural language.

Two fully equivalent implementations are provided -- pick whichever fits your stack:

Implementation	Directory	Runtime
TypeScript	typescript/	Node.js 18+
Python	python/	Python 3.10+

Both expose identical tools and produce the same output. Supports Bitbucket Cloud (API v2.0) and Bitbucket Server / Data Center (REST API 1.0).

Features

Tool	Description
`create_pr`	Create a new pull request
`get_pr`	Get PR details (title, description, state, author, reviewers)
`list_prs`	List pull requests with filters (state, author, limit)
`add_reviewer`	Add reviewer(s) / approver(s) to a PR
`approve_pr`	Approve a pull request
`get_pr_comments`	Read all comments on a PR
`add_pr_comment`	Add a general comment to a PR
`add_pr_inline_comment`	Comment on a specific line of code in the diff
`resolve_pr_comment`	Resolve or unresolve a PR comment
`get_pr_diff`	Get the full unified diff for a PR
`get_pr_commit_diff`	Get the diff for a specific commit in a PR
`merge_pr`	Merge a pull request
`decline_pr`	Decline (close) a pull request

Prerequisites

A Bitbucket Cloud account or a Bitbucket Server / Data Center instance with API access
Credentials (see Configuration below)

Configuration

The server requires environment variables depending on which Bitbucket variant you use:

Variable	Required For	Description
`BITBUCKET_TYPE`	All	`"cloud"` (default) or `"server"`
`BITBUCKET_CLOUD_USERNAME`	Cloud	Your Bitbucket username
`BITBUCKET_CLOUD_APP_PASSWORD`	Cloud	App password with PR read/write permissions
`BITBUCKET_SERVER_URL`	Server/DC	Base URL of your Bitbucket Server instance (e.g. `https://bitbucket.mycompany.com`)
`BITBUCKET_SERVER_TOKEN`	Server/DC	Personal Access Token
`BITBUCKET_DEFAULT_WORKSPACE`	Optional	Default workspace slug (Cloud) or project key (Server). Saves you from passing `workspace` on every tool call.
`BITBUCKET_DEFAULT_REPO_SLUG`	Optional	Default repository slug. Saves you from passing `repo_slug` on every tool call.

When BITBUCKET_DEFAULT_WORKSPACE and BITBUCKET_DEFAULT_REPO_SLUG are set, every tool call that accepts workspace / repo_slug will use them as defaults. The LLM can still override them by explicitly passing different values in any individual tool call.

TypeScript

Prerequisites

Node.js 18+ -- download

Installation

From npm (recommended):

npm install -g bitbucket-llm-bridge

Or run directly with npx:

npx bitbucket-llm-bridge

From source:

git clone https://github.com/bardiabarabadi/Bitbucket-MCP.git
cd Bitbucket-MCP/typescript
npm install
npm run build

Connecting to Cursor

Add the server to your Cursor MCP configuration. Create or edit .cursor/mcp.json in your project root (or your global Cursor config).

Bitbucket Cloud:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "bitbucket-llm-bridge"],
      "env": {
        "BITBUCKET_TYPE": "cloud",
        "BITBUCKET_CLOUD_USERNAME": "your_username",
        "BITBUCKET_CLOUD_APP_PASSWORD": "your_app_password",
        "BITBUCKET_DEFAULT_WORKSPACE": "your_workspace",
        "BITBUCKET_DEFAULT_REPO_SLUG": "your_repo"
      }
    }
  }
}

Bitbucket Server / Data Center:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "bitbucket-llm-bridge"],
      "env": {
        "BITBUCKET_TYPE": "server",
        "BITBUCKET_SERVER_URL": "https://bitbucket.mycompany.com",
        "BITBUCKET_SERVER_TOKEN": "your_personal_access_token",
        "BITBUCKET_DEFAULT_WORKSPACE": "YOUR_PROJECT_KEY",
        "BITBUCKET_DEFAULT_REPO_SLUG": "your_repo"
      }
    }
  }
}

Restart Cursor after saving. To verify, open Cursor's MCP panel (gear icon -> MCP) and check that bitbucket appears as connected.

Connecting to Claude Desktop

Edit claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "bitbucket-llm-bridge"],
      "env": {
        "BITBUCKET_TYPE": "cloud",
        "BITBUCKET_CLOUD_USERNAME": "your_username",
        "BITBUCKET_CLOUD_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

Restart Claude Desktop after saving. You should see the MCP tools icon in the chat input.

Development

cd typescript

# Run in development mode (no build needed)
BITBUCKET_TYPE=cloud BITBUCKET_CLOUD_USERNAME=user BITBUCKET_CLOUD_APP_PASSWORD=pass npm run dev

# Type-check without emitting
npx tsc --noEmit

Project Structure

typescript/
  src/
    index.ts                    — Entry point: creates MCP server, registers tools, starts stdio transport
    config.ts                   — Environment variable parsing and config types
    client/
      base.ts                  — Abstract BitbucketClient interface
      cloud.ts                 — Bitbucket Cloud API v2.0 implementation
      datacenter.ts            — Bitbucket Server/DC REST API 1.0 implementation
    tools/
      pull-requests.ts         — create_pr, get_pr, list_prs, merge_pr, decline_pr
      comments.ts              — get_pr_comments, add_pr_comment, add_pr_inline_comment, resolve_pr_comment
      reviews.ts               — add_reviewer, approve_pr
      diff.ts                  — get_pr_diff, get_pr_commit_diff

Python

Prerequisites

Python 3.10+ -- download

Installation

From PyPI (recommended):

pip install bitbucket-llm-bridge

From source:

git clone https://github.com/bardiabarabadi/Bitbucket-MCP.git
cd Bitbucket-MCP/python
pip install -e .

Connecting to Cursor

Add the server to your Cursor MCP configuration. Create or edit .cursor/mcp.json in your project root (or your global Cursor config).

Global install (i.e. pip install bitbucket-llm-bridge):

{
  "mcpServers": {
    "bitbucket": {
      "command": "bitbucket-llm-bridge",
      "args": [],
      "env": {
        "BITBUCKET_TYPE": "cloud",
        "BITBUCKET_CLOUD_USERNAME": "your_username",
        "BITBUCKET_CLOUD_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

Venv install -- macOS / Linux:

{
  "mcpServers": {
    "bitbucket": {
      "command": "/path/to/your/venv/bin/bitbucket-llm-bridge",
      "args": [],
      "env": {
        "BITBUCKET_TYPE": "cloud",
        "BITBUCKET_CLOUD_USERNAME": "your_username",
        "BITBUCKET_CLOUD_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

Venv install -- Windows:

{
  "mcpServers": {
    "bitbucket": {
      "command": "C:/path/to/your/venv/Scripts/bitbucket-llm-bridge.exe",
      "args": [],
      "env": {
        "BITBUCKET_TYPE": "cloud",
        "BITBUCKET_CLOUD_USERNAME": "your_username",
        "BITBUCKET_CLOUD_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

Replace the credentials and venv path with your own values. Restart Cursor after saving.

Connecting to Claude Desktop

Edit claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Global install:

{
  "mcpServers": {
    "bitbucket": {
      "command": "bitbucket-llm-bridge",
      "args": [],
      "env": {
        "BITBUCKET_TYPE": "cloud",
        "BITBUCKET_CLOUD_USERNAME": "your_username",
        "BITBUCKET_CLOUD_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

Venv install -- macOS / Linux:

{
  "mcpServers": {
    "bitbucket": {
      "command": "/path/to/your/venv/bin/bitbucket-llm-bridge",
      "args": [],
      "env": {
        "BITBUCKET_TYPE": "server",
        "BITBUCKET_SERVER_URL": "https://bitbucket.mycompany.com",
        "BITBUCKET_SERVER_TOKEN": "your_personal_access_token"
      }
    }
  }
}

Venv install -- Windows:

{
  "mcpServers": {
    "bitbucket": {
      "command": "C:/path/to/your/venv/Scripts/bitbucket-llm-bridge.exe",
      "args": [],
      "env": {
        "BITBUCKET_TYPE": "server",
        "BITBUCKET_SERVER_URL": "https://bitbucket.mycompany.com",
        "BITBUCKET_SERVER_TOKEN": "your_personal_access_token"
      }
    }
  }
}

Restart Claude Desktop after saving. You should see the MCP tools icon in the chat input.

Development

cd python

# Install in editable mode
pip install -e .

# Run the server
BITBUCKET_TYPE=cloud BITBUCKET_CLOUD_USERNAME=user BITBUCKET_CLOUD_APP_PASSWORD=pass bitbucket-llm-bridge

# Or run as module
python -m bitbucket_llm_bridge

# Install dev dependencies and run tests
pip install pytest pytest-asyncio
pytest tests/ -v

Project Structure

python/
  src/bitbucket_llm_bridge/
    server.py                   — Entry point: creates FastMCP server, registers tools, starts stdio transport
    config.py                   — Environment variable parsing and BitbucketConfig dataclass
    client/
      base.py                  — Abstract BitbucketClient ABC
      cloud.py                 — Bitbucket Cloud API v2.0 implementation
      datacenter.py            — Bitbucket Server/DC REST API 1.0 implementation
    tools/
      pull_requests.py         — create_pr, get_pr, list_prs, merge_pr, decline_pr
      comments.py              — get_pr_comments, add_pr_comment, add_pr_inline_comment, resolve_pr_comment
      reviews.py               — add_reviewer, approve_pr
      diff.py                  — get_pr_diff, get_pr_commit_diff

Tool Reference

create_pr

Create a new pull request.

Parameters:

workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.
title (string, required) -- PR title
source_branch (string, required) -- Source branch name
destination_branch (string, required) -- Destination/target branch name
description (string, optional) -- PR description (markdown supported)
reviewers (string[], optional) -- List of reviewer usernames to add
close_source_branch (boolean, optional) -- Delete source branch on merge

get_pr

Get full details for a pull request including title, description, state, author, and reviewers.

Parameters:

pr_id (number, required) -- Pull request ID
workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.

list_prs

List pull requests with optional filters.

Parameters:

workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.
state (string, optional) -- Filter by state: OPEN, MERGED, DECLINED, SUPERSEDED
author (string, optional) -- Filter by author username
limit (number, optional, default 25) -- Maximum results

add_reviewer

Add reviewer(s) / approver(s) to a pull request.

Parameters:

pr_id (number, required) -- Pull request ID
reviewers (string[], required) -- List of usernames to add as reviewers
workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.

approve_pr

Approve a pull request as the authenticated user.

Parameters:

pr_id (number, required) -- Pull request ID
workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.

get_pr_comments

Read all comments on a pull request.

Parameters:

pr_id (number, required) -- Pull request ID
workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.

add_pr_comment

Add a general comment to a pull request.

Parameters:

pr_id (number, required) -- Pull request ID
content (string, required) -- Comment text (markdown supported)
workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.

add_pr_inline_comment

Comment on a specific line of code in the pull request diff.

Parameters:

pr_id (number, required) -- Pull request ID
content (string, required) -- Comment text (markdown supported)
file_path (string, required) -- Path of the file in the diff (e.g. "src/main.py")
line (number, required) -- Line number to comment on
workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.
line_type (string, optional) -- "new" (added lines, default) or "old" (removed lines)

resolve_pr_comment

Resolve or unresolve a comment on a pull request.

Parameters:

pr_id (number, required) -- Pull request ID
comment_id (number, required) -- The ID of the comment to resolve
workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.
resolved (boolean, optional, default true) -- True to resolve, false to unresolve

get_pr_diff

Get the full unified diff for a pull request.

Parameters:

pr_id (number, required) -- Pull request ID
workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.

get_pr_commit_diff

Get the diff for a specific commit in a pull request.

Parameters:

pr_id (number, required) -- Pull request ID
commit_hash (string, required) -- Full or short SHA of the commit
workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.

merge_pr

Merge a pull request.

Parameters:

pr_id (number, required) -- Pull request ID
workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.
merge_strategy (string, optional) -- "merge_commit" (default), "squash", or "fast_forward"
close_source_branch (boolean, optional) -- Delete source branch after merge
message (string, optional) -- Custom merge commit message

decline_pr

Decline (close without merging) a pull request.

Parameters:

pr_id (number, required) -- Pull request ID
workspace (string, optional) -- Cloud workspace slug or Server project key. Uses BITBUCKET_DEFAULT_WORKSPACE if omitted.
repo_slug (string, optional) -- Repository slug. Uses BITBUCKET_DEFAULT_REPO_SLUG if omitted.

Example Prompts

Once connected, you can ask your AI assistant things like:

"Show me all open pull requests in workspace myteam, repo backend-api"
"Get the details and diff of PR #42"
"Create a PR from feature-login to main with title 'Add login page'"
"Add alice and bob as reviewers to PR #15"
"Approve pull request #33"
"Comment on line 42 of src/auth.py in PR #7 saying 'This needs null checking'"
"Resolve the comment with ID 12345 on PR #7"
"Merge PR #10 using squash strategy"

Publishing

Publish to npm

cd typescript
npm login
npm publish

The prepublishOnly script runs tsc automatically before publish. Only the dist/, README.md, and LICENSE files are included in the package.

Publish to PyPI

cd python
pip install hatch
hatch build
hatch publish

Or using twine:

pip install build twine
python -m build
twine upload dist/*

Troubleshooting

"BITBUCKET_CLOUD_USERNAME and BITBUCKET_CLOUD_APP_PASSWORD must be set" Make sure both environment variables are set in your MCP configuration. Check for typos.

"BITBUCKET_SERVER_URL and BITBUCKET_SERVER_TOKEN must be set" Set BITBUCKET_TYPE=server and provide both the URL and token.

API returns 401 / 403 Your credentials are invalid or lack sufficient permissions. For Bitbucket Cloud, ensure your App Password has Repositories: Read/Write and Pull Requests: Read/Write permissions.

Server doesn't appear in Cursor/Claude

Ensure the node/python path is correct
Restart Cursor/Claude Desktop after editing the config
TypeScript: Check that npm run build completed without errors
Python: Check that pip install completed without errors

Comment appears at end of file instead of inline For Bitbucket Cloud, the line_type parameter controls which side of the diff the comment targets. Use "new" for added lines and "old" for removed lines. Do not specify both.

License

MIT

Project details

These details have not been verified by PyPI

Release history Release notifications | RSS feed

This version

1.0.1

Mar 5, 2026

1.0.0

Mar 5, 2026

0.1.0

Mar 5, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bitbucket_llm_bridge-1.0.1.tar.gz (11.3 kB view details)

Uploaded Mar 5, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

bitbucket_llm_bridge-1.0.1-py3-none-any.whl (17.7 kB view details)

Uploaded Mar 5, 2026 Python 3

File details

Details for the file bitbucket_llm_bridge-1.0.1.tar.gz.

File metadata

Download URL: bitbucket_llm_bridge-1.0.1.tar.gz
Upload date: Mar 5, 2026
Size: 11.3 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.10

File hashes

Hashes for bitbucket_llm_bridge-1.0.1.tar.gz
Algorithm	Hash digest
SHA256	`9bab20391c306900098737f3616df3b1fc6c2e88b708b215d1d2512c8e2b7583`
MD5	`09d5dd92231b526b52e52a3b960892be`
BLAKE2b-256	`ee69cc3022b68eecd5ac800405222ca984e2461588a22f316f36d69940a1970f`

See more details on using hashes here.

File details

Details for the file bitbucket_llm_bridge-1.0.1-py3-none-any.whl.

File metadata

Download URL: bitbucket_llm_bridge-1.0.1-py3-none-any.whl
Upload date: Mar 5, 2026
Size: 17.7 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.10

File hashes

Hashes for bitbucket_llm_bridge-1.0.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`020c1aa22c7f4332160fbc2eb7599c1b7000a5dadda81e274f46fac9df1874fc`
MD5	`a9da6580d5cbae6ed5abe078498515fc`
BLAKE2b-256	`50b6f4b7ffbb8c985902416eb75e9e0c3c15699085ba6e418b711e78735475fc`

See more details on using hashes here.

bitbucket-llm-bridge 1.0.1

Navigation

Verified details

Maintainers

Unverified details

Meta

Project description

Bitbucket LLM Bridge

Features

Prerequisites

Configuration

TypeScript

Prerequisites

Installation

Connecting to Cursor

Connecting to Claude Desktop

Development

Project Structure

Python

Prerequisites

Installation

Connecting to Cursor

Connecting to Claude Desktop

Development

Project Structure

Tool Reference

create_pr

get_pr

list_prs

add_reviewer

approve_pr

get_pr_comments

add_pr_comment

add_pr_inline_comment

resolve_pr_comment

get_pr_diff

get_pr_commit_diff

merge_pr

decline_pr

Example Prompts

Publishing

Publish to npm

Publish to PyPI

Troubleshooting

License

Project details

Verified details

Maintainers

Unverified details

Meta

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes