# 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 Get up and running in 4 steps: ### 1. Prerequisites - Node.js **24.13+** (see `.nvmrc`) - A Bitbucket Cloud [API Token](https://id.atlassian.com/manage-profile/security/api-tokens) with **repository read** permissions (note: App Passwords are no longer supported by Bitbucket) ### 2. Install & Build ```bash git clone cd bitbucket-mcp npm install npm run build ``` ### 3. Configure in Claude Add the MCP server to your Claude configuration: **Claude Code** — edit `~/.claude/settings.json` (global) or `.claude/settings.json` (per-project): ```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_api_token", "DEFAULT_WORKSPACE": "your-workspace", "DEFAULT_REPO": "your-repo" } } } } ``` **Claude Desktop** — edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (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_api_token", "DEFAULT_WORKSPACE": "your-workspace", "DEFAULT_REPO": "your-repo" } } } } ``` > **Important:** > - Replace `/absolute/path/to/bitbucket-mcp` with the actual absolute path where you cloned the repo. > - `DEFAULT_WORKSPACE` and `DEFAULT_REPO` are optional but convenient — they let you omit those parameters from every tool call. > - Get your API token from [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens). ### 4. Verify Restart Claude (or reload MCP servers), then ask Claude to run the `validate_token` tool. If credentials are correct, it will confirm the connection is working. --- ## 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 ### Running Locally For development, you can use a `.env` file instead of configuring credentials in the MCP client: ```env BITBUCKET_MCP_EMAIL=your_email@example.com BITBUCKET_MCP_TOKEN=your_api_token DEFAULT_WORKSPACE=my-workspace DEFAULT_REPO=my-repo ``` ```bash # Run with hot reload npm run dev # Or run directly npm start ``` ### Testing ```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 [API Token](https://id.atlassian.com/manage-profile/security/api-tokens) > **Note:** Bitbucket no longer supports App Passwords. You must use an API Token instead. 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)