mcp-server-bitbucket 0.5.0

MCP server for Bitbucket API operations

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

Quick Start

# Install
pipx install mcp-server-bitbucket

# Configure Claude Code
claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e BITBUCKET_EMAIL=[e-mail] \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- mcp-server-bitbucket

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

Available Tools (54 total)

Repositories

Tool	Description
list_repositories	List and search repositories (supports fuzzy name matching)
get_repository	Get repository details
create_repository	Create a new repository
delete_repository	Delete a repository
update_repository	Update repo settings (project, visibility, description, name)

Branches & Commits

Tool	Description
list_branches	List branches in a repo
get_branch	Get branch details
list_commits	List commits (filter by branch or file path)
get_commit	Get commit details
compare_commits	Compare two commits/branches (diff stats)

Tags

Tool	Description
list_tags	List tags in a repo
create_tag	Create a new tag
delete_tag	Delete a tag

Branch Restrictions

Tool	Description
list_branch_restrictions	List branch protection rules
create_branch_restriction	Create branch protection rule
delete_branch_restriction	Delete branch protection rule

Source (File Browsing)

Tool	Description
get_file_content	Read file contents without cloning
list_directory	List directory contents

Commit Statuses (CI/CD)

Tool	Description
get_commit_statuses	Get build/CI statuses for a commit
create_commit_status	Report build status from external CI

Pull Requests

Tool	Description
list_pull_requests	List PRs (open, merged, etc.)
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 from a PR
request_changes_pr	Request changes on a PR
decline_pr	Decline (close) a PR
list_pr_comments	List comments on a PR
add_pr_comment	Add comment to a PR (general or inline)
get_pr_diff	Get the diff of a PR

Pipelines

Tool	Description
list_pipelines	List recent pipeline runs
get_pipeline	Get pipeline status
get_pipeline_logs	View pipeline logs
trigger_pipeline	Trigger a pipeline run
stop_pipeline	Stop a running pipeline

Deployments

Tool	Description
list_environments	List deployment environments (test, staging, prod)
get_environment	Get environment details
list_deployment_history	Get deployment history for an environment

Webhooks

Tool	Description
list_webhooks	List configured webhooks
create_webhook	Create a new webhook
get_webhook	Get webhook details
delete_webhook	Delete a webhook

Repository Permissions

Tool	Description
list_user_permissions	List user permissions for a repo
get_user_permission	Get specific user's permission
update_user_permission	Add/update user permission
delete_user_permission	Remove user permission
list_group_permissions	List group permissions for a repo
get_group_permission	Get specific group's permission
update_group_permission	Add/update group permission
delete_group_permission	Remove group permission

Projects

Tool	Description
list_projects	List projects in workspace
get_project	Get project details

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 [e-mail] 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:

# Simple fuzzy search by name
list_repositories(search="api")  # Finds repos with "api" in name

# Advanced Bitbucket query syntax
list_repositories(query='name ~ "test" AND is_private = true')

# Filter by project
list_repositories(project_key="MYPROJECT")

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

Installation Options

From PyPI (Recommended)

pipx install mcp-server-bitbucket
# or
pip install mcp-server-bitbucket

Updating

# Upgrade to latest version
pipx upgrade mcp-server-bitbucket

# If upgrade doesn't pick up the new version, reinstall:
pipx uninstall mcp-server-bitbucket
pipx install mcp-server-bitbucket

From Source

git clone [e-mail]:simplekyc/bitbucket-mcp.git
cd bitbucket-mcp
poetry install

Configuration

Claude Code CLI (Recommended)

claude mcp add bitbucket -s user \
  -e BITBUCKET_WORKSPACE=your-workspace \
  -e BITBUCKET_EMAIL=[e-mail] \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -- mcp-server-bitbucket

Manual Configuration

Add to ~/.claude.json:

{
  "mcpServers": {
    "bitbucket": {
      "command": "mcp-server-bitbucket",
      "env": {
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_EMAIL": "[e-mail]",
        "BITBUCKET_API_TOKEN": "your-api-token"
      }
    }
  }
}

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 (Cloud Run)

For deploying as an HTTP API:

# Run locally
poetry run uvicorn src.http_server:app --reload --port 8080

# Deploy to Cloud Run
gcloud run deploy bitbucket-mcp-service \
  --source . \
  --region australia-southeast1 \
  --set-secrets "BITBUCKET_EMAIL=bitbucket-email:latest,BITBUCKET_API_TOKEN=bitbucket-token:latest"

Development

Requirements

• Python 3.11+
• Poetry for dependency management
• PyPI account for publishing

Setup

git clone [e-mail]:simplekyc/bitbucket-mcp.git
cd bitbucket-mcp
poetry install

Running Locally

# MCP server (stdio mode)
poetry run python -m src.server

# HTTP server
poetry run uvicorn src.http_server:app --reload --port 8080

Publishing to PyPI

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
   • Configure Poetry: poetry config pypi-token.pypi pypi-YOUR_TOKEN

2. Bump version in pyproject.toml

3. Build and publish:

   poetry build
   poetry publish
   

4. Tag the release:

   git tag v0.x.x
   git push origin v0.x.x
   

Links

• PyPI Package
• Installation Guide
• Bitbucket Repository

License

MIT