265 lines
7.0 KiB
Markdown
265 lines
7.0 KiB
Markdown
<div align="center">
|
|
|
|
# Bitbucket MCP Server
|
|
|
|
**A Model Context Protocol server for AI agents to interact with Bitbucket Cloud Pull Requests**
|
|
|
|
[](https://nodejs.org/)
|
|
[](https://www.typescriptlang.org/)
|
|
[](https://modelcontextprotocol.io/)
|
|
[](LICENSE)
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
## 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 [API Token](https://id.atlassian.com/manage-profile/security/api-tokens) with **repository read** permissions
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
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)
|