MCP Bitbucket Server

An MCP (Model Context Protocol) server to interact with Bitbucket through automated tools.

Installation

1. Clone the repository

git clone <repository-url>
cd bitbucket

2. Install dependencies

Option A: With pnpm (recommended)

pnpm install

Option B: With npm

npm install

3. Configure environment variables

Create a .env file in the project root with your Bitbucket credentials:

BITBUCKET_EMAIL=your_email@example.com
BITBUCKET_API_TOKEN=your_api_token
BITBUCKET_WORKSPACE=your_workspace
BITBUCKET_REVIEWER_UUID=reviewer_uuid_optional
BITBUCKET_API_BASE_URL=https://api.bitbucket.org/2.0
BITBUCKET_DEFAULT_DESTINATION_BRANCH=develop
BITBUCKET_CLOSE_SOURCE_BRANCH=true

Variable descriptions:

• BITBUCKET_EMAIL: Your Bitbucket account email

• BITBUCKET_API_TOKEN: Your Bitbucket App Password (not your regular password)

• BITBUCKET_WORKSPACE: Your Bitbucket workspace name

• BITBUCKET_REVIEWER_UUID: (Optional) UUID of the default reviewer for pull requests. Use a comma-separated list for several reviewers

• BITBUCKET_API_BASE_URL: (Optional) Base URL for Bitbucket API (default: https://api.bitbucket.org/2.0)

• BITBUCKET_DEFAULT_DESTINATION_BRANCH: (Optional) Default destination branch for pull requests (default: develop)

• BITBUCKET_CLOSE_SOURCE_BRANCH: (Optional) Whether to close source branch after merge (default: true)

Related MCP server: Bitbucket MCP Server

MCP Configuration

Add the following configuration to your MCP settings file (usually in ~/.config/mcp/settings.json or similar):

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["tsx", "/full/path/to/project/src/server.ts"],
      "env": {
        "BITBUCKET_EMAIL": "your_email@example.com",
        "BITBUCKET_API_TOKEN": "your_api_token",
        "BITBUCKET_WORKSPACE": "your_workspace",
        "BITBUCKET_REVIEWER_UUID": "reviewer_uuid_optional",
        "BITBUCKET_API_BASE_URL": "https://api.bitbucket.org/2.0",
        "BITBUCKET_DEFAULT_DESTINATION_BRANCH": "develop",
        "BITBUCKET_CLOSE_SOURCE_BRANCH": "true"
      }
    }
  }
}

Note: Replace /full/path/to/project with the absolute path where you have cloned this project.

Usage

Once configured, you can use the following tools from your MCP client:

• Prepare Pull Request (prepare-pull-request-automatically): Automatically generate the title, description, branches and project for a pull request

• Create Pull Request (create-pull-request): Create a pull request (optionally as a draft)

• List Pull Requests (list-pull-request): View the open pull requests of a repository

• Review Pull Request (review-pull-request): Show the diff, metadata, approvals and comments of a pull request

• Comment Pull Request (comment-pull-request): Add a comment to an existing pull request

Using it with a skill (recommended)

The MCP tools work on their own, but the assistant gets much better results when it also has a skill: a short instructions file that tells it when to use each tool, in which order, and which rules to follow. Without one, the assistant may skip the confirmation step, guess the wrong parameters, or fall back to calling the Bitbucket API with curl.

Skills are a Claude Code feature. If you use another MCP client, you can put the same guidance in its system prompt or custom instructions.

Example skill

This repository includes a ready-to-use example in skills/bitbucket/SKILL.md. You can use it as is or adapt it to your team's conventions.

To install it for all your projects:

mkdir -p ~/.claude/skills/bitbucket
cp skills/bitbucket/SKILL.md ~/.claude/skills/bitbucket/SKILL.md

To use it only in one project, copy it to <your-project>/.claude/skills/bitbucket/SKILL.md instead.

What your skill should cover

If you write your own skill, make sure it covers at least:

• When to use it: any task about pull requests or code review, and only when the repository is hosted on Bitbucket.

• Tools only: always use the MCP tools, never curl or manual API calls. If the MCP fails, report it and ask the user what to do.

• Creating a PR: call prepare-pull-request-automatically first, passing any value the user already gave (title, branches, draft…). Then show the summary, ask for confirmation, and only then call create-pull-request.

• Draft PRs: pass draft: true to both tools when the user asks for a draft or WIP PR.

• The project parameter: it's the repository slug. If the user doesn't give it, take it from the origin remote of the current repository.

• Reviewing and commenting: if there's no PR ID, call list-pull-request first (it only returns open PRs, with no filters). Then use review-pull-request and comment-pull-request.

• Comments: ask for the text if it's missing, prefix it with [AI], and confirm with the user before posting a comment written by the assistant.

Add your own conventions on top: PR title format, description template, which branch to target, language of the comments, etc.

Development

To run the server in development mode:

With pnpm:

pnpm run inspector

With npm:

npm run inspector

Requirements

• Node.js 18+

• pnpm or npm

• Bitbucket account with App Password configured