bb-mcp-server
Provides tools for managing Bitbucket Cloud pull requests, including listing, fetching, creating, updating, merging, declining, approving, and retrieving diffs and diffstats, as well as managing pull request comments and descriptions.
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., "@bb-mcp-server Show me the open pull requests in our Bitbucket repo."
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.
bb-mcp-server
An MCP server for Bitbucket Cloud, giving MCP clients (Claude Code, Claude Desktop, etc.) tools to read and manage pull requests, their comments, and their descriptions.
Atlassian has announced an official Bitbucket MCP server; at the time this was written it wasn't yet available, so this fills the gap with the same underlying REST API.
Features
Pull requests — list, get, create, update, merge, decline, approve/unapprove, diff, diffstat
Comments — list, get, create (general, inline, or as a reply), update, delete
Descriptions — focused get/update tools that touch only the description field
See Tools below for the full list.
Related MCP server: bitbucket-mcp
Requirements
Node.js >= 18.17
A Bitbucket Cloud account with an Atlassian API token
Setup
npm install
npm run buildConfigure credentials via environment variables (see .env.example):
Variable | Required | Description |
| yes | Atlassian account email, used with the API token for Basic Auth. |
| yes | API token from id.atlassian.com. |
| no | Default workspace slug, so tools can omit |
| no | Default repository slug, so tools can omit |
| no | API base URL override. Defaults to |
Register with an MCP client
Example for Claude Code (claude mcp add) or a client's mcp.json:
{
"mcpServers": {
"bitbucket": {
"command": "node",
"args": ["/absolute/path/to/bb-mcp-server/dist/index.js"],
"env": {
"BITBUCKET_EMAIL": "you@example.com",
"BITBUCKET_API_TOKEN": "your-api-token",
"BITBUCKET_WORKSPACE": "my-workspace",
"BITBUCKET_REPO_SLUG": "my-repo"
}
}
}
}BITBUCKET_WORKSPACE and BITBUCKET_REPO_SLUG are optional — omit them to require every tool
call to specify workspace/repoSlug explicitly, which is useful if the client should be able to
work across multiple repositories.
Try it with the MCP Inspector
npm run inspectorTools
All tools accept optional workspace / repoSlug arguments that fall back to
BITBUCKET_WORKSPACE / BITBUCKET_REPO_SLUG when omitted.
Pull requests
Tool | Description |
| List PRs, filterable by state or a Bitbucket query string. |
| Fetch full details of one PR. |
| Open a new PR. |
| Update title, description, reviewers, and/or destination. |
| Merge an open PR. |
| Decline an open PR. |
| Approve a PR as the authenticated user. |
| Remove the authenticated user's approval. |
| Fetch the unified diff as raw text. |
| Fetch a per-file change summary. |
Comments
Tool | Description |
| List all (non-deleted) comments on a PR. |
| Fetch a single comment. |
| Add a comment — general, inline (via |
| Edit a comment's body. |
| Delete a comment. |
Descriptions
Tool | Description |
| Read just a PR's description. |
| Replace just a PR's description, without touching other fields. |
Development
npm run dev # run the server directly with tsx (no build step)
npm run typecheck # tsc --noEmit
npm run lint # eslint
npm run format # prettier --write
npm test # vitest
npm run build # compile to dist/Architecture
src/
config.ts # env var loading/validation (zod)
bitbucket/
client.ts # typed Bitbucket REST API v2.0 client (auth, pagination, errors)
errors.ts # BitbucketApiError
types.ts # Bitbucket API response shapes
tools/
shared.ts # zod param helpers, workspace/repo resolution, error wrapping
pullRequests.ts # bb_* PR tools
comments.ts # bb_* comment tools
descriptions.ts # bb_* description tools
index.ts # registerAllTools
server.ts # builds the McpServer and registers tools
index.ts # stdio entrypointAuthentication notes
This server authenticates with HTTP Basic Auth using your Atlassian account email and an API token — the auth method Atlassian currently recommends for Bitbucket Cloud (app passwords are being phased out). The token only needs the Pull Requests scope for the operations this server performs.
License
MIT
Available Tools
17 toolsbb_approve_pull_requestApprove pull requestB
Approves a pull request as the authenticated user.
Inputs: pullRequestId (required), repoSlug, workspace.
bb_create_pull_requestCreate pull requestB
Creates a new pull request from a source branch into a destination branch.
Inputs: title (required), sourceBranch (required), repoSlug, reviewers, +4 more.
bb_create_pull_request_commentCreate pull request commentA
Adds a comment to a pull request. Provide inlinePath (and optionally inlineLine) for a code review comment anchored to a file, or parentId to reply to an existing comment. Omit both for a general comment.
Inputs: content (required), pullRequestId (required), parentId, repoSlug, +3 more.
bb_decline_pull_requestDecline pull requestB
Declines an open pull request.
Inputs: pullRequestId (required), message, repoSlug, workspace.
bb_delete_pull_request_commentDelete pull request commentB
Deletes a comment from a pull request.
Inputs: commentId (required), pullRequestId (required), repoSlug, workspace.
bb_get_pull_requestGet pull requestA
Fetches full details of a single pull request, including its description.
Inputs: pullRequestId (required), repoSlug, workspace.
bb_get_pull_request_commentGet pull request commentB
Fetches a single comment on a pull request by ID.
Inputs: commentId (required), pullRequestId (required), repoSlug, workspace.
bb_get_pull_request_descriptionGet pull request descriptionA
Fetches just a pull request's description text, as raw Markdown.
Inputs: pullRequestId (required), repoSlug, workspace.
bb_get_pull_request_diffGet pull request diffA
Fetches the unified diff of a pull request as raw text.
Inputs: pullRequestId (required), repoSlug, workspace, contextLines.
bb_get_pull_request_diffstatGet pull request diffstatA
Fetches a per-file summary of changes (added/removed/modified, line counts) for a pull request.
Inputs: pullRequestId (required), repoSlug, workspace.
bb_list_pull_request_commentsList pull request commentsA
Lists all (non-deleted) comments on a pull request, including inline code comments and replies.
Inputs: pullRequestId (required), repoSlug, workspace.
bb_list_pull_requestsList pull requestsA
Lists pull requests in a repository, optionally filtered by state or a Bitbucket query string.
Inputs: sort, query, state, pagelen, +2 more.
bb_merge_pull_requestMerge pull requestC
Merges an open pull request.
Inputs: pullRequestId (required), message, repoSlug, workspace, +2 more.
bb_unapprove_pull_requestUnapprove pull requestA
Removes the authenticated user's approval from a pull request.
Inputs: pullRequestId (required), repoSlug, workspace.
bb_update_pull_requestUpdate pull requestA
Updates an open pull request. Only the provided fields are changed; omit a field to leave it as-is. For description-only edits, prefer bb_update_pull_request_description.
Inputs: pullRequestId (required), title, repoSlug, reviewers, +3 more.
bb_update_pull_request_commentUpdate pull request commentA
Edits the body of an existing comment. Only the comment's author can edit it.
Inputs: content (required), commentId (required), pullRequestId (required), repoSlug, +1 more.
bb_update_pull_request_descriptionUpdate pull request descriptionA
Replaces a pull request's description without touching its title, reviewers or destination branch.
Inputs: description (required), pullRequestId (required), repoSlug, workspace.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool targets a distinct action on a pull request or its comments, from core lifecycle (create, get, update, merge, decline) to diffs and comment management. The only potential overlap is between bb_update_pull_request and bb_update_pull_request_description, but the descriptions clearly delineate when to use the specific description-only variant, making misselection unlikely.
All tools follow a consistent verb_noun naming pattern with a bb_ prefix, using snake_case throughout (e.g., bb_list_pull_requests, bb_delete_pull_request_comment). Verbs are uniformly lowercase and resource names are consistently structured, with no mixing of camelCase or other conventions.
At 17 tools, the set is slightly above the typical 3-15 range for a well-scoped server, but each tool serves a distinct purpose in managing pull requests and their comments. The count is justified by the comprehensive feature set, though it edges toward the higher end.
The server provides full CRUD and lifecycle coverage for pull requests, including creation, retrieval, updates, merge, decline, approval, diffs, and comment management. Minor gaps exist, such as no direct tool for managing reviewers or listing commits, but these are peripheral to the core PR workflow and can be worked around via API query capabilities.
Maintenance
Related MCP Connectors
A MCP server built for developers enabling Git based project management with project and personal…
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
MCP Server for JFrog, providing tools for development and artifact management.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server for Bitbucket Cloud that enables managing pull requests, branches, and repositories in natural language from any MCP-capable client.23542 npm4MIT
- FlicenseCqualityDmaintenanceAn MCP server for Bitbucket Cloud, covering pull requests, pull request comments, and pipelines.26-
- AlicenseAqualityDmaintenanceMCP server for Bitbucket Cloud that enables reviewing, managing, and merging pull requests, assigning reviewers by name, reading files at a ref, and inspecting pipeline status from any MCP client.14MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Bitbucket Cloud that enables listing repositories, managing pull requests, posting comments, and handling tasks via natural language.MIT