Which integrations are available for this server?

Provides tools for interacting with Bitbucket Cloud and Server APIs, enabling management of repositories, pull requests, branches, tags, commits, pipelines, source code, and more.

How do I use Bitbucket MCP Server?

1. Click on "Deploy 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., "@Bitbucket MCP Server list pull requests in workspace my-workspace" 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.

Bitbucket MCP Server

by ATERCATES

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

Bitbucket MCP Server

A Model Context Protocol (MCP) server for integrating with Bitbucket Cloud and Server APIs. This MCP server enables AI assistants like Claude and Cursor to interact with your Bitbucket repositories, pull requests, pipelines, and other resources.

Features

✨ Comprehensive Bitbucket Integration - 59 tools covering repositories, PRs, branches, commits, pipelines, and more

🔒 Secure Authentication - App password tokens or basic auth with granular permission control via Bitbucket

📝 Well-Documented - Complete API reference, architecture guides, and deployment instructions in /docs

🧪 Fully Tested - Comprehensive unit test suite with full tool coverage (Vitest)

⚡ Modular Design - Clean, maintainable architecture organized by feature domain (11 handler modules)

🛡️ Safety First - 3 operation modes (readonly, safe, full) with fine-grained tool control

🚀 Production Ready - Built with pnpm, ESLint, Prettier, and modern TypeScript

Related MCP server: bitbucket-mcp-server

Quick Start

Installation

# Option 1: Global install
pnpm add -g @atercates/bitbucket-mcp

# Option 2: Use with NPX (no installation required)
npx -y @atercates/bitbucket-mcp@latest

# Option 3: Local development
git clone https://github.com/ATERCATES/bitbucket-mcp.git
cd bitbucket-mcp
pnpm install
pnpm build
pnpm start

Configuration

REQUIRED Environment Variables:

# Authentication (Personal API Token ONLY)
export BITBUCKET_USERNAME="user@example.com"    # Your Atlassian email address
export BITBUCKET_API_TOKEN="ATBBxxxxxxxxxxxxx"  # Personal API Token (starts with ATBB or ATATT)

# Default Workspace (optional but recommended)
export BITBUCKET_WORKSPACE="my-workspace"       # Your default workspace name

Optional Configuration:

# Server Operation Mode
export BITBUCKET_MODE="safe"  # readonly | safe (default) | full

# Fine-grained tool control
export BITBUCKET_ENABLED_TOOLS="getPullRequest,listPullRequests,createPullRequest"
export BITBUCKET_DISABLED_TOOLS="deleteBranch,deleteRepository"

# Custom API URL (for self-hosted Bitbucket Server)
export BITBUCKET_URL="https://bitbucket.company.com/rest/api/2.0"

🔐 Operation Modes:

readonly - Only GET operations (no modifications)
safe - GET + POST/PUT operations, but no deletes (default)
full - All operations including dangerous deletes

⚠️ Authentication Notes:

This MCP server strictly enforces Personal API Tokens (starting with ATBB or ATATT)
App Passwords and Access Tokens (BBAT-xxx) are NOT supported
BITBUCKET_USERNAME must be your Atlassian email address

Running the Server

# If installed globally
bitbucket-mcp

# If using NPX
npx -y @atercates/bitbucket-mcp@latest

# If installed locally
pnpm start

The server will start and listen for MCP protocol connections via stdio.

Integration with MCP Clients

Claude / Cursor Configuration

Add to your MCP configuration (.mcp.json or similar):

{
  "mcpServers": {
    "bitbucket": {
      "command": "bitbucket-mcp",
      "env": {
        "BITBUCKET_USERNAME": "user@example.com",
        "BITBUCKET_API_TOKEN": "ATBBxxxxxxxxxxxxx",
        "BITBUCKET_WORKSPACE": "my-workspace",
        "BITBUCKET_MODE": "safe"
      }
    }
  }
}

Examples:

// Read-only mode (safe for production analysis)
{
  "BITBUCKET_MODE": "readonly"
}

// Safe mode (default - no deletes)
{
  "BITBUCKET_MODE": "safe"
}

// Full mode (all operations including deletes)
{
  "BITBUCKET_MODE": "full"
}

// Fine-grained control (only specific tools)
{
  "BITBUCKET_ENABLED_TOOLS": "getPullRequest,listPullRequests,getPullRequestDiff"
}

// Blacklist specific tools
{
  "BITBUCKET_DISABLED_TOOLS": "deleteBranch,deleteRepository,deleteTag"
}

Or with npx:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@atercates/bitbucket-mcp@latest"],
      "env": {
        "BITBUCKET_USERNAME": "user@example.com",
        "BITBUCKET_API_TOKEN": "ATBBxxxxxxxxxxxxx",
        "BITBUCKET_WORKSPACE": "my-workspace",
        "BITBUCKET_MODE": "safe"
      }
    }
  }
}

Available Tools

The server provides 59 tools organized into 11 categories:

Category	Tools
Repositories	List, get, create repositories
Pull Requests	Create, approve, merge, decline PRs
PR Comments	Create, delete PR comments
PR Tasks	Create, update, delete PR tasks (TODOs)
PR Content	Get diffs and commits
Branches & Tags	List, create, delete branches and tags
Commits	List commits and commit details
Pipelines	List, run, stop pipeline runs
Source Code	Read file content from repositories
Users	Get current user and workspace info
Branching Model	Get branching strategy configuration

Complete reference: See docs/TOOLS.md

Environment Variables

Authentication (Required)

BITBUCKET_USERNAME - Your Atlassian email address (e.g., user@example.com)
BITBUCKET_API_TOKEN - Personal API Token starting with ATBB- or ATATT-

How to create:

Go to https://bitbucket.org/account/settings/app-passwords/
Click "Create API token"
Select permissions: Repositories (Read, Write), Pull requests (Read, Write), Pipelines (Read)
Copy the generated token
Set expiration date (max 1 year)

Configuration (Optional)

BITBUCKET_WORKSPACE - Default workspace name (can be provided per-tool call)
BITBUCKET_URL - API base URL (default: https://api.bitbucket.org/2.0)
BITBUCKET_MODE - Operation mode: readonly, safe (default), or full
BITBUCKET_ENABLED_TOOLS - Comma-separated list of tools to enable (whitelist mode)
BITBUCKET_DISABLED_TOOLS - Comma-separated list of tools to disable (blacklist mode)

Logging (Optional)

BITBUCKET_LOG_DISABLE - Disable file logging (default: false)
BITBUCKET_LOG_FILE - Custom log file path
BITBUCKET_LOG_DIR - Custom log directory
BITBUCKET_LOG_PER_CWD - Create per-directory logs (default: false)

Documentation

Tools Reference - Complete API documentation for all 59 tools with examples
Architecture Guide - Technical design, modular structure, and extension guide

Development

Prerequisites

Node.js 24
pnpm (or npm)

Setup

git clone https://github.com/ATERCATES/bitbucket-mcp.git
cd bitbucket-mcp
pnpm install

Build

pnpm build          # Compile TypeScript
pnpm lint           # Run ESLint  
pnpm format         # Format with Prettier
pnpm format:check   # Check formatting

Testing

pnpm test           # Run Vitest suite
pnpm test:watch     # Watch mode

Running in Development

pnpm dev            # Run with tsx (watch mode, no build required)
# OR
pnpm build && pnpm start

MCP Inspector (Debugging)

pnpm inspector      # Launch interactive MCP inspector to test tools

Project Structure

src/
├─ index.ts              # Entry point
├─ server.ts             # MCP server orchestration
├─ client.ts             # Bitbucket API client
├─ config.ts             # Configuration management
├─ logger.ts             # File-based logging
├─ types.ts              # TypeScript definitions
├─ schemas.ts            # JSON schemas
├─ utils.ts              # Utilities
├─ pagination.ts         # Pagination helper
└─ handlers/             # Feature modules
   ├─ repositories.ts
   ├─ pull-requests.ts
   ├─ pr-comments.ts
   ├─ pr-tasks.ts
   ├─ pr-content.ts
   ├─ refs.ts
   ├─ commits.ts
   ├─ pipelines.ts
   ├─ source.ts
   ├─ users.ts
   ├─ branching-model.ts
   └─ index.ts

docs/
├─ TOOLS.md              # Tools reference
└─ architecture/
   └─ ARCHITECTURE.md    # Technical design

__tests__/
├─ test-utils.ts         # Test helpers
└─ handlers/             # Handler tests

Architecture

The server uses a modular handler-based architecture:

MCP Client → Server → Handler Modules → BitbucketClient → Bitbucket API

Each handler module:

Defines tools (names, schemas, descriptions)
Implements handlers (async functions)
Can mark tools as dangerous
Is automatically registered by the server

See docs/architecture/ARCHITECTURE.md for details.

Dangerous Operations

Some tools that perform destructive operations are marked as dangerous:

deletePullRequestComment
deletePullRequestTask
deleteBranch
deleteTag

These require BITBUCKET_MODE=full to use, preventing accidental data loss.

Troubleshooting

Authentication Issues

Test your credentials:

# Test Personal API Token
curl -u "user@example.com:ATBBxxxxxx" \
  https://api.bitbucket.org/2.0/user

# Should return your user info if credentials are valid

Common errors:

"BITBUCKET_USERNAME is required"
- Set BITBUCKET_USERNAME to your Atlassian email address.
"BITBUCKET_API_TOKEN is required"
- Set BITBUCKET_API_TOKEN to your Personal API Token (starts with ATBB).
"Invalid token format"
- The token must start with ATBB. App passwords and Access Tokens are not supported.
"401 Unauthorized"
- Check username/token are correct
- Verify token hasn't expired (max 1 year)
- Ensure you are using your email address as username

View Logs

macOS:

tail -f ~/Library/Logs/bitbucket-mcp/bitbucket.log

Linux:

tail -f ~/.local/state/bitbucket-mcp/bitbucket.log

Windows:

Get-Content -Path "$env:LOCALAPPDATA\bitbucket-mcp\bitbucket.log" -Tail 50 -Wait

Self-Hosted Bitbucket

For self-hosted Bitbucket Server, set the API URL:

BITBUCKET_URL=https://bitbucket.mycompany.com/rest/api/2.0 bitbucket-mcp

License

MIT License - See LICENSE file for details.

Support

🔧 Check docs/TOOLS.md for tool documentation with examples
🏗️ Review docs/architecture/ARCHITECTURE.md for technical details
🐛 Enable logging with BITBUCKET_LOG_DISABLE=false for debugging
🐞 Report issues at https://github.com/ATERCATES/bitbucket-mcp/issues

Architecture: Modular handler-based design with 11 feature modules
Test Framework: Vitest
Package Manager: pnpm

Available Tools

59 tools

addPullRequestCommentA

Add a comment to a pull request: general, inline on a diff line, or a reply to an existing comment (pass parent)

Inputs: content (required), repo_slug (required), workspace (required), pull_request_id (required), +3 more.

approvePullRequestC

Approve a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required), all, +2 more.

bitbucket_api_requestA

Make an authenticated GET request to the Bitbucket Cloud API. Use this tool for endpoints not covered by other specific tools, or to access raw API data. The response is returned as a JSON string.

Inputs: endpoint (required), params.

convertTodraftB

Convert a regular pull request to draft status

Inputs: repo_slug (required), workspace (required), pull_request_id (required).

createBranchC

Create a new branch in a repository

Inputs: name (required), target (required), repo_slug (required), workspace (required).

createDraftPullRequestB

Create a new draft pull request

Inputs: title (required), repo_slug (required), workspace (required), description (required), +3 more.

createPullRequestC

Create a new pull request

Inputs: title (required), repo_slug (required), workspace (required), description (required), +5 more.

createPullRequestTaskA

Create a task on a pull request

Inputs: content (required), repo_slug (required), workspace (required), pull_request_id (required), +2 more.

createTagC

Create a new tag in a repository

Inputs: name (required), target (required), repo_slug (required), workspace (required), +1 more.

declinePullRequestC

Decline a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required).

getBranchB

Get a specific branch from a repository

Inputs: name (required), repo_slug (required), workspace (required).

getCommitA

Get a specific commit from a repository

Inputs: sha (required), repo_slug (required), workspace (required).

getCurrentUserA

Get the currently authenticated Bitbucket user

Inputs: no named parameters.

getEffectiveDefaultReviewersB

Get effective default reviewers for a repository

Inputs: repo_slug (required), workspace (required).

getEffectiveRepositoryBranchingModelC

Get the effective branching model for a repository

Inputs: repo_slug (required), workspace (required).

getFileContentA

Get the content of a file from a Bitbucket repository

Inputs: path (required), repo_slug (required), workspace (required), commit.

getPendingReviewPRsA

List all open pull requests in the workspace where the authenticated user is a reviewer and has not yet approved.

Inputs: limit, workspace, repositoryList.

getPipelineRunB

Get details for a specific pipeline run

Inputs: repo_slug (required), workspace (required), pipeline_uuid (required), all, +2 more.

getPipelineStepB

Get details for a specific pipeline step

Inputs: repo_slug (required), step_uuid (required), workspace (required), pipeline_uuid (required).

getPipelineStepLogsB

Get logs for a specific pipeline step

Inputs: repo_slug (required), step_uuid (required), workspace (required), pipeline_uuid (required), +5 more.

getPipelineStepsB

List steps for a pipeline run

Inputs: repo_slug (required), workspace (required), pipeline_uuid (required).

getProjectBranchingModelC

Get the branching model for a project

Inputs: workspace (required), project_key (required).

getProjectBranchingModelSettingsC

Get the branching model config for a project

Inputs: workspace (required), project_key (required).

getPullRequestC

Get details for a specific pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required), all, +2 more.

getPullRequestActivityB

Get activity log for a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required), all, +2 more.

getPullRequestCommentB

Get a specific comment on a pull request

Inputs: repo_slug (required), workspace (required), comment_id (required), pull_request_id (required).

getPullRequestCommentsB

List comments on a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required), all, +2 more.

getPullRequestCommitsB

Get commits on a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required), all, +2 more.

getPullRequestDiffB

Get diff for a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required).

getPullRequestDiffStatB

Get diff statistics for a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required), all, +2 more.

getPullRequestPatchC

Get patch for a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required).

getPullRequestsC

Get pull requests for a repository

Inputs: repo_slug (required), workspace (required), all, page, +3 more.

getPullRequestStatusesB

List commit statuses associated with a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required), all, +2 more.

getPullRequestTaskB

Get a specific task on a pull request

Inputs: task_id (required), repo_slug (required), workspace (required), pull_request_id (required).

getPullRequestTasksC

List tasks on a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required).

getRepositoryC

Get repository details

Inputs: repo_slug (required), workspace (required).

getRepositoryBranchingModelC

Get the branching model for a repository

Inputs: repo_slug (required), workspace (required).

getRepositoryBranchingModelSettingsC

Get the branching model config for a repository

Inputs: repo_slug (required), workspace (required).

getTagA

Get a specific tag from a repository

Inputs: name (required), repo_slug (required), workspace (required).

listBranchesB

List branches in a repository

Inputs: repo_slug (required), workspace (required), q, all, +2 more.

listCommitsC

List commits in a repository

Inputs: repo_slug (required), workspace (required), all, page, +4 more.

listPipelineRunsA

List pipeline runs for a repository

Inputs: repo_slug (required), workspace (required), all, page, +5 more.

listRepositoriesC

List Bitbucket repositories

Inputs: all, name, page, limit, +2 more.

listWorkspacesA

List Bitbucket workspaces the user has access to

Inputs: all, page, pagelen.

mergePullRequestC

Merge a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required), message, +2 more.

publishDraftPullRequestB

Publish a draft pull request to make it ready for review

Inputs: repo_slug (required), workspace (required), pull_request_id (required).

removeRequestChangesA

Remove request changes from a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required).

reopenCommentB

Reopen a resolved comment thread on a pull request

Inputs: repo_slug (required), workspace (required), comment_id (required), pull_request_id (required).

requestChangesC

Request changes on a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required).

resolveCommentB

Resolve a comment thread on a pull request

Inputs: repo_slug (required), workspace (required), comment_id (required), pull_request_id (required).

runPipelineC

Trigger a new pipeline run

Inputs: target (required), repo_slug (required), workspace (required), variables.

stopPipelineB

Stop a running pipeline

Inputs: repo_slug (required), workspace (required), pipeline_uuid (required).

unapprovePullRequestB

Remove approval from a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required), all, +2 more.

updateProjectBranchingModelSettingsC

Update the branching model config for a project

Inputs: workspace (required), project_key (required), production, development, +1 more.

updatePullRequestC

Update a pull request

Inputs: repo_slug (required), workspace (required), pull_request_id (required), draft, +5 more.

updatePullRequestCommentC

Update a comment on a pull request

Inputs: content (required), repo_slug (required), workspace (required), comment_id (required), +1 more.

updatePullRequestTaskB

Update a task on a pull request

Inputs: task_id (required), repo_slug (required), workspace (required), pull_request_id (required), +2 more.

updateRepositoryBranchingModelSettingsB

Update the branching model config for a repository

Inputs: repo_slug (required), workspace (required), production, development, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.9/5.0

Scored 2026-09-09 18:45 across 59 tools

Disambiguation3/5

Most tools are cleanly separated by resource and action, but the five branching-model tools (project vs repository, model vs settings vs effective) have overlapping descriptions that an agent would struggle to distinguish. Comments, tasks, and PR review actions are otherwise fairly unambiguous.

Naming Consistency3/5

The majority of tools follow a get/list/create/update/action + resource pattern, making the set mostly predictable. However, convertTodraft, getPendingReviewPRs, resolveComment/reopenComment, and the snake_case bitbucket_api_request break the convention.

Tool Count2/5

With 59 tools the server is substantially over the practical MCP threshold; even though each tool maps to a distinct API operation, the volume is heavy for an agent to scan and select from. Some closely related branching-model and comment tools could be consolidated.

Completeness3/5

The pull request lifecycle is very complete, and pipelines, branches, tags, commits, and comments have solid coverage for common tasks. However, repository mutation is absent and delete operations are missing for branches, tags, comments, and tasks, while the generic fallback is GET-only, so these gaps cannot be worked around.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

OneSchema MCP Server
co.oneschema
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Data Platforms App Automation
1
https://api.oneschema.co/mcp
neverinfamous-memory-journal-mcp
ai.smithery
A MCP server built for developers enabling Git based project management with project and personal…
Version Control Developer Tools Project Management
320
https://server.smithery.ai/@neverinfamous/memory-journal-mcp/mcp
SmartBear MCP
com.smartbear
MCP server for AI access to SmartBear tools, including BugSnag, Reflect, Swagger, PactFlow, QTM4J.
Monitoring Testing & QA Tools API Testing
144
https://zephyr.mcp.smartbear.com/mcp
Station Zero
services.stationzero
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Knowledge & Memory File Systems Workplace & Productivity
1
https://stationzero.services/mcp

Related MCP Servers

bitbucket-python-mcp
Version Control Developer Tools
clikader
A
license
A
quality
D
maintenance
An MCP server for BitBucket Cloud operations that enables AI agents to manage repositories, branches, pull requests, and search code.
Updated 10 months ago (2026-01-24 05:57 UTC)
32
MIT
bitbucket-mcp-server
Version Control CI/CD & DevOps
fnops
A
license
B
quality
D
maintenance
MCP server for Bitbucket Cloud that enables AI agents to manage repositories, branches, pull requests, and deployments via typed tools.
Updated 8 months ago (2026-03-16 13:35 UTC)
17
45 npm
ISC
BitBucket-MCP-To-Review-PRs
Version Control Developer Tools
arslanismail
A
license
Not graded
quality
D
maintenance
A read-only MCP server for the Bitbucket Cloud REST API v2.0 that enables AI assistants to browse workspaces, repositories, and review pull requests.
Updated 8 months ago (2026-03-26 20:23 UTC)
45 npm
ISC
mcp-bitbucket
Version Control CI/CD & DevOps
webboy
A
license
Not graded
quality
D
maintenance
MCP server for Bitbucket Cloud that exposes 35 tools covering repositories, pull requests, branching models, and pipelines, enabling AI clients to automate Bitbucket workflows.
Updated 7 months ago (2026-04-01 13:41 UTC)
3
MIT

Bitbucket MCP Server

Features

Quick Start

Installation

Configuration

Running the Server

Integration with MCP Clients

Claude / Cursor Configuration

Available Tools

Environment Variables

Authentication (Required)

Configuration (Optional)

Logging (Optional)

Documentation

Development

Prerequisites

Setup

Build

Testing

Running in Development

MCP Inspector (Debugging)

Project Structure

Architecture

Dangerous Operations

Troubleshooting

Authentication Issues

View Logs

Self-Hosted Bitbucket

License

Support

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

bitbucket-python-mcp

bitbucket-mcp-server

BitBucket-MCP-To-Review-PRs

mcp-bitbucket