Bitbucket 代码审查 MCP 服务器

🔍 Bitbucket Code Review MCP Server

An MCP (Model Context Protocol) server that enables AI agents like Gemini CLI and Antigravity to post well-formatted code review comments on Bitbucket Cloud pull requests.

The MCP does NOT review code itself — it provides tools for agents to create comments tagged with [🤖 AI Review] that a human reviewer will review and approve.

✨ Features

v2 is a breaking change — see Migrating from v1. The tool surface was consolidated (21 → 15), severity was removed, update_comment now replaces by default, and delete_comment no longer relies on a text tag.

🚀 Setup

Prerequisites

• Node.js 22+ (LTS) via nvm
• A Bitbucket Cloud account with an API Token
  • Required permissions: Repositories: Read, Pull requests: Read & Write

Install from GitHub

The easiest way to use this MCP is directly from GitHub — no cloning needed:

# npx directly from GitHub (recommended for agents)
npx -y github:Adyel/bitbucket-code-review-mcp

Or clone and build locally:

git clone https://github.com/Adyel/bitbucket-code-review-mcp.git
cd bitbucket-code-review-mcp
nvm use 22
npm install   # auto-builds via `prepare` script

Environment Variables

# Required
export BITBUCKET_EMAIL="your-atlassian-email@example.com"
export BITBUCKET_API_TOKEN="your-api-token"

# Optional defaults (avoids specifying in every tool call)
# These values come from your Bitbucket repo URL:
#   https://bitbucket.org/{workspace}/{repo_slug}
# e.g. https://bitbucket.org/acme-corp/backend-api
#   → BITBUCKET_DEFAULT_WORKSPACE=acme-corp
#   → BITBUCKET_DEFAULT_REPO_SLUG=backend-api
export BITBUCKET_DEFAULT_WORKSPACE="your-workspace"
export BITBUCKET_DEFAULT_REPO_SLUG="your-repo"

# Optional: your Bitbucket account ID, used by get_review_activity.
# Needed when the API token lacks the read:user:bitbucket scope (GET /user).
# Find it in any PR's API JSON under author.account_id / participants[].user.account_id.
export BITBUCKET_ACCOUNT_ID="your-account-id"

# Optional: customize the AI review tag (default: 🤖 AI Review)
# Set to empty string to disable tagging entirely: BITBUCKET_AI_TAG=""
export BITBUCKET_AI_TAG="🤖 AI Review"

# Optional: create comments as pending/draft (default: false)
# When true, comments are not published until the reviewer submits the review
export BITBUCKET_COMMENTS_PENDING=false

🔌 Agent Configuration

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "bitbucket-code-review": {
      "command": "npx",
      "args": ["-y", "github:Adyel/bitbucket-code-review-mcp"],
      "env": {
        "BITBUCKET_EMAIL": "your-atlassian-email@example.com",
        "BITBUCKET_API_TOKEN": "your-api-token",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace",
        "BITBUCKET_DEFAULT_REPO_SLUG": "your-repo"
      }
    }
  }
}

Local install alternative: If you cloned the repo locally, replace the command and args with:

复制

"command": "node",
"args": ["/absolute/path/to/bitbucket-code-review-mcp/dist/index.js"]

Antigravity / Other MCP Clients

{
  "bitbucket-code-review": {
    "command": "npx",
    "args": ["-y", "github:Adyel/bitbucket-code-review-mcp"],
    "env": {
      "BITBUCKET_EMAIL": "your-atlassian-email@example.com",
      "BITBUCKET_API_TOKEN": "your-api-token",
      "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace",
      "BITBUCKET_DEFAULT_REPO_SLUG": "your-repo"
    }
  }
}

🛠️ Available Tools

PR Discovery

Code Review Comments

Tasks

Read-only tools (list_*, get_*) are annotated with readOnlyHint, and delete_comment with destructiveHint, so MCP hosts can auto-approve reads and confirm deletes appropriately.

🔒 Safety Guards

• Delete protection: delete_comment deletes only comments authored by the account the API token authenticates as (checked via GET /user, cached). Bitbucket also enforces permission server-side, and a 403 is surfaced as a clear message.
• Edit control: update_comment cleanly replaces a comment by default. Pass append=true to keep the old body, and mark=true to add an [✏️ Updated by AI] marker when you want the edit to be visible.
• Configurable tag: Set BITBUCKET_AI_TAG to customize the [🤖 AI Review] prefix, or "" to disable it. The tag is cosmetic — deletion no longer depends on it.
• Pending comments: Set BITBUCKET_COMMENTS_PENDING=true to create comments as drafts that are only published when the reviewer submits the review.

Token scope: use an API token for the review bot's own account. The authorship check keys off that account, so an admin/shared token would let the bot delete comments authored by that same account across the repo.

🔀 Migrating from v1

🔄 Resilience & Pagination

• Automatic pagination: All list endpoints (list_pull_requests, list_comments, list_pull_request_files, list_tasks) automatically follow Bitbucket's next URLs to return complete results, even for large PRs. If the safety cap (200 pages) or a circular link is hit, a warning is logged to stderr.
• Retry with backoff: API requests automatically retry on HTTP 429 (rate limit) and 5xx (server errors) with exponential backoff, respecting Retry-After headers.

🎨 Comment Formatting

All comments are auto-tagged with the configurable [🤖 AI Review] prefix:

[🤖 AI Review]
Use optional chaining for safer property access.

Code suggestions use Bitbucket's native syntax and render an Apply button. They carry the AI tag like any other comment and no label of their own:

[🤖 AI Review]
Use optional chaining here

```suggestion
const name = user?.name ?? 'default';
```

📁 Project Structure

src/
├── index.ts               # Entry point (Zod env validation, --version)
├── bitbucket-client.ts    # API client (auth, identity, pagination, retry, truncation)
├── comment-formatter.ts   # Comment formatting & AI tag
├── schemas/
│   └── shared.ts          # Shared Zod input schemas
├── utils/
│   └── response.ts        # Response helpers & error handling
└── tools/
    ├── index.ts            # Tool registration entry point
    ├── pr-discovery.ts     # PR lookup, diff, file content
    ├── comments.ts         # add/update/delete/list/resolve comments
    ├── tasks.ts            # Task create/list/update
    └── bulk.ts             # Batch comments (add_comments)

🤝 Contributing

See CONTRIBUTING.md for development setup, adding tools, and the release process.

CLI

node dist/index.js --version   # Print version and exit

License

MIT