Summary
Auto-generated from Bitbucket Cloud's OpenAPI spec, this server gives Claude the full Bitbucket API surface through tool calls. You get repo management, pull requests, pipelines, branch restrictions, and everything else in the spec without waiting for manual endpoint additions. It's built in Go, ships as a container, and uses the same code generation pipeline that powers a CLI and Terraform provider. Reach for this when you want Claude to handle Bitbucket operations directly instead of you writing scripts or clicking through the UI. The prompts are customizable, and because it regenerates from the live spec, new Bitbucket features flow in automatically.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
17 tools
BITBUCKET_CREATE_BRANCHCreates a new branch in a Bitbucket repository from a target commit hash; the branch name must be unique, adhere to Bitbucket's naming conventions, and not include the 'refs/heads/' prefix.4 params
Creates a new branch in a Bitbucket repository from a target commit hash; the branch name must be unique, adhere to Bitbucket's naming conventions, and not include the 'refs/heads/' prefix.
Parameters* required
namestringThe name for the new branch (e.g., 'feature/new-login', 'bugfix/issue-123'). Important: Do not include the 'refs/heads/' prefix.
repo_slugstringThe slug or UUID of the repository where the branch will be created. This is usually the repository's name in URL-friendly format.
workspacestringThe workspace ID or UUID that owns the repository. This can typically be found in the URL of your Bitbucket workspace.
target_hashstringThe full commit hash (SHA1) from which the new branch will be created. This commit must exist in the repository.
BITBUCKET_CREATE_ISSUECreates a new issue in a Bitbucket repository, setting the authenticated user as reporter; ensures assignee (if provided) has repository access, and that any specified milestone, version, or component IDs exist.11 params
Creates a new issue in a Bitbucket repository, setting the authenticated user as reporter; ensures assignee (if provided) has repository access, and that any specified milestone, version, or component IDs exist.
Parameters* required
kindstringType of the issue (e.g., 'bug', 'enhancement', 'proposal', 'task').
titlestringTitle for the new issue.
due_onstringDue date for the issue in ISO 8601 format (e.g., 'YYYY-MM-DDTHH:mm:ssZ').
contentstringDetailed description for the new issue.
assigneestringBitbucket username of the assignee. The assignee must have repository access.
prioritystringPriority level of the issue (e.g., 'trivial', 'minor', 'major', 'critical', 'blocker').
repo_slugstringThe slug of the Bitbucket repository.
workspacestringThe ID or slug of the Bitbucket workspace.
version_idintegerNumeric ID of an existing version to associate with this issue.
component_idintegerNumeric ID of an existing component to associate with this issue.
milestone_idintegerNumeric ID of an existing milestone to associate with this issue.
BITBUCKET_CREATE_ISSUE_COMMENTAdds a new comment with markdown support to an existing Bitbucket issue.4 params
Adds a new comment with markdown support to an existing Bitbucket issue.
Parameters* required
contentstringThe raw text content for the comment. This content supports markdown formatting, which Bitbucket will then render.
issue_idstringThe unique identifier of the issue on which the comment will be posted.
repo_slugstringThe slug (URL-friendly version) of the repository name.
workspacestringThe ID or slug of the workspace or user that owns the repository.
BITBUCKET_CREATE_PULL_REQUESTCreates a new pull request in a specified Bitbucket repository, ensuring the source branch exists and is distinct from the (optional) destination branch.8 params
Creates a new pull request in a specified Bitbucket repository, ensuring the source branch exists and is distinct from the (optional) destination branch.
Parameters* required
titlestringConcise title summarizing the changes for the pull request.
repo_slugstringSlug (URL-friendly name) of the repository for the pull request.
reviewersarrayList of Bitbucket user UUIDs to be added as reviewers.
workspacestringWorkspace ID (UUID or slug) of the repository owner.
descriptionstringDetailed Markdown description of the pull request, outlining changes and purpose.
source_branchstringName of the source branch with changes to be merged.
destination_branchstringName of the destination branch for merging; defaults to repository's main branch if unspecified.
close_source_branchbooleanIf true, automatically closes the source branch upon pull request merge.default: false
BITBUCKET_CREATE_REPOSITORYCreates a new Bitbucket 'git' repository in a specified workspace, defaulting to the workspace's oldest project if `project_key` is not provided.9 params
Creates a new Bitbucket 'git' repository in a specified workspace, defaulting to the workspace's oldest project if `project_key` is not provided.
Parameters* required
has_wikibooleanEnable the wiki (`True`), or disable it (`False`).default: true
languagestringPrimary programming language (e.g., 'python', 'java') for categorization.
repo_slugstringURL-friendly slug for the new repository.
workspacestringID or slug of the Bitbucket workspace for the new repository.
has_issuesbooleanEnable the issue tracker (`True`), or disable it (`False`).default: true
is_privatebooleanRepository visibility: `True` for private, `False` for public.default: true
descriptionstringDescription for the new repository.
fork_policystringForking policy for the repository, determining who can create forks.one of
allow_forks · no_public_forks · no_forksdefault: allow_forksproject_keystringKey of the Bitbucket project for the repository; if omitted, it's placed in the workspace's oldest project.
BITBUCKET_CREATE_SNIPPET_COMMENTPosts a new top-level comment or a threaded reply to an existing comment on a specified Bitbucket snippet.4 params
Posts a new top-level comment or a threaded reply to an existing comment on a specified Bitbucket snippet.
Parameters* required
contentstringRaw text content of the comment; Bitbucket will render any included markup (like Markdown).
parent_idintegerID of an existing comment to reply to, creating a threaded comment; if omitted, a top-level comment is created.
workspacestringWorkspace ID or slug (e.g., 'my_workspace_slug' or a UUID) for the Bitbucket workspace containing the snippet.
encoded_idstringUnique, encoded ID of the Bitbucket snippet to comment on (typically part of the snippet's URL).
BITBUCKET_DELETE_ISSUEPermanently deletes a specific issue, identified by its `issue_id`, from the repository specified by `repo_slug` within the given `workspace`.3 params
Permanently deletes a specific issue, identified by its `issue_id`, from the repository specified by `repo_slug` within the given `workspace`.
Parameters* required
issue_idstringThe unique identifier of the issue to be deleted from the specified repository.
repo_slugstringThe slug of the repository. This is the repository's name, usually in lowercase and with hyphens instead of spaces.
workspacestringThe workspace ID (slug) or UUID of the Bitbucket workspace that owns the repository. This can be the workspace name or its universally unique identifier.
BITBUCKET_DELETE_REPOSITORYPermanently deletes a specified Bitbucket repository; this action is irreversible and does not affect forks.2 params
Permanently deletes a specified Bitbucket repository; this action is irreversible and does not affect forks.
Parameters* required
repo_slugstringThe slug (URL-friendly name) of the repository to be deleted. This identifies the repository within the workspace.
workspacestringThe ID or slug of the Bitbucket workspace that owns the repository. This can be a user's username or a team's slug.
BITBUCKET_GET_CURRENT_USERRetrieves the profile information (UUID, display name, links, creation date) for the currently authenticated Bitbucket user.
Retrieves the profile information (UUID, display name, links, creation date) for the currently authenticated Bitbucket user.
No parameter schema in public metadata yet.
BITBUCKET_GET_FILE_FROM_REPOSITORYRetrieves a specific file's content from a Bitbucket repository at a given commit (hash, branch, or tag), failing if the file path is invalid for that commit.4 params
Retrieves a specific file's content from a Bitbucket repository at a given commit (hash, branch, or tag), failing if the file path is invalid for that commit.
Parameters* required
pathstringFull path to the file within the repository (e.g., 'src/main.py').
commitstringCommit hash, branch name (fetches latest), or tag for the file version.
repo_slugstringRepository slug or UUID (typically URL-formatted name).
workspacestringWorkspace ID or UUID (often username or team name) containing the repository.
BITBUCKET_GET_PULL_REQUESTGet a single pull request by ID with complete details.3 params
Get a single pull request by ID with complete details.
Parameters* required
repo_slugstringRepository slug (URL-friendly name).
workspacestringWorkspace ID or slug (URL-friendly name).
pull_request_idintegerThe ID of the pull request to retrieve.
BITBUCKET_GET_SNIPPETRetrieves a specific Bitbucket snippet by its encoded ID from an existing workspace, returning its metadata and file structure.3 params
Retrieves a specific Bitbucket snippet by its encoded ID from an existing workspace, returning its metadata and file structure.
Parameters* required
workspacestringThe workspace ID (slug) or the workspace UUID surrounded by curly braces, identifying the Bitbucket workspace.
encoded_idstringThe unique identifier (encoded ID) of the snippet to be retrieved.
accept_formatstringThe desired format for the response. Valid options are 'application/json', 'multipart/related', or 'multipart/form-data'. This may affect how snippet content or file data is presented.default: application/json
BITBUCKET_LIST_PULL_REQUESTSLists pull requests in a specified, accessible Bitbucket repository, optionally filtering by state (OPEN, MERGED, DECLINED).5 params
Lists pull requests in a specified, accessible Bitbucket repository, optionally filtering by state (OPEN, MERGED, DECLINED).
Parameters* required
pageintegerPage number for paginated results (starts from 1).
statestringLifecycle state of a pull request.one of
OPEN · MERGED · DECLINEDpagelenintegerNumber of pull requests per page (1-100). Bitbucket default if not specified.
repo_slugstringRepository slug (URL-friendly name).
workspacestringWorkspace ID or slug (URL-friendly name).
BITBUCKET_LIST_REPOSITORIES_IN_WORKSPACELists repositories in a specified Bitbucket workspace, accessible to the authenticated user, with options to filter by role or query string, and sort results.4 params
Lists repositories in a specified Bitbucket workspace, accessible to the authenticated user, with options to filter by role or query string, and sort results.
Parameters* required
qstringQuery string using Bitbucket's REST API filtering syntax to filter repositories. For detailed syntax, refer to Bitbucket API documentation.
rolestringFilters repositories by the authenticated user's role within each repository.
sortstringField for sorting repository results. Prefix with '-' for descending order. Common sortable fields: 'name', 'updated_on', 'created_on'.
workspacestringThe identifier of the Bitbucket workspace. This can be the workspace slug (e.g., 'my-workspace') or its UUID enclosed in curly braces (e.g., '{workspace-uuid}').
BITBUCKET_LIST_WORKSPACE_MEMBERSLists all members of a specified Bitbucket workspace; the workspace must exist.1 params
Lists all members of a specified Bitbucket workspace; the workspace must exist.
Parameters* required
workspacestringThe workspace ID (UUID) or slug from which to list members. The slug is the user-friendly, URL-safe identifier for the workspace.
BITBUCKET_LIST_WORKSPACESLists Bitbucket workspaces accessible to the authenticated user, optionally filtered and sorted.2 params
Lists Bitbucket workspaces accessible to the authenticated user, optionally filtered and sorted.
Parameters* required
qstringQuery string to filter workspaces by attributes, following Bitbucket's filtering syntax.
sortstringField to sort returned workspaces by; prefix with a hyphen (-) for descending order.
BITBUCKET_UPDATE_ISSUEUpdates an existing issue in a Bitbucket repository by modifying specified attributes; requires `workspace`, `repo_slug`, `issue_id`, and at least one attribute to update.12 params
Updates an existing issue in a Bitbucket repository by modifying specified attributes; requires `workspace`, `repo_slug`, `issue_id`, and at least one attribute to update.
Parameters* required
kindstringThe updated kind (type) for the issue. If omitted, kind remains unchanged.
statestringThe updated state for the issue. If omitted, state remains unchanged.
titlestringThe new title for the issue. If omitted, the title remains unchanged.
contentstringThe new content or description for the issue, in raw text format. If omitted, the content remains unchanged.
versionstringThe name of the version affected by this issue (e.g., '1.0.0', '2.0-beta'). If omitted, the version remains unchanged.
issue_idstringThe unique identifier (ID) of the issue to be updated.
prioritystringThe updated priority for the issue. If omitted, priority remains unchanged.
componentstringThe name of the component to associate with the issue (e.g., 'API', 'Frontend'). If omitted, the component remains unchanged.
milestonestringThe name of the milestone to associate with the issue (e.g., 'Sprint 1', 'v1.0 Launch'). If omitted, the milestone remains unchanged.
repo_slugstringThe slug or name of the repository (e.g., 'my-app-repo').
workspacestringThe workspace ID or slug that owns the repository (e.g., 'my-company' or '{123e4567-e89b-12d3-a456-426614174000}').
assignee_account_idstringThe Bitbucket account ID (UUID) of the user to assign the issue to. If omitted, the assignee remains unchanged.
bitbucket-cli
Low-maintenance Bitbucket Cloud tooling built from the live OpenAPI spec: a CLI for software engineers, an MCP server for AI agents, and a Terraform provider for DevSecOps teams.
[!IMPORTANT]
https://github.com/FabianSchurig/bitbucket-cliis the canonical repository. If you found this project through theterraform-provider-bitbucketmirror, watch, star, file issues, and contribute inbitbucket-cli.
Start here
| Audience | Best fit | Start here |
|---|---|---|
| DevSecOps engineers | Terraform provider | Terraform Registry, generated provider docs, example: bitbucket_tags |
| Software engineers / computer scientists | bb-cli | CLI usage guide |
| AI agents / agent platform users | bb-mcp | MCP usage guide |
Quick links
- Canonical GitHub repository
- Terraform Registry:
FabianSchurig/bitbucket - Mirror repository:
terraform-provider-bitbucket - GitHub Releases
- SonarQube Cloud
- Contributing guide
Install
Homebrew (macOS and Linux)
brew tap FabianSchurig/tap
brew install bitbucket-cli
APT (Debian / Ubuntu)
Download the .deb package from the latest release and install it. Supported architectures: amd64, arm64.
TAG_URL=$(curl -fsSIL -o /dev/null -w '%{url_effective}' https://github.com/FabianSchurig/bitbucket-cli/releases/latest)
VERSION=${TAG_URL##*/}
VERSION=${VERSION%%\?*}
VERSION=${VERSION%%\#*}
VERSION=${VERSION#v}
ARCH=$(dpkg --print-architecture)
curl -LO "https://github.com/FabianSchurig/bitbucket-cli/releases/download/v${VERSION}/bb-cli_${VERSION}_${ARCH}.deb"
sudo dpkg -i "bb-cli_${VERSION}_${ARCH}.deb"
Replace bb-cli with bb-mcp to install the MCP server instead.
RPM (Fedora / RHEL / CentOS)
Download the .rpm package from the latest release and install it. Supported architectures: amd64, arm64.
TAG_URL=$(curl -fsSIL -o /dev/null -w '%{url_effective}' https://github.com/FabianSchurig/bitbucket-cli/releases/latest)
VERSION=${TAG_URL##*/}
VERSION=${VERSION%%\?*}
VERSION=${VERSION%%\#*}
VERSION=${VERSION#v}
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -LO "https://github.com/FabianSchurig/bitbucket-cli/releases/download/v${VERSION}/bb-cli_${VERSION}_${ARCH}.rpm"
sudo rpm -i "bb-cli_${VERSION}_${ARCH}.rpm"
Replace bb-cli with bb-mcp to install the MCP server instead.
Scoop (Windows)
scoop bucket add bitbucket https://github.com/FabianSchurig/scoop-bucket
scoop install bb-cli
scoop install bb-mcp
Winget (Windows)
winget install FabianSchurig.bb-cli
winget install FabianSchurig.bb-mcp
Install script
curl -fsSL https://raw.githubusercontent.com/FabianSchurig/bitbucket-cli/main/install.sh | sh
See install.sh options for version selection, binary choice (bb-cli, bb-mcp, or all), and custom install directories.
Other methods
| Method | Command |
|---|---|
| Go install | go install github.com/FabianSchurig/bitbucket-cli/cmd/bb-cli@latest |
| Docker | docker pull ghcr.io/fabianschurig/bitbucket-cli:latest |
| Download binaries | GitHub Releases |
For full installation details see the CLI usage guide and the MCP usage guide.
What this project is
This repository keeps Bitbucket Cloud tooling maintainable by generating most of the surface area from the live Bitbucket OpenAPI spec.
- One API description, three user-facing tools: CLI, MCP, and Terraform all come from the same schema pipeline.
- Thin hand-written runtime: auth, dispatch, output, and Terraform runtime stay generic instead of growing per-endpoint glue.
- Fast spec adoption: new Bitbucket endpoints flow in through generation instead of large manual rewrites.
- Maintenance-first design: the main development effort goes into the shared generators and runtime, not duplicated endpoint code.
- Internal/undocumented endpoints supported the same way: schemas under
schema/can be hand-authored for endpoints that are not in Bitbucket's public OpenAPI spec (for example the project-level branch-restrictions endpoint exposed only viahttps://bitbucket.org/!api/internal/...). The generators and runtime treat them identically — schema paths may use absolute URLs and the dispatcher passes them through unchanged.
Architecture
flowchart LR
A[Live Bitbucket OpenAPI spec] --> B[enrich_spec.py]
B --> C[partition_spec.py]
C --> D[schema/*-schema.yaml]
D --> E[oapi-codegen models]
D --> F[CLI generator]
D --> G[MCP generator]
D --> H[Terraform generator]
E --> I[Shared generated types]
F --> J[bb-cli]
G --> K[bb-mcp]
H --> L[terraform-provider-bitbucket]
I --> J
I --> K
I --> L
M[Hand-written runtime\nauth, dispatch, output, MCP handler, TF runtime] --> J
M --> K
M --> L
In practice:
- CLI exposes Bitbucket operations as terminal commands.
- MCP exposes the same operations as tool calls for AI agents.
- Terraform maps operation groups into generic resources and data sources.
- Hand-written code stays small on purpose; generated code handles endpoint coverage.
CI pipelines
flowchart TD
A[push / pull_request] --> B[ci.yml]
A --> C[terraform-tests.yml]
D[schedule / manual] --> E[schema-sync.yml]
E --> F[Fetch live spec]
F --> G[Regenerate code and docs]
G --> H[Build and test]
H --> I[Tag new version]
I --> J[release.yml]
J --> K[docker.yml]
I --> L[terraform-release.yml]
K --> M[Publish to MCP Registry]
ci.yml: builds, lints, vets, runs Go tests, and sends analysis to SonarQube Cloud.terraform-tests.yml: runs mock-based Terraform acceptance andterraform testsuites, plus real API tests when credentials exist. See docs/e2e-coverage.md for the current list of endpoints exercised by the real-API tests.schema-sync.yml: daily/manual sync that fetches the live Bitbucket spec, regenerates generated artifacts, rebuilds docs, tests everything, and tags a release when the schema changed.release.yml: publishes tagged binary releases via GoReleaser.docker.yml: builds multi-arch container images forbb-cliandbb-mcp, pushes them to GHCR, and publishes thebb-mcpserver to the MCP Registry.terraform-release.yml: mirrors the tagged source intoterraform-provider-bitbucketand publishes the Terraform provider release.
How this differs from DrFaust92/terraform-provider-bitbucket
| Aspect | DrFaust92/terraform-provider-bitbucket | FabianSchurig/bitbucket |
|---|---|---|
| Maintenance model | Hand-written provider resources | Mostly generated from the live Bitbucket OpenAPI spec |
| Scope | Terraform provider only | Terraform provider + CLI + MCP server in one canonical repo |
| API coverage model | Curated, typed resources | Broad endpoint coverage through grouped generic resources/data sources |
| Update flow | Manual feature work per resource | Schema sync pipeline regenerates code and docs |
| Resource shape | Resource-specific typed fields | Generic params, response fields, and raw API response |
| Best fit | Opinionated Terraform workflows | Teams that want fast Bitbucket API coverage and shared tooling across Terraform, shells, and AI agents |
This project optimizes for breadth, maintenance, and shared infrastructure across interfaces. If you want a heavily hand-modeled Terraform UX, the DrFaust92 provider may feel more familiar. If you want one maintained pipeline that keeps Terraform, CLI, and MCP aligned with Bitbucket Cloud, this repository is designed for that.
Documentation map
Use the short guides on this first page to get started, then switch to the detailed docs for the interface you need.
- CLI: docs/cli.md
- MCP: docs/mcp.md
- Terraform provider docs: docs/index.md and the Terraform Registry docs
- Real-API E2E test coverage: docs/e2e-coverage.md — auto-generated list of which resource groups are exercised by
TestAccRealAPI_*tests, and which are still missing coverage.
The Terraform documentation under docs/ is generated. The root README stays focused on orientation, links, architecture, maintenance, and contribution entry points.
Maintenance and contributions
- Read CONTRIBUTING.md before changing generators or runtime code.
- Do not hand-edit generated files; fix the generator or schema source instead.
- Prefer changes that improve the shared pipeline or hand-written runtime across all endpoints.
- Open issues and pull requests in the canonical
bitbucket-clirepository.
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
BITBUCKET_USERNAMEYour Bitbucket username/ email (required for Basic auth, omit for workspace/repo access tokens)
BITBUCKET_TOKEN*secretYour Bitbucket API token or OAuth2 access token
Categories
Registryactive
Packageghcr.io/fabianschurig/bitbucket-mcp:0.16.2
TransportSTDIO
AuthRequired
UpdatedMay 26, 2026
