Which integrations are available for this server?

Provides tools for interacting with Bitbucket Cloud REST API v2.0, enabling AI agents to manage repositories, pull requests (including drafts, comments, and pending reviews), branching models, and pipelines.

How do I use mcp-bitbucket?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-bitbucket Show open pull requests" 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.

mcp-bitbucket

by webboy

Overview Schema Related Servers Score Discussions

Python

Hybrid

mcp-bitbucket

License: MIT Python 3.10+ MCP

Python MCP (Model Context Protocol) server for Bitbucket Cloud (REST API v2.0), built with FastMCP. It exposes 35 tools covering repositories, pull requests (including comments, drafts, and pending reviews), branching models, and pipelines — enabling AI clients (Cursor, Claude Code, etc.) to safely automate Bitbucket workflows.

Related MCP server: Bitbucket MCP Server

Features

Full Bitbucket Cloud REST API v2.0 coverage for common workflows
Two transport modes: stdio (for local AI clients) and SSE/HTTP (for Docker/remote)
Draft pull requests and pending (unpublished) comments support
Cross-repository pending review detection
Branching model management at both repository and project levels
Pipeline management: trigger, stop, inspect runs, steps, and logs
Built-in health check with connectivity validation
Multi-project support with separate credentials per workspace
Docker-ready with health checks, resource limits, and non-root user

Requirements

Python 3.10+
uv package manager (pipx install uv or follow uv docs)
Bitbucket Cloud account with one of:
- App Password (recommended) for BITBUCKET_USERNAME / BITBUCKET_PASSWORD
- OAuth token via BITBUCKET_TOKEN

Recommended App Password Scopes

Scope	Required for
`repository:read`	Listing repos, branching models
`pullrequest:read`	Reading PRs, comments, diffs, commits
`pullrequest:write`	Creating/updating/merging PRs, comments
`pipeline:read`	Listing and inspecting pipeline runs
`pipeline:write`	Triggering and stopping pipelines

Installation

# Clone the repository
git clone https://github.com/webboy/mcp-bitbucket.git
cd mcp-bitbucket

# Install in editable mode
uv pip install -e .

Dependencies

Package	Purpose
`mcp[cli]>=1.2.0`	MCP SDK with CLI support
`httpx>=0.27`	HTTP client for Bitbucket API
`pydantic>=2.7`	Data validation and tool parameter schemas
`structlog>=24.1.0`	Structured logging
`uvicorn>=0.30.0`	ASGI server for SSE transport
`starlette>=0.37.0`	ASGI framework

Configuration

All configuration is done via environment variables:

Variable	Default	Description
`BITBUCKET_URL`	`https://api.bitbucket.org/2.0`	Bitbucket Cloud API base URL
`BITBUCKET_TOKEN`	—	OAuth Bearer token (alternative to username/password)
`BITBUCKET_USERNAME`	—	Bitbucket username (for App Password auth)
`BITBUCKET_PASSWORD`	—	Bitbucket App Password
`BITBUCKET_WORKSPACE`	—	Default workspace slug (optional but convenient)
`MCP_TRANSPORT`	`stdio`	Transport type: `stdio` or `sse`
`MCP_HOST`	`0.0.0.0`	Host to bind SSE server
`MCP_PORT`	`9000`	Port for SSE server
`FASTMCP_LOG_LEVEL`	`INFO`	Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`

Note: Either BITBUCKET_TOKEN or BITBUCKET_USERNAME + BITBUCKET_PASSWORD must be set. The BITBUCKET_USERNAME is also required for the getPendingReviewPRs tool to identify the current reviewer.

Running the Server

stdio mode (default)

BITBUCKET_USERNAME='<user>' \
BITBUCKET_PASSWORD='<app_password>' \
BITBUCKET_WORKSPACE='<workspace>' \
uv run mcp-bitbucket

The server uses stdio and waits for an MCP client to connect.

SSE/HTTP mode

BITBUCKET_USERNAME='<user>' \
BITBUCKET_PASSWORD='<app_password>' \
BITBUCKET_WORKSPACE='<workspace>' \
uv run mcp-bitbucket --transport sse --port 9000

The server starts an HTTP endpoint at http://0.0.0.0:9000/sse.

CLI Arguments

Argument	Default	Description
`--transport`	`stdio` (or `MCP_TRANSPORT` env)	`stdio` or `sse`
`--host`	`0.0.0.0` (or `MCP_HOST` env)	Bind host for SSE
`--port`	`9000` (or `MCP_PORT` env)	Bind port for SSE

Docker Usage (HTTP/SSE Transport)

The MCP server runs in a Docker container using HTTP/SSE transport, allowing a single long-running container that handles multiple client connections.

Quick Start

Create environment file:

cp .env.example .env
# Edit .env with your Bitbucket credentials

Build and start the container:

docker-compose up -d --build

Configure your AI client (e.g., Cursor ~/.cursor/mcp.json):

{
  "mcpServers": {
    "bitbucket": {
      "url": "http://localhost:9000/sse"
    }
  }
}

Restart your AI client — The Bitbucket MCP server should now be available!

Manual Docker Commands

# Build the image
docker build -t mcp-bitbucket:latest .

# Run with docker-compose
docker-compose up -d          # Start in background
docker-compose logs -f         # View logs
docker-compose down            # Stop

# Run directly
docker run -d \
  --name mcp-bitbucket \
  -p 9000:9000 \
  -e BITBUCKET_USERNAME=your_username \
  -e BITBUCKET_PASSWORD=your_app_password \
  -e BITBUCKET_WORKSPACE=your_workspace \
  -e MCP_TRANSPORT=sse \
  mcp-bitbucket:latest

Health Check

curl http://localhost:9000/sse

Container Management

docker ps | grep mcp-bitbucket   # Check if running
docker logs mcp-bitbucket        # View logs
docker restart mcp-bitbucket     # Restart
docker stop mcp-bitbucket && docker rm mcp-bitbucket  # Stop and remove

Benefits of HTTP/SSE Transport

Single container — one long-running container handles all requests
Multiple connections — clients can connect/reconnect without spawning new containers
Better performance — no container startup overhead per request
Easier debugging — view logs with docker logs
Health monitoring — built-in health checks (30s interval)
Resource limits — default 512MB memory limit, 128MB reserved

Multi-Project Setup

Run multiple containers with different Bitbucket credentials for separate projects:

Create project-specific env files:

cp .env.project1.example .env.project1
cp .env.project2.example .env.project2
# Edit each with the appropriate credentials

Start both containers:

docker compose -f docker-compose.project1.yml up -d
docker compose -f docker-compose.project2.yml up -d

Configure your AI client with both servers:

{
  "mcpServers": {
    "bitbucket-project1": {
      "url": "http://localhost:9000/sse"
    },
    "bitbucket-project2": {
      "url": "http://localhost:9001/sse"
    }
  }
}

Manage individually:

docker compose -f docker-compose.project1.yml down      # Stop project1
docker compose -f docker-compose.project2.yml logs -f    # Logs for project2

Tools Reference

All tools return MCP-compatible responses (text content with pretty-printed JSON, or raw text for diffs/logs). Errors are returned as structured ERROR: <ExceptionType>: <message> text.

Health (1 tool)

Tool	Description
`health`	Validates configuration and Bitbucket connectivity. Checks credentials and workspace access.

Repositories (2 tools)

Tool	Description
`listRepositories`	List repositories in a workspace. Filter by name (contains match) and limit results (1–100).
`getRepository`	Get full repository details by workspace and repo slug.

Pull Requests (17 tools)

Tool	Description
`getPullRequests`	List PRs for a repository. Filter by state (`OPEN`, `MERGED`, `DECLINED`, `SUPERSEDED`) and limit.
`createPullRequest`	Create a PR with title, description, source/target branches, optional reviewers. Supports `draft=True`.
`getPullRequest`	Get a single PR by ID.
`updatePullRequest`	Update PR title and/or description.
`getPullRequestActivity`	List activity feed (comments, approvals, status changes) for a PR.
`approvePullRequest`	Approve a PR as the current user.
`unapprovePullRequest`	Remove your approval from a PR.
`declinePullRequest`	Decline (close) a PR with an optional message.
`mergePullRequest`	Merge a PR with optional commit message and merge strategy (`merge-commit`, `squash`, `fast-forward`).
`getPullRequestComments`	List all comments on a PR.
`getPullRequestCommits`	List commits included in a PR.
`getPullRequestDiff`	Get the unified diff for a PR (raw text).
`addPullRequestComment`	Add a comment to a PR. Supports inline file/line comments and pending (draft) comments.
`addPendingPullRequestComment`	Add a pending (unpublished) comment to a PR. Shorthand for `addPullRequestComment` with `pending=True`.
`publishPendingComments`	Publish all pending comments on a PR.
`createDraftPullRequest`	Create a draft PR (shorthand for `createPullRequest` with `draft=True`).
`publishDraftPullRequest`	Publish a draft PR (convert to ready for review).
`convertTodraft`	Convert an open PR back to draft.
`getPendingReviewPRs`	List PRs awaiting your review across all (or specified) repositories in a workspace. Requires `BITBUCKET_USERNAME`.

Branching Models (7 tools)

Tool	Description
`getRepositoryBranchingModel`	Get the repository-level branching model (effective settings).
`getRepositoryBranchingModelSettings`	Get raw repository branching model settings (may inherit from project).
`updateRepositoryBranchingModelSettings`	Update repository branching model: development/production branches and branch types.
`getEffectiveRepositoryBranchingModel`	Resolve the effective branching model taking project-level inheritance into account.
`getProjectBranchingModel`	Get project-level branching model (defaults for repositories).
`getProjectBranchingModelSettings`	Get raw project branching model settings.
`updateProjectBranchingModelSettings`	Update project branching model: development/production branches and branch types.

Pipelines (8 tools)

Tool	Description
`listPipelineRuns`	List pipeline runs. Filter by status (`COMPLETED`, `FAILED`, `RUNNING`), target branch, trigger type (`PUSH`, `MANUAL`), and limit.
`getPipelineRun`	Get details for a specific pipeline run by UUID.
`runPipeline`	Trigger a pipeline run for a target branch/commit with optional pipeline variables.
`stopPipeline`	Stop a running pipeline by UUID.
`getPipelineSteps`	List all steps for a pipeline run.
`getPipelineStep`	Get details for a specific pipeline step.
`getPipelineStepLogs`	Get raw logs for a pipeline step (plain text).

Use with AI Clients

Cursor (Docker — Recommended)

See Docker Usage above. Configure ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bitbucket": {
      "url": "http://localhost:9000/sse"
    }
  }
}

Cursor / Claude Code (Direct UV — Development)

If the client runs inside the same environment (e.g., Ubuntu/WSL2), use an absolute path to uv:

{
  "mcpServers": {
    "bitbucket": {
      "command": "/home/<user>/.local/bin/uv",
      "args": ["run", "--with-editable", "/path/to/mcp-bitbucket", "mcp-bitbucket"],
      "env": {
        "BITBUCKET_URL": "https://api.bitbucket.org/2.0",
        "BITBUCKET_USERNAME": "your_username",
        "BITBUCKET_PASSWORD": "your_app_password",
        "BITBUCKET_WORKSPACE": "your_workspace",
        "FASTMCP_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Cursor on Windows (WSL Bridge)

If Cursor runs on Windows (outside WSL), bridge to WSL:

{
  "mcpServers": {
    "bitbucket": {
      "command": "wsl",
      "args": [
        "bash", "-lc",
        "cd /home/<user>/projects/mcp/mcp-bitbucket && BITBUCKET_USERNAME='your_username' BITBUCKET_PASSWORD='your_app_password' BITBUCKET_WORKSPACE='your_workspace' /home/<user>/.local/bin/uv run mcp-bitbucket"
      ]
    }
  }
}

Debug with MCP Inspector

Launch the MCP Inspector to interactively test tools:

BITBUCKET_USERNAME='<user>' \
BITBUCKET_PASSWORD='<app_password>' \
BITBUCKET_WORKSPACE='<workspace>' \
uv run --with mcp mcp dev src/app.py --with-editable .

Open the printed URL and call tools like health and listRepositories.

Architecture

mcp-bitbucket/
├── src/
│   ├── cli.py                # CLI entry point (argparse, transport selection)
│   ├── app.py                # FastMCP instance for MCP Inspector / dev
│   ├── server.py             # BitbucketMcpServer: tool registry + MCP handlers
│   ├── bitbucket_client.py   # BitbucketClient: thin httpx wrapper over REST v2.0
│   └── config.py             # BitbucketConfig dataclass + env loader
├── Dockerfile                # Python 3.10-slim, non-root user, SSE default
├── docker-compose.yml        # Default single-instance compose
├── docker-compose.project1.yml  # Multi-project compose (port 9000)
├── docker-compose.project2.yml  # Multi-project compose (port 9001)
├── .env.example              # Template for environment variables
├── pyproject.toml            # Project metadata and dependencies (hatchling)
└── LICENSE                   # MIT

Key Components

BitbucketConfig — Immutable dataclass holding API URL, credentials, and default workspace. Loaded from environment variables.
BitbucketClient — Synchronous HTTP client (httpx) that maps 1:1 to Bitbucket REST API v2.0 endpoints. Supports both token and App Password authentication.
BitbucketMcpServer — Registers all 35 tools with FastMCP, wraps each call in error handling (_safe), and manages both stdio and SSE transports.
cli.py — Entry point that parses CLI arguments, initializes config and server, and runs the selected transport.

Troubleshooting

Problem	Solution
No tools visible in client	Ensure the command starts in your environment (use absolute path to `uv`). Set `FASTMCP_LOG_LEVEL=DEBUG`.
401/403 errors	Verify App Password scopes and workspace/repo access.
Workspace missing errors	Set `BITBUCKET_WORKSPACE` env var or pass `workspace` argument to tools.
Inspector won't connect	Ensure proxy health at `http://localhost:6277/health` returns `{"status":"ok"}`. If bridging from Windows to WSL, enable localhost forwarding.
Container not starting	Check `docker logs mcp-bitbucket` for startup errors. Verify `.env` file exists and is populated.
`getPendingReviewPRs` fails	Requires `BITBUCKET_USERNAME` to be set (identifies the current reviewer).

Security

Treat App Passwords and OAuth tokens as secrets. Never commit .env files — they are in .gitignore.
The Docker image runs as a non-root user (mcp, UID 1000).
Rotate credentials immediately if exposed.
The server does not store or log credentials.

License

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/webboy/mcp-bitbucket'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

mcp-bitbucket

Table of Contents

Features

Requirements

Recommended App Password Scopes

Installation

Dependencies

Configuration

Running the Server

stdio mode (default)

SSE/HTTP mode

CLI Arguments

Docker Usage (HTTP/SSE Transport)

Quick Start

Manual Docker Commands

Health Check

Container Management

Benefits of HTTP/SSE Transport

Multi-Project Setup

Tools Reference

Health (1 tool)

Repositories (2 tools)

Pull Requests (17 tools)

Branching Models (7 tools)

Pipelines (8 tools)

Use with AI Clients

Cursor (Docker — Recommended)

Cursor / Claude Code (Direct UV — Development)

Cursor on Windows (WSL Bridge)

Debug with MCP Inspector

Architecture

Key Components

Troubleshooting

Security

License

Maintenance

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API