Bitbucket MCP Server

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

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

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

Available Tools (58 total)

Repositories

Branches & Commits

Tags

Branch Restrictions

Source (File Browsing)

Commit Statuses (CI/CD)

Pull Requests

Pipelines

Pipeline Variables

Deployments

Webhooks

Repository Permissions

Projects

MCP Prompts

Reusable workflow templates that guide Claude through common tasks:

MCP Resources

Browsable workspace data as markdown:

Example Usage

Once configured, ask Claude to:

Repositories & Branches:

• "List all repositories in my workspace"

• "Search for repositories with 'api' in the name"

• "Show me the last 10 commits on the main branch"

• "Compare develop branch with main"

Pull Requests & Code Review:

• "Show me open pull requests in my-repo"

• "Create a PR from feature-branch to main"

• "Approve PR #42"

• "Add a comment to PR #15 saying 'Looks good!'"

• "Show me the diff for PR #42"

• "Merge PR #42 using squash strategy"

Pipelines & CI/CD:

• "Trigger a pipeline on the develop branch"

• "What's the status of the latest pipeline?"

• "Get the build status for commit abc123"

Deployments:

• "List deployment environments for my-repo"

• "Show deployment history for production"

Webhooks:

• "List webhooks configured for my-repo"

• "Create a webhook for push events"

Tags:

• "List all tags in my-repo"

• "Create a tag v1.0.0 on the main branch"

• "Delete the old-release tag"

Branch Protection:

• "List branch restrictions for my-repo"

• "Require 2 approvals to merge to main"

• "Prevent force push to production branches"

Source Browsing:

• "Show me the contents of src/main.py"

• "List files in the root directory"

• "Read the README.md from the develop branch"

Repository Permissions:

• "List user permissions for my-repo"

• "Give user@example.com write access to my-repo"

• "List group permissions for my-repo"

• "Grant admin access to the DevOps group"

Repository Search

The list_repositories tool supports flexible searching:

Query syntax supports: name ~ "term", is_private = true/false, AND, OR

Installation Options

From PyPI (Recommended)

Updating

From Source

Configuration

Claude Code CLI (Recommended)

Output Format (Optional)

Set OUTPUT_FORMAT to optimize token usage:

Cursor IDE

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

Claude Desktop / Manual Configuration

Add to ~/.claude.json:

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

See the full installation guide for detailed instructions.

HTTP Server (Remote Deployment)

Deploy the MCP server as an HTTP service for remote access from any MCP client. Uses the standard MCP Streamable HTTP transport protocol.

Running Locally

Deploy to Cloud Run (Google Cloud)

Deploy to Railway/Render/Fly.io

Set these environment variables in your platform:

• BITBUCKET_WORKSPACE: Your Bitbucket workspace slug

• BITBUCKET_EMAIL: Your Bitbucket account email

• BITBUCKET_API_TOKEN: Your repository access token

• PORT: (usually auto-set by platform)

Docker Deployment

Connecting Claude Code to Remote Server

Once deployed, connect Claude Code to your remote MCP server:

Manual Configuration for Remote Server

Add to ~/.claude.json:

Development

Requirements

• Python 3.11+

• uv for dependency management

• PyPI account for publishing

Setup

Running Locally

CI/CD Pipeline

The project uses GitHub Actions for automated testing and publishing:

• Every push to main: Runs tests with coverage

• Pull requests: Runs full test suite

• Tags (: Tests, builds, and publishes to PyPI

To release a new version:

Manual Publishing

If you need to publish manually:

1. Get a PyPI API Token:

   • Go to https://pypi.org/manage/account/token/

   • Create a token with scope "Entire account" (first time) or project-specific

   • Set environment variable: export UV_PUBLISH_TOKEN=pypi-YOUR_TOKEN

2. Build and publish:

   uv build uv publish

Links

• PyPI Package

• Installation Guide

• GitHub Repository

License

MIT