# bitbucket-mcp

[![npm version](https://img.shields.io/npm/v/@yunusemregul/bitbucket-mcp.svg)](https://www.npmjs.com/package/@yunusemregul/bitbucket-mcp)
[![npm downloads](https://img.shields.io/npm/dm/@yunusemregul/bitbucket-mcp.svg)](https://www.npmjs.com/package/@yunusemregul/bitbucket-mcp)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI assistants (like Claude) programmatic access to **Bitbucket Cloud**. It enables reading and managing pull requests, browsing repositories and branches, and automating code review workflows from your MCP client.

It authenticates with Bitbucket using an app password tied to your Atlassian account. Multiple workspace connections can be configured, with an optional default repository per workspace.

## What You Can Do

- *"List all open PRs in my-repo targeting the main branch"*
- *"Create a pull request from feature/SCC-1234 to develop with a summary of the changes"*
- *"Show me what files changed in PR #42 and give me a line-by-line diff of the auth module"*
- *"Find the PR for branch feature/payments and merge it with a squash strategy"*
- *"Decline the stale PRs that have been open for more than 30 days"*

![Web UI showing workspace list and live activity log](docs/screenshots/web-ui-overview.jpeg)

## Features

- **Multi-workspace support**: configure and switch between multiple Bitbucket Cloud workspaces
- **Default repository**: set a default repo per workspace so you don't need to specify it every call
- **Web UI**: browser-based management console for adding/editing workspace connections
- **Protected branches**: mark branches as protected to prevent accidental AI-triggered merges
- **Branch autocomplete**: the UI fetches and caches branch names for fast autocomplete
- **Real-time activity log**: live MCP tool execution log via SSE streamed to the Web UI
- **Mock OAuth**: built-in OAuth stub so MCP clients that require OAuth flows work out of the box

## Tools

| Tool | Description |
|------|-------------|
| `list_workspaces` | List all configured Bitbucket workspace connections |
| `list_repos` | List repositories in a workspace |
| `list_branches` | List branches in a repository with optional name filter |
| `get_pull_requests` | List pull requests filtered by state, source, or destination branch |
| `get_pull_request` | Get details of a single pull request |
| `create_pull_request` | Open a new pull request |
| `merge_pull_request` | Merge a pull request (merge commit, squash, or fast-forward) |
| `decline_pull_request` | Decline a pull request |
| `get_pr_diff` | List all files changed in a PR with line counts |
| `get_pr_file_diff` | Get the full diff for a specific file in a PR |

## Installation

### Via npx (recommended)

```bash
npx @yunusemregul/bitbucket-mcp
```

### Global install

```bash
npm install -g @yunusemregul/bitbucket-mcp
bitbucket-mcp
```

The server starts on `http://localhost:18434` by default.

```
Options:
  -p, --port    Port to listen on (default: 18434)
  -v, --version Print version
  -h, --help    Show help
```

Workspace configuration is stored in `~/.bitbucket-mcp/workspaces.json`.

## Configuration

### Via Web UI

Open `http://localhost:18434/` in your browser, click **+ Add Workspace**, fill in the details (connection is tested automatically as you type), then click **Save**.

![Add Workspace form with live connection test](docs/screenshots/add-workspace-form.jpeg)

### Workspace options

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Display name for this connection |
| `workspaceSlug` | string | Bitbucket workspace slug (from the URL) |
| `username` | string | Atlassian account email |
| `token` | string | Bitbucket app password |
| `repoSlug` | string | Default repository slug (optional) |
| `protectedBranches` | string[] | Branches the AI is not allowed to merge into |

> **Tip:** Set `protectedBranches` to `["main", "master"]` on production workspaces to block accidental merges.

## Using with Codex

Codex uses the Streamable HTTP endpoint:

```bash
codex mcp add bitbucket-mcp --url http://localhost:18434/mcp
```

Or add it directly to `~/.codex/config.toml`:

```toml
[mcp_servers.bitbucket-mcp]
url = "http://localhost:18434/mcp"
```

## Using with Claude Code

Claude Code can continue using the legacy SSE endpoint:

```bash
claude mcp add --transport sse bitbucket-mcp http://localhost:18434/mcp/sse
```

## Other MCP clients

For clients that support Streamable HTTP, use:

```json
{
  "mcpServers": {
    "bitbucket-mcp": {
      "url": "http://localhost:18434/mcp"
    }
  }
}
```

## Project Structure

```
bitbucket-mcp/
├── server.js           # Express app, Streamable HTTP + legacy SSE MCP endpoints
├── bitbucket.js        # Bitbucket Cloud API client
├── storage.js          # Workspace config persistence
├── tools/
│   ├── index.js        # Tool registry
│   ├── context.js      # Shared runtime state (sessions, logging)
│   └── *.js            # One file per MCP tool
└── static/
    ├── index.html      # Management console UI
    ├── app.js          # UI logic
    └── style.css       # Styles
```

## Release Notes

**v1.0.1** - Web UI shows the running server version next to the title and setup/tools modals, sourced from a new `/healthz` endpoint. Fixed the server previously reporting a hardcoded `1.0.0` version instead of reading `package.json`.

## Security Notes

- Credentials are stored in plaintext in `~/.bitbucket-mcp/workspaces.json`. Avoid exposing this file.
- Use Bitbucket **app passwords** with the minimum required scopes rather than your main account password.
- Use `protectedBranches` to prevent the AI from merging into sensitive branches.