Bitbucket Data Center / Server

Overview

C3 ships with c3_bitbucket — a single MCP tool that lets Claude Code (and the human, via the Hub UI) read and act on a self-hosted Bitbucket Data Center / Server instance. There is no separate browser context-switch: PRs, diffs, builds, branches, comments, approvals, and merges are all accessible inside the C3 workflow.

What you get

Quick start

Three commands to wire up an enterprise Bitbucket server and pin a working repo.

c3 bitbucket login \
  --url https://bitbucket.example.com

c3 bitbucket set-default \
  --project PROJ \
  --repo my-service

c3 bitbucket status

First call from Claude Code

# Whoami
c3_bitbucket(action='whoami')

# Open PRs in the pinned repo
c3_bitbucket(action='list_prs', state='OPEN')

# Detail of a specific PR
c3_bitbucket(action='get_pr', pr_id=42)

Authentication & security

Personal Access Tokens

C3 uses Bitbucket Data Center Personal Access Tokens (Bearer auth). Generate one in your Bitbucket profile under Manage account → Personal access tokens. Choose a permission level matching what you intend to do:

Where the token lives

TLS verification

Default: verify_tls = true. To disable verification for self-signed enterprise CAs, pass --insecure on c3 bitbucket login, or flip bitbucket.verify_tls to false in .c3/config.json.

Multiple servers / accounts

save_credentials appends each (base_url, username) pair to the accounts index. Switch with c3 bitbucket use --url ... --username .... The active account is what every c3_bitbucket call resolves to.

Action reference

The MCP tool dispatches by action. Twenty-seven actions are grouped below by capability. Project + repo default from bitbucket.default_project / default_repo when not provided.

Read & discovery

Pull-request writes

Branch writes

Repository administration

CLI commands

Five subcommands cover account lifecycle and repo defaults. Run any with --help for full flags.

Hub UI tab

The per-project Hub UI gains a Bitbucket tab in its sidebar (between Edits and Instructions). Five sub-views:

Endpoints powering the tab live in cli/server.py under /api/bitbucket/*. The Hub server (port 3330) does not host these — Bitbucket is per-project, so the API runs inside each project's session-server (default port 3333).

Audit trail — Edit ledger integration

State changes that happen on the platform side (not in your local working tree) are still appended to the C3 edit ledger so the audit trail is complete. The path for these entries is virtual:

bitbucket://<project>/<repo>

The following actions log to the ledger when they succeed:

Read-only actions and the status probe are not logged. Token text is stripped from logged kwargs before persisting.

.c3/config.json — bitbucket section

Default shape (gets created on first c3 bitbucket login):

{
  "bitbucket": {
    "active": { "base_url": "https://bitbucket.example.com", "username": "alice" },
    "accounts": [
      { "base_url": "https://bitbucket.example.com", "username": "alice" }
    ],
    "default_project": "PROJ",
    "default_repo": "my-service",
    "verify_tls": true
  }
}

Example workflows

Review and merge a PR

# 1. See what's open
c3_bitbucket(action='list_prs', state='OPEN')

# 2. Drill into one
c3_bitbucket(action='get_pr', pr_id=42)
c3_bitbucket(action='get_pr_diff', pr_id=42)

# 3. Comment with review notes
c3_bitbucket(action='comment_pr', pr_id=42,
             body='LGTM modulo the test in test_x.py:42')

# 4. Approve, then merge — version is fetched automatically
c3_bitbucket(action='approve_pr', pr_id=42)
c3_bitbucket(action='merge_pr', pr_id=42,
             message='Merge feat/bitbucket — release v2.30.0')

Open a PR for the current branch

# Push the branch first via c3_shell (auto-logs to ledger)
c3_shell(cmd='git push -u origin feat/bitbucket')

# Then open the PR
c3_bitbucket(action='create_pr',
             title='feat: Bitbucket Data Center integration (v2.30.0)',
             from_branch='feat/bitbucket',
             to_branch='main',
             description='See CHANGELOG [2.30.0] for details.',
             reviewers='alice,bob')

Cut a feature branch via the API

c3_bitbucket(action='create_branch',
             name='feat/oauth-fix',
             start_point='refs/heads/main')

Check CI status before merging

# Latest commit on the PR's source branch
pr = c3_bitbucket(action='get_pr', pr_id=42)
# (in agent code) → fromRef.latestCommit
c3_bitbucket(action='build_status', commit='<sha>')

Inventory webhooks before changing CI

c3_bitbucket(action='list_webhooks')
c3_bitbucket(action='create_webhook',
             name='jenkins',
             url='https://ci.example.com/hooks/bitbucket',
             events='repo:refs_changed,pr:opened,pr:merged',
             active=true,
             secret='shared-with-jenkins')

Troubleshooting

Where to look

• Activity log: Hub UI → Bitbucket tab → Overview, plus .c3/activity_log.jsonl for raw events tagged bitbucket_action.
• Edit ledger: c3_edits(action='history', file='bitbucket://<project>/<repo>') for all platform-side mutations.
• Tool calls: c3_session(action='log') entries record every c3_bitbucket dispatch with action name and (sanitized) args.