Bitbucket MCP Server

A Model Context Protocol server for AI agents to interact with Bitbucket Cloud Pull Requests

---

Overview

This MCP server exposes read-only Bitbucket Cloud Pull Request operations as tools that AI agents (Claude, etc.) can invoke over stdio. It connects your AI workflow directly to your Bitbucket repositories.

Capabilities

Category	Operations
Pull Requests	List, get details, get full expanded PR
Code Review	Diff, patch, file changes, commits
Collaboration	Comments, activities, participants, reviewers
Workflow	Status, tasks, task count
Auth	Token validation

---

Quick Start

Prerequisites

• Node.js 24.13+ (see .nvmrc)
• A Bitbucket Cloud App Password with repository read permissions

Installation

git clone <repository-url>
cd bitbucket-mcp
npm install

Configuration

Create a .env file in the project root:

BITBUCKET_MCP_EMAIL=your_email@example.com
BITBUCKET_MCP_TOKEN=your_app_password

# Optional defaults (avoids passing workspace/repo on every call)
DEFAULT_WORKSPACE=my-workspace
DEFAULT_REPO=my-repo

Or export as environment variables (takes priority over .env):

export BITBUCKET_MCP_EMAIL=your_email@example.com
export BITBUCKET_MCP_TOKEN=your_app_password

Run

# Production
npm start

# Development (hot reload)
npm run dev

# Build
npm run build

---

MCP Client Configuration

Claude Code

Add the following to your Claude Code MCP settings (~/.claude/settings.json or project .claude/settings.json):

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": [
        "/absolute/path/to/bitbucket-mcp/dist/index.js"
      ],
      "env": {
        "BITBUCKET_MCP_EMAIL": "your_email@example.com",
        "BITBUCKET_MCP_TOKEN": "your_bitbucket_app_password",
        "DEFAULT_WORKSPACE": "your-workspace",
        "DEFAULT_REPO": "your-repo"
      }
    }
  }
}

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": [
        "/absolute/path/to/bitbucket-mcp/dist/index.js"
      ],
      "env": {
        "BITBUCKET_MCP_EMAIL": "your_email@example.com",
        "BITBUCKET_MCP_TOKEN": "your_bitbucket_app_password",
        "DEFAULT_WORKSPACE": "your-workspace",
        "DEFAULT_REPO": "your-repo"
      }
    }
  }
}

Note: You must build the project first (npm run build) since the config points to dist/index.js. Use the absolute path to the compiled entry point. Setting DEFAULT_WORKSPACE and DEFAULT_REPO is optional but convenient — it lets you omit those parameters from every tool call.

---

Available Tools

Authentication

Tool	Description
validate_token	Verify credentials are valid

Pull Request Discovery

Tool	Description	Key Parameters
list_pull_requests	List PRs in a repository	workspace, repository, state?, author?
get_pull_request	Get PR summary	workspace, repository, pullRequestId
get_full_pull_request	Get PR with all fields expanded	workspace, repository, pullRequestId
get_pull_request_status	Get PR state (open/merged/declined)	workspace, repository, pullRequestId

Code Changes

Tool	Description	Key Parameters
get_pull_request_diff	Get unified diff	workspace, repository, pullRequestId, path?, context?
get_pull_request_patch	Get raw patch file	workspace, repository, pullRequestId
get_pull_request_changes	List modified files	workspace, repository, pullRequestId
get_pull_request_commits	List commits in PR	workspace, repository, pullRequestId

Collaboration

Tool	Description	Key Parameters
get_pull_request_comments	Get all comments	workspace, repository, pullRequestId
get_pull_request_comment	Get a specific comment	workspace, repository, pullRequestId, commentId
get_pull_request_activities	Get activity feed	workspace, repository, pullRequestId
get_pull_request_participants	Get all participants	workspace, repository, pullRequestId
get_pull_request_reviewers	Get assigned reviewers	workspace, repository, pullRequestId

Tasks

Tool	Description	Key Parameters
get_pull_request_tasks	Get PR tasks	workspace, repository, pullRequestId
get_pull_request_task_count	Get task count	workspace, repository, pullRequestId

Pagination: Tools that return lists support limit and start parameters.

---

Example

{
  "name": "list_pull_requests",
  "arguments": {
    "workspace": "my-team",
    "repository": "backend-api",
    "state": "open"
  }
}

Response:

{
  "pull_requests": [
    {
      "id": 42,
      "title": "feat: add user authentication",
      "state": "OPEN",
      "author": { "display_name": "Jane Doe" },
      "source": { "branch": { "name": "feature/auth" } },
      "destination": { "branch": { "name": "main" } }
    }
  ],
  "count": 1
}

---

Development

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Integration tests (requires valid credentials)
npm run test:integration

# Type check
npx tsc --noEmit

# Coverage report
npm run test:coverage

Project Structure

src/
├── index.ts             # MCP server & tool schema definitions
├── router.ts            # Tool name → API method dispatcher
├── bitbucket-client.ts  # Axios HTTP client for Bitbucket Cloud API
└── config.ts            # Credential & default config loading
tests/
├── unit/                # Mocked unit tests
└── integration/         # Live API tests

---

Authentication Details

This server uses HTTP Basic Authentication with the Bitbucket Cloud REST API v2.0:

• Username = your Bitbucket email
• Password = an App Password

Credential resolution order:

1. Environment variables (BITBUCKET_MCP_EMAIL + BITBUCKET_MCP_TOKEN)
2. .env file in project root
3. Interactive prompt (development only)

---

License

MIT