# Bitbucket MCP Server **A Model Context Protocol server for AI agents to interact with Bitbucket Cloud Pull Requests** [![Node.js](https://img.shields.io/badge/Node.js-24.13-339933?logo=node.js&logoColor=white)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.3-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![MCP](https://img.shields.io/badge/MCP-1.29-blueviolet)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
--- ## 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 ### Prerequisites - Node.js **24.13+** (see `.nvmrc`) - A Bitbucket Cloud [App Password](https://bitbucket.org/account/settings/app-passwords/) with **repository read** permissions ### Installation ```bash git clone cd bitbucket-mcp npm install ``` ### Configuration Create a `.env` file in the project root: ```env BITBUCKET_MCP_EMAIL=your_email@example.com BITBUCKET_MCP_TOKEN=your_app_password # Optional defaults (avoids passing workspace/repo on every call) DEFAULT_WORKSPACE=my-workspace DEFAULT_REPO=my-repo ``` Or export as environment variables (takes priority over `.env`): ```bash export BITBUCKET_MCP_EMAIL=your_email@example.com export BITBUCKET_MCP_TOKEN=your_app_password ``` ### Run ```bash # Production npm start # Development (hot reload) npm run dev # Build npm run build ``` --- ## MCP Client Configuration ### Claude Code Add the following to your Claude Code MCP settings (`~/.claude/settings.json` or project `.claude/settings.json`): ```json { "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_bitbucket_app_password", "DEFAULT_WORKSPACE": "your-workspace", "DEFAULT_REPO": "your-repo" } } } } ``` ### Claude Desktop Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows): ```json { "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_bitbucket_app_password", "DEFAULT_WORKSPACE": "your-workspace", "DEFAULT_REPO": "your-repo" } } } } ``` > **Note:** You must build the project first (`npm run build`) since the config points to `dist/index.js`. Use the **absolute path** to the compiled entry point. Setting `DEFAULT_WORKSPACE` and `DEFAULT_REPO` is optional but convenient — it lets you omit those parameters from every tool call. --- ## 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 ```json { "name": "list_pull_requests", "arguments": { "workspace": "my-team", "repository": "backend-api", "state": "open" } } ``` Response: ```json { "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 ```bash # 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 [App Password](https://bitbucket.org/account/settings/app-passwords/) 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](LICENSE)