Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@bitbucket-mcp show the diff for pull request #42"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server for Bitbucket Cloud. Review, manage, and merge pull requests, assign reviewers by name, read files at a ref, and inspect pipeline status — from any MCP client (Claude Desktop, Cursor, Claude Code) or a hosted HTTP endpoint.
It talks to the Bitbucket Cloud REST API v2.0 with a single access token. All read paths are paginated and capped; write tools (create/merge PR, comments, reviewers) are explicit.
All tools are prefixed bb_.
Tool | What it does |
| List PRs in a repo, filtered by state |
| Full detail for one PR |
| Unified diff for a PR |
| All comments on a PR (inline + general) |
| Aggregated build/status checks for a PR |
| Commit statuses for an arbitrary ref |
| Open a PR (optionally with reviewers) |
| Merge a PR (merge_commit / squash / fast_forward) |
| Add a comment (optionally inline on a file/line) |
| Edit one of your comments |
| Delete one of your comments |
| Assign reviewers by name or UUID |
| Inspect the local known-members directory |
| Read a file's contents at a branch/commit |
Bitbucket's /workspaces/{workspace}/members endpoint requires the account
scope (which PR tokens don't carry), so you can't resolve a person's name to
their account UUID over the API. This server keeps a small local directory
of known members so bb_add_pull_request_reviewers accepts a plain name (e.g.
"Jane Doe") and resolves it offline. Raw account UUIDs always work too.
Seed people in either place (both use the same JSON shape; the env var merges on top of the file):
tools/bitbucket/directory.json — copy directory.example.json and fill it in. This file is git-ignored so real account UUIDs never get committed.
BITBUCKET_KNOWN_MEMBERS env var — handy for hosted deploys.
{
"your-workspace-slug": [
{ "uuid": "{00000000-0000-0000-0000-000000000000}", "display_name": "Jane Doe", "nickname": "Jane" }
]
}Related MCP server: Bitbucket MCP
Set via environment variables (see .env.example). Prefix BITBUCKET_.
Variable | Required | Description |
| ✅ | Access token (Bearer) or app password |
| — | Set only when using an app password (switches to Basic auth) |
| — | Default workspace slug, so tools don't need it each call |
| — | Default repo slug |
| — | JSON of extra known members (merged over |
| — | Pagination cap (default |
| — | HTTP timeout in seconds (default |
Tools are always listed but return a clear "not configured" error if
BITBUCKET_API_KEY is missing, so the server starts cleanly without secrets.
Requires Python 3.11+.
git clone https://github.com/matt-nann/bitbucket-mcp.git
cd bitbucket-mcp
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export BITBUCKET_API_KEY=your-token
python server.py # stdio (default)Claude Desktop (claude_desktop_config.json) / Cursor (~/.cursor/mcp.json):
{
"mcpServers": {
"bitbucket": {
"command": "python",
"args": ["/absolute/path/to/bitbucket-mcp/server.py"],
"env": {
"BITBUCKET_API_KEY": "your-token",
"BITBUCKET_WORKSPACE": "your-workspace-slug"
}
}
}
}Claude Code:
claude mcp add bitbucket \
--env BITBUCKET_API_KEY=your-token \
--env BITBUCKET_WORKSPACE=your-workspace-slug \
-- python /absolute/path/to/bitbucket-mcp/server.pyThe same server runs over streamable HTTP for a shared/hosted deployment. It
binds dual-stack IPv6 and honors $PORT, so it works on Railway (and
Fly/Heroku/Docker) out of the box:
MCP_TRANSPORT=http PORT=8000 python server.py --http
# MCP endpoint: http://localhost:8000/mcp health: /health⚠️ HTTP mode has no built-in authentication and every request uses the one
BITBUCKET_API_KEY identity. Don't expose it publicly without an auth proxy in
front. See HOSTING.md for the full Railway walkthrough,
Docker instructions, and the security model.
Extracted from a larger internal multi-tool MCP server into a standalone, self-contained package. No internal identifiers or shared auth layers are included; the member directory ships only as a placeholder example.
Create a new Bitbucket pull request.
Args: title: PR title. source_branch: Source branch name. destination_branch: Destination branch name (default "main"). description: PR description (Markdown). reviewers: List of Bitbucket account UUIDs. close_source_branch: Delete source branch after merge. workspace: Bitbucket workspace slug. repo: Repository slug.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository slug. Defaults to BITBUCKET_DEFAULT_REPO. | |
| title | Yes | PR title. | |
| reviewers | No | List of Bitbucket account UUIDs to request as reviewers. | |
| workspace | No | Bitbucket workspace slug. Defaults to BITBUCKET_WORKSPACE. | |
| description | No | PR description (Markdown). | |
| source_branch | Yes | Source branch name. | |
| destination_branch | No | Destination branch name. | main |
| close_source_branch | No | Delete the source branch after merge. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It describes the action and parameters but does not disclose side effects (beyond close_source_branch), success/failure behavior, authentication requirements, or rate limits. The agent cannot infer the overall behavior beyond creation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a clear bulleted list starting with the action. It is appropriately sized for 8 parameters and avoids redundancy. However, it could be slightly more concise by merging default values inline, but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters and high schema coverage, the description covers the necessary input information. An output schema exists, so return values are handled elsewhere. However, behavioral gaps (e.g., error handling, idempotency) reduce completeness for an agent unfamiliar with Bitbucket.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal value. It restates parameter names and short descriptions, but does not elaborate on constraints, formats, or relationships. For example, 'reviewers: List of Bitbucket account UUIDs' is identical to the schema. No additional nuance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create a new Bitbucket pull request' and lists relevant parameters. The name 'bb_create_pull_request' clearly indicates a creation action, and siblings are all about comments or retrieval, so the purpose is distinct and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, when not to use it, or how it compares to similar tools like 'bb_edit_pull_request_comment' or 'bb_get_pull_request'. The context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a comment to a Bitbucket pull request — general or inline on a specific file/line.
Args: pull_request_id: The PR id (number). content: Comment body (Markdown). inline_path: File path for inline comment. inline_to: Line number in new version. inline_from: Line number in old version. workspace: Bitbucket workspace slug. repo: Repository slug.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository slug. Defaults to BITBUCKET_DEFAULT_REPO. | |
| content | Yes | Comment body (Markdown). | |
| inline_to | No | Line number in the new version of the file. | |
| workspace | No | Bitbucket workspace slug. Defaults to BITBUCKET_WORKSPACE. | |
| inline_from | No | Line number in the old version of the file. | |
| inline_path | No | File path for an inline comment. Omit for a general comment. | |
| pull_request_id | Yes | The PR id (number). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It indicates mutation ('Add a comment') and explains the difference between general and inline comments, but does not disclose auth requirements, rate limits, or potential side effects beyond the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear one-line summary followed by a list of parameters. It is slightly lengthy but front-loads the purpose. Could be more concise by avoiding repetition of parameter names already in schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters (2 required) and the existence of an output schema, the description adequately explains the two modes (general vs inline) and covers the necessary parameters. It is sufficient for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema by explaining the role of inline parameters (inline_path, inline_from, inline_to) and defaults for workspace and repo. Schema coverage is 100%, but the description clarifies usage context for inline vs general comments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Add), resource (comment to a Bitbucket pull request), and distinguishes between general and inline comments. It differentiates from siblings like bb_delete_pull_request_comment and bb_edit_pull_request_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for adding comments but does not explicitly state when to use this tool versus alternatives. No guidance on when not to use it or what prerequisites exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a comment from a Bitbucket pull request.
Permanently removes the comment. Only the comment's author may delete it — deleting someone else's comment fails with an authorization error. Get comment ids from bb_get_pull_request_comments. Returns a confirmation with the deleted comment id.
Args: pull_request_id: The PR id (number). comment_id: The id of the comment to delete. workspace: Bitbucket workspace slug. repo: Repository slug.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository slug. Defaults to BITBUCKET_DEFAULT_REPO. | |
| workspace | No | Bitbucket workspace slug. Defaults to BITBUCKET_WORKSPACE. | |
| comment_id | Yes | The id of the comment to delete. | |
| pull_request_id | Yes | The PR id (number). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses permanent removal (destructive), authorization requirement, and return value (confirmation with deleted comment id). This is transparent and sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: one sentence for purpose, then behavioral details, then a bullet list of arguments. Every sentence adds value and is front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter tool with 2 required, no nested objects, and an output schema, the description covers purpose, usage, behavior (authorization, permanence), parameter sourcing, and return value. Complete for effective usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description lists args in a docstring but adds little beyond schema—only repeats descriptions already in the schema. No additional semantic nuance provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Delete a comment from a Bitbucket pull request.' This distinguishes it from sibling tools like bb_create_pull_request_comment and bb_edit_pull_request_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies that only the comment's author can delete it and that deletion fails otherwise. Also tells where to get comment IDs (bb_get_pull_request_comments), providing clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit the body of an existing Bitbucket pull request comment.
Replaces the comment's content with content and returns the updated
comment. Only the comment's author may edit it — editing someone else's
comment fails with an authorization error. Get comment ids from
bb_get_pull_request_comments.
Args: pull_request_id: The PR id (number). comment_id: The id of the comment to edit. content: New comment body (Markdown), replaces the old one. workspace: Bitbucket workspace slug. repo: Repository slug.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository slug. Defaults to BITBUCKET_DEFAULT_REPO. | |
| content | Yes | New comment body (Markdown), replaces the old one. | |
| workspace | No | Bitbucket workspace slug. Defaults to BITBUCKET_WORKSPACE. | |
| comment_id | Yes | The id of the comment to edit. | |
| pull_request_id | Yes | The PR id (number). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the authorization constraint and that content replaces the old one. This is adequate, though could mention if edit is irreversible or any side effects. Still, it provides key behavioral insight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one short paragraph followed by an Args list. Every sentence serves a distinct purpose (purpose, behavior, constraint, source of IDs). No redundant or vague statements. Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description covers the action, constraints, and parameter roles sufficiently. It mentions the return behavior and auth limitations. For a tool with 5 parameters and a key constraint, it is comprehensive without being verbose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining the replacement effect ("Replaces the comment's content") and that the tool returns the updated comment, which supplements the schema descriptions. Some repetition exists but it's minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool edits the body of an existing Bitbucket pull request comment, specifying the verb (edit) and resource. It distinguishes itself from sibling tools like bb_create_pull_request_comment and bb_delete_pull_request_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: only the comment's author may edit, otherwise authorization fails. Also advises get comment ids from bb_get_pull_request_comments, helping the agent understand prerequisites and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Bitbucket PR's metadata: title, description, author, branches, reviewers, state.
Args: pull_request_id: The PR id (number). workspace: Bitbucket workspace slug. repo: Repository slug.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository slug. Defaults to BITBUCKET_DEFAULT_REPO. | |
| workspace | No | Bitbucket workspace slug. Defaults to BITBUCKET_WORKSPACE. | |
| pull_request_id | Yes | The PR id (number). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the burden. It describes a read operation (getting metadata) but does not explicitly state side effects, authentication needs, or error behavior. The implied safety is adequate but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a parameter list, front-loaded with purpose. Every sentence is useful with no redundancy or waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description need not detail return values. It covers the tool's purpose, parameters, and key return fields. Lacks behavioral depth but is sufficient for a simple read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's parameter list largely repeats what the schema already provides (names, defaults). It adds no new semantic information beyond listing the arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'Bitbucket PR's metadata', listing specific fields (title, description, author, branches, reviewers, state). This distinguishes it from sibling tools like bb_get_pull_request_status or bb_get_pull_request_diff.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for retrieving PR metadata, but it does not explicitly state when to use this tool versus alternatives like bb_get_pull_request_status. No exclusions or prerequisites are mentioned, though the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the review discussion on a Bitbucket PR (general and inline comments).
Args: pull_request_id: The PR id (number). workspace: Bitbucket workspace slug. repo: Repository slug.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository slug. Defaults to BITBUCKET_DEFAULT_REPO. | |
| workspace | No | Bitbucket workspace slug. Defaults to BITBUCKET_WORKSPACE. | |
| pull_request_id | Yes | The PR id (number). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It states the operation is a read (Get) and mentions it returns both general and inline comments. However, it does not disclose any behavioral traits such as authentication requirements, rate limits, or potential errors. It is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the purpose. The Args list is structured but slightly redundant with the schema. It is concise with no unnecessary sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, read-only operation) and the presence of an output schema, the description provides sufficient context. It explains the purpose and parameters well, but could optionally mention pagination or sort order if applicable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the baseline is 3. The description's parameter explanations largely repeat the schema's descriptions (e.g., defaults to environment variables). It adds no new meaning beyond what is already defined in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it gets the review discussion on a Bitbucket PR, including both general and inline comments. The verb 'Get' and resource 'review discussion' are specific, and the tool is distinct from siblings like bb_get_pull_request_diff and bb_get_pull_request_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching comments, but does not explicitly state when to use this tool versus alternatives like bb_get_pull_request for PR details or bb_get_pull_request_diff for diffs. No when-not or alternative guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the unified diff for a Bitbucket PR. Returns raw diff text.
Args: pull_request_id: The PR id (number). file_path: Optional file path filter. workspace: Bitbucket workspace slug. repo: Repository slug.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository slug. Defaults to BITBUCKET_DEFAULT_REPO. | |
| file_path | No | Optional: filter the diff to a single file path. | |
| workspace | No | Bitbucket workspace slug. Defaults to BITBUCKET_WORKSPACE. | |
| pull_request_id | Yes | The PR id (number). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'Returns raw diff text' but does not disclose potential issues like large output size, authentication requirements, or error handling. Minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the essential purpose. The Args list is somewhat redundant with the schema but not excessive. Only minor improvement possible by removing redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description doesn't need to detail return values. However, it lacks guidance on prerequisites (e.g., PR existence) and behavior for edge cases like empty diff. Adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description adds no new meaning beyond the schema. Parameter descriptions in the description essentially replicate schema info (e.g., 'Optional file path filter'). Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the unified diff for a Bitbucket PR' with a specific verb and resource. Among siblings, it's the only tool for retrieving diffs, making it easily distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for getting a PR diff but does not explicitly state when to use it versus alternatives (e.g., bb_get_pull_request for metadata). No exclusions or scenarios are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get CI/build status for a Bitbucket PR's latest commit.
Args: pull_request_id: The PR id (number). workspace: Bitbucket workspace slug. repo: Repository slug.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository slug. Defaults to BITBUCKET_DEFAULT_REPO. | |
| workspace | No | Bitbucket workspace slug. Defaults to BITBUCKET_WORKSPACE. | |
| pull_request_id | Yes | The PR id (number). |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It states the tool retrieves CI status but omits details like whether it's read-only, authentication needs, or what happens when no status exists. This is minimally adequate for a simple get operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence followed by a concise parameter list. It is front-loaded with the core purpose and contains no superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the simplicity of the tool (a read operation on CI status), the description adequately covers purpose and parameters. It lacks mention of potential edge cases but is sufficiently complete for a straightforward retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description's parameter details ('pull_request_id: The PR id (number)', etc.) essentially repeat the schema descriptions. Since schema coverage is 100%, the description adds no new semantic value, meeting the baseline for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Get CI/build status for a Bitbucket PR's latest commit', specifying the verb, resource, and scope. This clearly distinguishes from sibling tools like bb_get_pull_request which retrieves PR metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description does not mention exclusion conditions, prerequisites, or contrast with similar tools like bb_get_pull_request, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List known workspace members to resolve a person's name to their UUID.
Members come from the local known-members directory (see directory.py).
Bitbucket's live members API is not used: it requires the account
scope the MCP token doesn't carry, so it only ever returned 403. The
directory is the single source of truth — seed people into
directory.json or the BITBUCKET_KNOWN_MEMBERS env var.
You usually don't need to call this before bb_add_pull_request_reviewers — that tool resolves names against the same directory itself. Use this to inspect who is known, or when a name is ambiguous. If more than one member matches, present the candidates rather than guessing.
Args: query: Optional case-insensitive name filter (display name or nickname). workspace: Bitbucket workspace slug.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional case-insensitive name filter matched against each member's display name and nickname. Omit to list everyone. | |
| workspace | No | Bitbucket workspace slug. Defaults to BITBUCKET_WORKSPACE. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully compensates by explaining why the live API is not used (403 due to scope), the directory as source of truth, and how to seed members.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a clear purpose sentence, explanatory paragraphs, and parameter details. Compact but not terse; could be slightly more concise but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no enums and an output schema, the description covers purpose, internals, usage guidance, and parameter semantics comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds useful context like case-insensitivity and nickname matching for query, and default workspace behavior, going slightly beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists known workspace members to resolve a person's name to their UUID, with a specific verb and resource. It distinguishes from sibling tools that focus on pull requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use (inspect known members, handle ambiguity) and when not to (usually not needed before bb_add_pull_request_reviewers), and provides guidance on ambiguous matches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0bb_create_pull_requestbb_create_pull_request_commentbb_delete_pull_request_commentbb_edit_pull_request_commentbb_get_pull_requestbb_get_pull_request_commentsbb_get_pull_request_diffbb_get_pull_request_statusbb_list_workspace_membersScored across 9 tools
Each tool targets a distinct action on pull requests or workspace members. No two tools overlap in purpose; create, get, diff, status, and comment operations are clearly separated.
All tools follow a consistent 'bb_verb_noun' pattern (e.g., bb_create_pull_request, bb_get_pull_request_comments). The naming is uniform and predictable across the entire set.
With 9 tools, the server is well-scoped for Bitbucket pull request management. It covers core operations without being overly broad or too sparse.
While comment CRUD is fully covered, missing operations like listing, updating, merging, or declining pull requests create gaps for a complete PR workflow. The workspace members list is a helpful auxiliary tool.
A MCP server built for developers enabling Git based project management with project and personal…
MCP Server for JFrog, providing tools for development and artifact management.
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
MCP server for Appcircle mobile CI/CD platform.
