# MCP Bitbucket Server

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

## Installation

### 1. Clone the repository

```bash
git clone <repository-url>
cd bitbucket
```

### 2. Install dependencies

**Option A: With pnpm (recommended)**

```bash
pnpm install
```

**Option B: With npm**

```bash
npm install
```

### 3. Configure environment variables

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

```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
```

**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)

## MCP Configuration

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

```json
{
  "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](https://docs.claude.com/en/docs/claude-code/skills) 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`](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:

```bash
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:**

```bash
pnpm run inspector
```

**With npm:**

```bash
npm run inspector
```

## Requirements

- Node.js 18+
- pnpm or npm
- Bitbucket account with App Password configured