Bitbucket MCP Server

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

TypeScript (Recommended for Smithery)

hljs language-bash

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

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

Python

hljs language-bash

# 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`	✅	Account email for Basic Auth
`BITBUCKET_API_TOKEN`	✅	Repository access token
`API_TIMEOUT`		Request timeout in seconds (default: 30)
`MAX_RETRIES`		Max retry attempts for rate limiting (default: 3)

Claude Code CLI

hljs language-bash

# 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:

hljs language-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 (58 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:

hljs language-python

# 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}
    ]
)

Branches, Commits, Tags

Tool	Description
`list_branches`	List branches
`get_branch`	Get branch details
`list_commits`	List commits
`get_commit`	Get commit details
`compare_commits`	Compare branches
`get_commit_statuses`	Get build statuses
`create_commit_status`	Report CI status
`list_tags`	List tags
`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

hljs language-bash

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

Python

hljs language-bash

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

Creating a Bitbucket API Token

Go to your repository in Bitbucket
Navigate to Repository settings > Access tokens
Click Create Repository Access Token
Select permissions:
- Repository: Read, Write, Admin, Delete
- Pull requests: Read, Write
- Pipelines: Read, Write
Copy the token immediately

Author

Built by Javier Aguilar - AI Agent Architect specializing in multi-agent orchestration and MCP development.

License

MIT

mcp-server-bitbucket

Bitbucket MCP Server

Language Versions

Features

Quick Start

TypeScript (Recommended for Smithery)

Python

Configuration

Environment Variables

Claude Code CLI

Cursor IDE

Available Tools (58 total)

Repositories

Pull Requests

Pipelines

trigger_pipeline Parameters

Branches, Commits, Tags

And more...

MCP Prompts

MCP Resources

Development

TypeScript

Python

Creating a Bitbucket API Token

Author

License

Similar Packages

Repository

Original Author

Publisher

Repository