bitbucket-mcp/README.md

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

Get up and running in 4 steps:

1. Prerequisites

• Node.js 24.13+ (see .nvmrc)
• A Bitbucket Cloud API Token with repository read permissions (note: App Passwords are no longer supported by Bitbucket)

2. Install & Build

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

3. Configure in Claude

Add the MCP server to your Claude configuration:

Claude Code — edit ~/.claude/settings.json (global) or .claude/settings.json (per-project):

{
  "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_api_token",
        "DEFAULT_WORKSPACE": "your-workspace",
        "DEFAULT_REPO": "your-repo"
      }
    }
  }
}

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (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_api_token",
        "DEFAULT_WORKSPACE": "your-workspace",
        "DEFAULT_REPO": "your-repo"
      }
    }
  }
}

Important:

• Replace /absolute/path/to/bitbucket-mcp with the actual absolute path where you cloned the repo.
• DEFAULT_WORKSPACE and DEFAULT_REPO are optional but convenient — they let you omit those parameters from every tool call.
• Get your API token from Atlassian API Tokens.

4. Verify

Restart Claude (or reload MCP servers), then ask Claude to run the validate_token tool. If credentials are correct, it will confirm the connection is working.

---

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

Running Locally

For development, you can use a .env file instead of configuring credentials in the MCP client:

BITBUCKET_MCP_EMAIL=your_email@example.com
BITBUCKET_MCP_TOKEN=your_api_token
DEFAULT_WORKSPACE=my-workspace
DEFAULT_REPO=my-repo

# Run with hot reload
npm run dev

# Or run directly
npm start

Testing

# 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 API Token

Note: Bitbucket no longer supports App Passwords. You must use an API Token instead.

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