zach-snell/bbkt

A complete command-line interface and Model Context Protocol (MCP) server written in Go that provides programmatic integration with Bitbucket Cloud workspaces and repositories.
Features
- **Dual mode** — Use as an interactive CLI for daily work, or launch as an MCP server (bbkt mcp) for AI agents (Claude Desktop, Cursor, etc.).
- **Git-aware** — Most commands auto-detect the current workspace and repo from .git/config, so bbkt prs list Just Works inside a Bitbucket repo.
- **Multi-profile** — Switch between personal and work Atlassian accounts with --profile or BBKT_PROFILE; auto-selects the right profile based on your git config email.
- **Two auth modes** — Atlassian API tokens (Basic auth) or interactive OAuth 2.0 with automatic token refresh.
- **Scope-aware MCP** — At startup the MCP server introspects your token's granted scopes and silently hides tools the token can't use, preventing the AI from hallucinating successful writes it doesn't have permission for.
- **Read and write** — Repositories, workspaces, pipelines, issues, pull requests, comments, and source code (read/write/delete) — all via the API.
Installation
Recommended — curl | bash
Installs the latest release binary for your OS/arch from GitHub Releases.
Fish users on --user: run fish_add_path ~/.local/bin once if it isn't already on $PATH.
From GitHub Releases
Download a prebuilt binary for your OS/arch directly from the Releases page (Linux/macOS/Windows, amd64 + arm64).
From source
Requires Go 1.26+.
Quickstart
For OAuth instead of an API token:
Authentication
bbkt stores credentials at ~/.config/bbkt/credentials.json and supports multiple profiles.
Atlassian API tokens (default)
> **Important:** Bitbucket Cloud REST API requires *scoped* API tokens since the September 2025 phase-2 of app-password deprecation. At id.atlassian.com/manage-profile/security/api-tokens, use the **"Create API token with scopes"** button — not plain "Create API token". Unscoped tokens authenticate to Atlassian but Bitbucket rejects them; bbkt will detect this and point you here.
Recommended scope set for full read/write:
OAuth 2.0 (browser flow)
Register an OAuth consumer in your Bitbucket workspace settings, then:
bbkt opens a browser, captures the callback on http://localhost:8976, exchanges the code for tokens, and stores them. Access tokens auto-refresh on expiry. To override the callback port (must match your registered redirect_uri):
Multi-profile switching
When BBKT_PROFILE is unset, bbkt tries to auto-select a profile whose accessible workspaces match your git config email; otherwise it falls back to active_profile.
One-shot env-var auth (CI, scripts)
Setting any of these env vars bypasses the stored profile entirely:
CLI Usage
Global flags (all commands): --json raw JSON output, --profile profile override.
Most commands prompt interactively (via huh) when required arguments are missing. Run bbkt --help for full flag details.
MCP Server
bbkt mcp launches a Model Context Protocol server for AI agents. Two transports:
Stdio (default — for Claude Desktop, Cursor, etc.)
Add to your MCP client config:
By default the server reads credentials from ~/.config/bbkt/credentials.json (the profile set up via bbkt auth). To override per-client: