bb ai¶
Run bb's MCP server, and install its agent skill
5 commands.
bb ai mcp- Run the MCP server, and list the tools it offers (2 commands)
bb ai skill- Install, remove or print the agent skill (3 commands)
bb ai mcp¶
Run the MCP server, and list the tools it offers
serve- Start the MCP server (stdio transport)
tools- List MCP tools with what they change and whether they ask
bb ai mcp serve¶
Start the MCP server (stdio transport)
bb ai mcp serve [flags]
Start the bb MCP server on stdio, for an MCP client to run.
Configure the client to run bb ai mcp serve, with a token of the server's own in the client's env block:
"bb": {
"command": "bb",
"args": ["ai", "mcp", "serve"],
"env": { "BITBUCKET_TOKEN": "${BB_MCP_TOKEN}" }
}
Every MCP client has that block: Claude Code and Claude Desktop (.mcp.json, claude_desktop_config.json), VS Code, Codex ([mcp_servers.bb.env] in config.toml, or codex mcp add --env) and Antigravity (mcp_config.json). The ${VAR} form keeps the agent on a PAT of its own, which can be read-only while yours can write, and writes neither into the file. No flag takes a token: a flag's value is readable in the process list for as long as the server runs.
Your MCP client decides whether a call runs, through its own prompts, rules or auto mode. What holds whatever it decides is Bitbucket's: its merge checks, the version a merge or an update names, and the token's permissions. --elicitation-opt-in, or mcp_elicitation_opt_in in your configuration file, makes the tools that decide whether or when a pull request merges also ask you in the client before each call: merging, enabling or disabling auto-merge, reporting a build status, creating a tag, and changing a pull request's draft flag. A client that cannot ask is then refused those tools with error -32021. It is a convenience in a client that shows the question, not a control: a client can answer it without you. bb ai mcp tools lists which tools ask.
The server offers only the tools that read unless --allow-writes, or mcp_allow_writes: true in your configuration file, lets it make changes in Bitbucket: you decide once, when you configure it, whether this server may write. Administrative policy can keep it read-only whatever those say. --tools exposes only the tools you name, and --exclude leaves tools out; neither brings back a tool that a read-only server or a scope withholds. refresh_view and suggest_form_values, which only the views of show call, go with show.
--project or --repo confines the server to one project or repository, and a call aimed elsewhere is refused. Build statuses, which hang off a commit rather than a project, are withheld while a scope is set. The server is never scoped by the directory it starts in. --host is required when more than one Bitbucket instance is configured.
A view is drawn from show's result and has no network of its own: its buttons call this server's tools through the client, with their confirmations, the scope and the audit trail. Views highlight code, but of a Svelte, ERB, PHTML, Go HTML or Jinja template only the markup, because a crafted file can keep the lexers for the code in it busy for seconds. --highlight-templates highlights that code too.
--audit-file records every tool call as JSON Lines, to a path or to stderr for a log collector that reads the process streams. When a record cannot be written the call is refused; --audit-failure=warn relaxes that. The trail covers this server only: an agent that can run shell commands can run bb directly. What holds either way is the token, so give this server a narrower PAT than your own.
# Serve the tools that read over stdio, for an MCP client to launch
bb ai mcp serve
# Let it make changes in Bitbucket too, confined to one repository
bb ai mcp serve --allow-writes --repo PROJ/repo
# Name the tools to expose, and record every call
bb ai mcp serve --tools get_pull_request,list_pull_requests,get_pr_diff \
--audit-file /var/log/bb/mcp-audit.jsonl
--ai-disclosure- End the comments, pull request descriptions and tag messages the agent writes with a line saying an AI agent wrote them; with --ai-disclosure=false the server offers no tool that publishes them under your name at once (default true)
--allow-writes- Expose the tools that change Bitbucket too; without it the server offers only the tools that read
--audit-failure string- What to do when an audit record cannot be written (one of: deny, warn) (default "deny")
--audit-file string- Append a JSON Lines audit record per tool call to this path, or to 'stderr'
--elicitation-opt-in- Ask the person in the MCP client before each call of a tool that decides a merge; a client that cannot ask is refused those tools
--exclude string- Comma-separated denylist of tool names to suppress
--highlight-templates- In views, highlight the code inside templates too, not only their markup
--host string- Target Bitbucket instance URL; required when multiple instances are configured
--project string- Confine the server to this project key; calls aimed elsewhere are refused
--repo string- Confine the server to one repository, as PROJECT/slug (or a slug alongside --project)
--tools string- Comma-separated allowlist of tool names to expose
Also takes the global flags.
Dry run: Not accepted: it starts a live server whose tools reach Bitbucket, and a session cannot be previewed.
Output with --json: this command writes no document of its own: runs an MCP server on stdio until it is stopped; the protocol is the output
bb ai mcp tools¶
List MCP tools with what they change and whether they ask
bb ai mcp tools [flags]
Print the MCP tools the serve command exposes.
Use this output to build --tools and --exclude allowlists and denylists.
ACCESS says whether a tool changes anything in Bitbucket. ASKS says whether a call asks the person to confirm it in the MCP client before it runs, on a server started with --elicitation-opt-in; without it, no tool asks:
always every call asks
when-setting-draft a call that sets the pull request's draft flag asks
never the tool runs when called
On a server that asks, a client that cannot show a confirmation gets error -32021 for a call that asks. It lists what bb ai mcp serve exposes with the same flags: the tools that read, and with --allow-writes every tool.
# The tools a server exposes by default: those that only read
bb ai mcp tools
# Every tool, as a server started with --allow-writes exposes them, with
# whether it changes anything and whether it asks first
bb ai mcp tools --allow-writes
--ai-disclosure- List the tools a server with this --ai-disclosure exposes; false leaves out the ones that publish what the agent writes under your name at once (default true)
--allow-writes- List the tools 'bb ai mcp serve --allow-writes' exposes, which change Bitbucket too
Also takes the global flags.
Dry run: Runs as usual: this command changes nothing, so there is nothing to hold back
Output with --json, where ? marks a field that can be absent
data list of object
name string Tool name, as an MCP client sees it.
description? string What the tool does.
writes boolean Whether the tool changes anything in Bitbucket.
asks always|when-setting-draft|never Whether a call asks the person to confirm it in the MCP client before
it runs, on a server started with --elicitation-opt-in; without it no
tool asks. always, never, or when-setting-draft for a call that sets
the pull request's draft flag.
bb ai skill¶
Install, remove or print the agent skill
install- Write an agent skill to the agent skills directories
remove- Remove an installed agent skill file
show- Print an agent skill to stdout
bb ai skill install¶
Write an agent skill to the agent skills directories
bb ai skill install [skill] [flags]
Write an agent skill file (defaults to "bb") where coding agents read it: .agents/skills, which most agents read, and .claude/skills, which Claude Code reads instead.
Project scope (default):
.agents/skills/<skill>/SKILL.md
.claude/skills/<skill>/SKILL.md
Global scope (--global), for every project of yours:
~/.agents/skills/<skill>/SKILL.md
~/.claude/skills/<skill>/SKILL.md
The skill is embedded in this binary, so no network connection is required. Re-run after upgrading bb to keep the skill files current.
# Install the bb skill for this project
bb ai skill install
# Install it for every project of yours
bb ai skill install --global
--global- Install for every project of yours (~/.agents/skills and ~/.claude/skills)
Also takes the global flags.
Dry run: Shows that it would write the skill file, without doing it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
status installed installed, removed, or not_found when removing something already absent.
skill bb Which skill this concerns.
path string Absolute path of the copy in .agents/skills, which most agents read; when removing,
the first file removed.
paths list of string or null Every file written or removed: the .agents/skills copy and the .claude/skills copy
Claude Code reads.
scope project|global project or global, which is what decided the paths.
bb ai skill remove¶
Remove an installed agent skill file
bb ai skill remove [skill] [flags]
# Remove the bb skill from this project
bb ai skill remove
# Remove it from every project of yours, without being asked
bb ai skill remove --global --yes
--global- Remove from every project of yours (~/.agents/skills and ~/.claude/skills)
-y, --yes- Confirm without being asked
Also takes the global flags.
Dry run: Shows that it would delete the skill file, without doing it; nothing is checked first (predicted)
Output with --json, where ? marks a field that can be absent
data
status removed|not_found installed, removed, or not_found when removing something already absent.
skill bb Which skill this concerns.
path string Absolute path of the copy in .agents/skills, which most agents read; when removing,
the first file removed.
paths list of string or null Every file written or removed: the .agents/skills copy and the .claude/skills copy
Claude Code reads.
scope project|global project or global, which is what decided the paths.
bb ai skill show¶
Print an agent skill to stdout
bb ai skill show [skill]
Print an agent skill to stdout (defaults to "bb").
The skill is embedded in this binary at compile time, so it works with no network connection and without the source repository present.
Redirect to the location your coding agent expects:
bb ai skill show > .agents/skills/bb/SKILL.md
Most agents read .agents/skills/<name>/SKILL.md, and Claude Code reads .claude/skills/<name>/SKILL.md; bb ai skill install writes both. For an agent that reads a path of its own, consult its documentation.
The baseline skill (fixed at release time) is also distributed via the open agent skills ecosystem and can be installed without bb being present:
npx skills add vriesdemichael/bitbucket-data-center-cli
The npx-installed files are snapshots from the repository. Use this command to get a skill that always matches your installed bb version.
# Print the skill that matches this bb
bb ai skill show
# Save it for an agent that reads a path of its own
bb ai skill show > .agents/skills/bb/SKILL.md
Also takes the global flags.
Dry run: Runs as usual: this command changes nothing, so there is nothing to hold back
Output with --json: this command writes no document of its own: prints a SKILL.md document; wrapping markdown in a data string helps nobody