Bitbucket MCP服务器

host-mcp-bitbucket

A local MCP (Model Context Protocol) server for Bitbucket that provides AI assistants with access to Bitbucket repositories, pull requests, comments, diffs, and tasks via REST API.

Works with both Bitbucket Cloud and Bitbucket Server/Data Center instances.

Compatibility

Note: Tasks on Data Center use the blocker-comments API (/blocker-comments) introduced in Bitbucket 7.2. The legacy /tasks endpoint was removed in Bitbucket 9.0. This MCP server uses the modern blocker-comments API, which is the only option on DC 8.0+.

Features

• Dual platform — full support for both Bitbucket Cloud and Bitbucket Server/Data Center APIs
• Repository operations — list and get repository details
• Pull request management — create, update, approve, merge, decline, request changes
• PR comments — add, update, delete, resolve/reopen comments (including inline comments)
• PR diffs — get raw diffs, diff statistics, and patches
• PR tasks — create, update, delete tasks on pull requests
• Pending reviews — stage draft review comments, then submit or discard the entire review at once (Data Center only)
• Branch & tag listing — list branches and tags with optional filtering
• Pagination — automatic pagination with all mode (capped at 1000 items); Cloud and DC pagination styles handled transparently
• Dual transport — stdio (default) and stateless Streamable HTTP (per-request sessions; supports concurrent clients and reconnections)
• Retry with backoff — automatic retry on transient errors (429, 5xx)

Quick Start

Install from npm

npx @mister-good-deal/host-mcp-bitbucket --bitbucket-token <YOUR_TOKEN>

Use with Claude Desktop / VS Code

Add to your MCP configuration:

{
    "mcpServers": {
        "bitbucket": {
            "command": "npx",
            "args": [
                "-y",
                "@mister-good-deal/host-mcp-bitbucket",
                "--bitbucket-token", "<YOUR_TOKEN>",
                "--default-workspace", "<YOUR_WORKSPACE>"
            ]
        }
    }
}

Environment Variables

You can also configure via environment variables:

export BITBUCKET_TOKEN="your-app-password-or-access-token"
export BITBUCKET_WORKSPACE="your-workspace"
export BITBUCKET_URL="https://api.bitbucket.org/2.0"  # optional, default for Cloud

Configuration

Bitbucket Server / Data Center

For self-hosted instances, point --bitbucket-url to your server URL (the REST API path is auto-appended):

npx @mister-good-deal/host-mcp-bitbucket \
    --bitbucket-url "https://bitbucket.mycompany.com" \
    --bitbucket-token "<YOUR_HTTP_ACCESS_TOKEN>" \
    --default-workspace "<PROJECT_KEY>"

The server auto-detects the platform (Cloud vs Data Center) from the URL and uses the correct API paths, pagination style, and request bodies. For DC, the --default-workspace value maps to a project key.

Available Tools

Pagination

Unless noted otherwise, listing tools accept the following optional parameters:

• pagelen — Number of items per page (default: 10, max: 100)
• page — 1-based page number
• all — When true, fetches all pages automatically (capped at 1000 items)

Workspace / Connectivity

Repository Operations

Note on createRepository: the slug comes from the URL on Cloud, so it is derived from name unless repoSlug is given; on Data Center the server always derives it. defaultBranch is Data Center only — Cloud cannot set it before a branch exists, so it is ignored and reported in the response message. isPrivate maps to is_private on Cloud and to public (inverted) on Data Center; forkable maps to forkable on Data Center and to fork_policy (allow_forks/no_forks) on Cloud.

Pull Request Operations

Pull Request Comment Operations

Pull Request Diff Operations

Pull Request Task Operations

Tasks on Cloud use the standard tasks API. On Data Center, tasks are implemented via blocker-comments (/blocker-comments), which is the canonical replacement since Bitbucket 7.2+.

Pending Review Operations (Data Center only)

These tools enable a staged review workflow: an AI agent drafts review comments that remain invisible until a human reviewer submits or discards the entire review.

Note: Pending reviews require Bitbucket Data Center. On Cloud, these tools return a clear error message.

Branch & Tag Operations

Development

pnpm install
pnpm run build
pnpm run lint
pnpm run test
pnpm run dev   # Run with tsx in dev mode

Integration Tests

Integration tests run against a lightweight Docker mock server that stubs both Bitbucket Cloud and Data Center REST APIs:

pnpm run test:integration

The mock server starts in under 1 second and provides deterministic responses with pre-populated fixtures (projects, repositories, pull requests, comments, tasks/blocker-comments, branches, tags).

Note: Atlassian publishes an official Bitbucket Data Center Docker image (atlassian/bitbucket) that can be used for manual smoke testing against a real instance. However, it requires ~2 GB RAM, takes 1–3 minutes to start, and needs a license — so it is not used for automated tests.

License

MIT