Skip to main content
Glama

Bitbucket MCP Server

by bobmaertz

Bitbucket MCP Server

A Model Context Protocol (MCP) server that provides LLM applications with access to Bitbucket Cloud repositories through a standardized interface.

Overview

This project implements an MCP server for Bitbucket Cloud REST API 2.0, enabling AI assistants like Claude to interact with Bitbucket repositories, pull requests, comments, tasks, and branches.

Architecture

The project is organized as a monorepo with two main packages:

  • bitbucket-api: Isolated REST API client for Bitbucket Cloud

  • bitbucket-mcp-server: MCP server implementation using the API client

Features

Supported Operations

Pull Requests

  • List pull requests for a repository

  • Get details of a specific pull request

  • Get commits in a pull request

  • Get diff for a pull request

Comments

  • List all comments on a pull request

  • Get a specific comment

  • Create new comments

  • Delete comments

Tasks

  • List all tasks on a pull request

  • Get a specific task

  • Create new tasks

  • Update task state (resolve/unresolve)

Branches

  • List repository branches

  • Get details of a specific branch

  • Create new branches

Installation

Prerequisites

  • Node.js 18 or higher

  • npm or pnpm

  • Bitbucket Cloud account with app password

Setup

  1. Clone the repository:

git clone <repository-url> cd bitbucket_mcp
  1. Install dependencies:

npm install
  1. Build the packages:

npm run build

Configuration

Environment Variables

Create a .env file or set the following environment variables:

# Required BITBUCKET_WORKSPACE=your-workspace BITBUCKET_USERNAME=your-username BITBUCKET_APP_PASSWORD=your-app-password # Optional BITBUCKET_DEFAULT_REPO=your-default-repo LOG_LEVEL=info

Creating a Bitbucket App Password

  1. Go to Bitbucket Settings > Personal Bitbucket settings > App passwords

  2. Click "Create app password"

  3. Give it a label (e.g., "MCP Server")

  4. Select the required permissions:

    • Repositories: Read, Write

    • Pull requests: Read, Write

    • Issues: Read (if using tasks)

  5. Copy the generated password

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{ "mcpServers": { "bitbucket": { "command": "node", "args": ["/absolute/path/to/bitbucket_mcp/packages/bitbucket-mcp-server/dist/index.js"], "env": { "BITBUCKET_WORKSPACE": "your-workspace", "BITBUCKET_USERNAME": "your-username", "BITBUCKET_APP_PASSWORD": "your-app-password" } } } }

Development

Project Structure

bitbucket_mcp/ ├── packages/ │ ├── bitbucket-api/ # REST API client package │ │ ├── src/ │ │ │ ├── client.ts # HTTP client │ │ │ ├── auth.ts # Authentication │ │ │ ├── types/ # TypeScript types │ │ │ └── resources/ # API resources │ │ └── package.json │ │ │ └── bitbucket-mcp-server/ # MCP server package │ ├── src/ │ │ ├── index.ts # Entry point │ │ ├── server.ts # Server setup │ │ ├── tools/ # MCP tools │ │ └── resources/ # MCP resources │ └── package.json │ ├── docs/ │ └── ai/ │ ├── DESIGN.md # Design document │ └── IMPLEMENTATION_PLAN.md └── package.json # Root workspace config

Available Scripts

# Build all packages npm run build # Run tests npm test # Lint code npm run lint # Format code npm run format # Clean build artifacts npm run clean

Running the MCP Server

For development:

cd packages/bitbucket-mcp-server npm run dev

For production:

node packages/bitbucket-mcp-server/dist/index.js

Usage Examples

Once configured with an MCP client like Claude Desktop, you can use natural language to interact with Bitbucket:

  • "List all open pull requests in the main repository"

  • "Show me the comments on pull request #42"

  • "What tasks are pending on PR #15?"

  • "List all branches in the repository"

  • "Create a comment on PR #10 saying 'Looks good to me!'"

Testing

Unit Tests

npm test

Integration Tests

Set up test environment variables and run:

npm run test:integration

Documentation

MCP Tools Reference

Pull Request Tools

bitbucket_list_pull_requests

List pull requests for a repository.

Parameters:

  • workspace (string, required): Bitbucket workspace ID

  • repo_slug (string, required): Repository slug

  • state (string, optional): Filter by state (OPEN, MERGED, DECLINED)

bitbucket_get_pull_request

Get details of a specific pull request.

Parameters:

  • workspace (string, required): Bitbucket workspace ID

  • repo_slug (string, required): Repository slug

  • pr_id (number, required): Pull request ID

bitbucket_get_pr_commits

Get commits in a pull request.

Parameters:

  • workspace (string, required): Bitbucket workspace ID

  • repo_slug (string, required): Repository slug

  • pr_id (number, required): Pull request ID

bitbucket_get_pr_diff

Get diff for a pull request.

Parameters:

  • workspace (string, required): Bitbucket workspace ID

  • repo_slug (string, required): Repository slug

  • pr_id (number, required): Pull request ID

Comment Tools

bitbucket_list_pr_comments

List all comments on a pull request.

Parameters:

  • workspace (string, required): Bitbucket workspace ID

  • repo_slug (string, required): Repository slug

  • pr_id (number, required): Pull request ID

bitbucket_create_comment

Create a new comment on a pull request.

Parameters:

  • workspace (string, required): Bitbucket workspace ID

  • repo_slug (string, required): Repository slug

  • pr_id (number, required): Pull request ID

  • content (string, required): Comment content (markdown supported)

Task Tools

bitbucket_list_pr_tasks

List all tasks on a pull request.

Parameters:

  • workspace (string, required): Bitbucket workspace ID

  • repo_slug (string, required): Repository slug

  • pr_id (number, required): Pull request ID

bitbucket_update_task

Update a task's state.

Parameters:

  • workspace (string, required): Bitbucket workspace ID

  • repo_slug (string, required): Repository slug

  • pr_id (number, required): Pull request ID

  • task_id (number, required): Task ID

  • state (string, required): New state (RESOLVED, UNRESOLVED)

Branch Tools

bitbucket_list_branches

List repository branches.

Parameters:

  • workspace (string, required): Bitbucket workspace ID

  • repo_slug (string, required): Repository slug

bitbucket_get_branch

Get details of a specific branch.

Parameters:

  • workspace (string, required): Bitbucket workspace ID

  • repo_slug (string, required): Repository slug

  • branch_name (string, required): Branch name

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests

  5. Submit a pull request

License

MIT

Support

For issues and questions:

Acknowledgments

-
security - not tested
F
license - not found
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI assistants to interact with Bitbucket Cloud repositories, allowing users to manage pull requests, comments, tasks, and branches through natural language commands.

  1. Overview
    1. Architecture
      1. Features
        1. Supported Operations
      2. Installation
        1. Prerequisites
        2. Setup
      3. Configuration
        1. Environment Variables
        2. Creating a Bitbucket App Password
        3. MCP Client Configuration
      4. Development
        1. Project Structure
        2. Available Scripts
        3. Running the MCP Server
      5. Usage Examples
        1. Testing
          1. Unit Tests
          2. Integration Tests
        2. Documentation
          1. MCP Tools Reference
            1. Pull Request Tools
            2. Comment Tools
            3. Task Tools
            4. Branch Tools
          2. Contributing
            1. License
              1. Support
                1. Acknowledgments

                  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/bobmaertz/bitbucket-mcp'

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