Skip to main content

Bitbucket MCP Server

CI/CD PyPI version npm version License: MIT

MCP server for Bitbucket API operations. Works with Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.

Language Versions

This repository contains both TypeScript and Python implementations:

Version Directory Status Installation
TypeScript /typescript ✅ Recommended (Smithery) npm install -g mcp-server-bitbucket
Python /python ✅ Stable pipx install mcp-server-bitbucket

Note: The TypeScript version is used for Smithery deployments. Both versions provide identical functionality.

Features

  • Repositories: get, create, delete, list, update (move to project, rename)
  • Pull Requests: create, get, list, merge, approve, decline, request changes, comments, diff
  • Pipelines: trigger, get status, list, view logs, stop
  • Branches: list, get
  • Projects: list, get
  • Commits: list, get details, compare/diff between branches
  • Commit Statuses: get build statuses, create status (CI/CD integration)
  • Deployments: list environments, get environment details, deployment history
  • Webhooks: list, create, get, delete
  • Tags: list, create, delete
  • Branch Restrictions: list, create, delete branch protection rules
  • Source Browsing: read files, list directories without cloning
  • Repository Permissions: manage user and group permissions
  • Pipeline Variables: manage CI/CD environment variables
  • MCP Prompts: reusable workflow templates (code review, release notes, etc.)
  • MCP Resources: browsable workspace data

Quick Start

# Install globally
npm install -g mcp-server-bitbucket

# Or run directly with npx
npx mcp-server-bitbucket

Python

# Install with pipx
pipx install mcp-server-bitbucket

# Configure Claude Code
claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e BITBUCKET_EMAIL=your-email@example.com \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- mcp-server-bitbucket

Full Installation Guide - Includes API token creation, permissions setup, and troubleshooting.

Configuration

Environment Variables

Variable Required Description
BITBUCKET_WORKSPACE ✅ Bitbucket workspace slug
BITBUCKET_EMAIL ✅ (basic auth) Account email for Basic Auth
BITBUCKET_API_TOKEN ✅ Atlassian API token (Basic auth)
BITBUCKET_OAUTH_TOKEN Access token sent as Authorization: Bearer
BITBUCKET_AUTH_TYPE Force auth mode: basic or bearer (auto-detected)
API_TIMEOUT Request timeout in seconds (default: 30)
MAX_RETRIES Max retry attempts for rate limiting (default: 3)

Claude Code CLI

# TypeScript version
claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e BITBUCKET_EMAIL=your-email@example.com \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- npx mcp-server-bitbucket

# Python version
claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e BITBUCKET_EMAIL=your-email@example.com \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- mcp-server-bitbucket

Cursor IDE

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["mcp-server-bitbucket"],
      "env": {
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_EMAIL": "your-email@example.com",
        "BITBUCKET_API_TOKEN": "your-api-token"
      }
    }
  }
}

Available Tools (62 total)

Repositories

Tool Description
list_repositories List and search repositories
get_repository Get repository details
create_repository Create a new repository
delete_repository Delete a repository
update_repository Update repo settings

Pull Requests

Tool Description
list_pull_requests List PRs
get_pull_request Get PR details
create_pull_request Create a new PR
merge_pull_request Merge a PR
approve_pr Approve a PR
unapprove_pr Remove approval
request_changes_pr Request changes
decline_pr Decline a PR
list_pr_comments List comments
add_pr_comment Add comment
get_pr_diff Get the diff

Pipelines

Tool Description
list_pipelines List recent runs
get_pipeline Get status
get_pipeline_logs View logs
trigger_pipeline Trigger a run (supports custom pipelines and commit triggers)
stop_pipeline Stop pipeline
list_pipeline_variables List variables
get_pipeline_variable Get variable
create_pipeline_variable Create variable
update_pipeline_variable Update variable
delete_pipeline_variable Delete variable

trigger_pipeline Parameters

Parameter Type Description
repo_slug string Repository slug (required)
branch string Branch to run on (default: main). Mutually exclusive with commit
commit string Commit hash to run on. Mutually exclusive with branch
custom_pipeline string Name from custom: section in bitbucket-pipelines.yml
variables array Variables as [{key, value, secured?}]

Examples:

# Default pipeline on main
trigger_pipeline(repo_slug="my-repo")

# Custom pipeline
trigger_pipeline(repo_slug="my-repo", custom_pipeline="deploy-staging")

# Custom pipeline on specific commit with variables
trigger_pipeline(
    repo_slug="my-repo",
    commit="abc123def",
    custom_pipeline="deploy-prod",
    variables=[
        {"key": "ENV", "value": "production"},
        {"key": "SECRET", "value": "xxx", "secured": True}
    ]
)

See history queries, pagination and retry behavior.

Branches, Commits, Tags

Tool Description
list_branches List branches
get_branch Get branch details
list_commits Paginated history with revision include/exclude and path filters
get_commit Get commit details
compare_commits Paginated changed-file statistics from base to head
get_commit_diff Raw diff, optionally by file, with explicit chunk continuation
get_merge_base Best common ancestor of two revisions
get_file_history Paginated file history with paths reported across renames
get_commit_statuses Get build statuses
create_commit_status Report CI status
list_tags Paginated tags with filtering and configurable sorting
get_tag Resolve an exact tag to its full target commit hash
create_tag Create a tag
delete_tag Delete a tag

And more...

  • Deployments: list_environments, get_environment, list_deployment_history
  • Webhooks: list_webhooks, create_webhook, get_webhook, delete_webhook
  • Branch Restrictions: list_branch_restrictions, create_branch_restriction, delete_branch_restriction
  • Source Browsing: get_file_content, list_directory
  • Permissions: User and group permission management (8 tools)
  • Projects: list_projects, get_project

MCP Prompts

Reusable workflow templates:

Prompt Description
code_review Comprehensive PR code review
release_notes Generate changelog between versions
pipeline_debug Debug failed CI/CD pipelines
repo_summary Complete repository status overview

MCP Resources

Browsable workspace data:

Resource URI Description
bitbucket://repositories List all repos
bitbucket://repositories/{repo} Repository details
bitbucket://repositories/{repo}/branches Branch list
bitbucket://repositories/{repo}/pull-requests Open PRs
bitbucket://projects List all projects

Development

TypeScript

cd typescript
npm install
npm run build
npm run dev  # Watch mode

Python

cd python
uv sync
uv run python -m src.server

Creating a Bitbucket API Token

  1. Go to your repository in Bitbucket
  2. Navigate to Repository settings > Access tokens
  3. Click Create Repository Access Token
  4. Select permissions:
    • Repository: Read, Write, Admin, Delete
    • Pull requests: Read, Write
    • Pipelines: Read, Write
  5. Copy the token immediately

License

MIT

Metadata

Release files for mcp-server-bitbucket 0.13.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-server-bitbucket 0.13.1
File Size Uploaded Provenance Actions
mcp_server_bitbucket-0.13.1.tar.gz 129.7 kB With provenance Details for mcp_server_bitbucket-0.13.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-server-bitbucket 0.13.1
File Interpreter ABI Platform Actions
mcp_server_bitbucket-0.13.1-py3-none-any.whl Python 3 none any Details for mcp_server_bitbucket-0.13.1-py3-none-any.whl

Total release size: 167.3 kB

Release files / mcp_server_bitbucket-0.13.1.tar.gz

Download URL mcp_server_bitbucket-0.13.1.tar.gz
Size 129.7 kB
Tags Source
SHA-256 checksum
How to use checksums
23119f86e8cd04fe062508a6cf42610ec94df3a48959dadb76fd348a3c1c830a
BLAKE2b-256 checksum
How to use checksums
81d627cd0dc837f827c5565be2dac1cfb22507cc86748cc4b332356191fc4fa4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / mcp_server_bitbucket-0.13.1-py3-none-any.whl

Download URL mcp_server_bitbucket-0.13.1-py3-none-any.whl
Size 37.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
31f1ccbf77d251c8a60688a8a92d749f5e8a336ab252b554fe0d5b77747c0951
BLAKE2b-256 checksum
How to use checksums
0fb6448d900fee366e99b076914eef740241a87848b67a17c2a75269ec093f2a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for mcp-server-bitbucket 0.13.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mcp_server_bitbucket-0.13.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page