Skip to main content
Glama
bb-mcp-server

bb-mcp-server

by donchoko

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

Setup

npm install
npm run build

Configure credentials via environment variables (see .env.example):

Variable

Required

Description

BITBUCKET_EMAIL

yes

Atlassian account email, used with the API token for Basic Auth.

BITBUCKET_API_TOKEN

yes

API token from id.atlassian.com.

BITBUCKET_WORKSPACE

no

Default workspace slug, so tools can omit workspace per call.

BITBUCKET_REPO_SLUG

no

Default repository slug, so tools can omit repoSlug per call.

BITBUCKET_BASE_URL

no

API base URL override. Defaults to https://api.bitbucket.org/2.0.

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 inspector

Tools

All tools accept optional workspace / repoSlug arguments that fall back to BITBUCKET_WORKSPACE / BITBUCKET_REPO_SLUG when omitted.

Pull requests

Tool

Description

bb_list_pull_requests

List PRs, filterable by state or a Bitbucket query string.

bb_get_pull_request

Fetch full details of one PR.

bb_create_pull_request

Open a new PR.

bb_update_pull_request

Update title, description, reviewers, and/or destination.

bb_merge_pull_request

Merge an open PR.

bb_decline_pull_request

Decline an open PR.

bb_approve_pull_request

Approve a PR as the authenticated user.

bb_unapprove_pull_request

Remove the authenticated user's approval.

bb_get_pull_request_diff

Fetch the unified diff as raw text.

bb_get_pull_request_diffstat

Fetch a per-file change summary.

Comments

Tool

Description

bb_list_pull_request_comments

List all (non-deleted) comments on a PR.

bb_get_pull_request_comment

Fetch a single comment.

bb_create_pull_request_comment

Add a comment — general, inline (via inlinePath/inlineLine), or a reply (via parentId).

bb_update_pull_request_comment

Edit a comment's body.

bb_delete_pull_request_comment

Delete a comment.

Descriptions

Tool

Description

bb_get_pull_request_description

Read just a PR's description.

bb_update_pull_request_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 entrypoint

Authentication 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 tools
bb_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

    A3.7/5.0

    Scored across 17 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers