Bitbucket MCP Server

MCP (Model Context Protocol) server for AI agents to interact with Bitbucket Cloud Pull Requests.

Features

• ✅ List pull requests in repositories
• ✅ Get detailed PR information
• ✅ Get PR activities/events
• ✅ Get PR changes (files modified)
• ✅ Get PR comments and individual comments
• ✅ Get PR commits
• ✅ Get PR diff and patch
• ✅ Get PR participants and reviewers
• ✅ Get PR status/state
• ✅ Get PR tasks
• ✅ Flexible credential configuration (env var or .env file)
• ✅ Rate limiting protection
• ✅ Error handling and retry logic

Installation

npm install

Configuration

Credentials Sources (Priority Order)

1. Environment Variables (highest priority):

   export BITBUCKET_MCP_EMAIL=your_email@example.com
   export BITBUCKET_MCP_TOKEN=your_token_here
   

2. .env file in project root:

   BITBUCKET_MCP_EMAIL=your_email@example.com
   BITBUCKET_MCP_TOKEN=your_token_here
   

3. Interactive prompt (development fallback)

Getting Your Access Token

1. Go to Bitbucket Applications
2. Click "New application" or select existing
3. Set callback URL to http://localhost:8080 (or any placeholder)
4. Copy the Access token

Note: Bitbucket uses Basic Authentication with your email as username and the access token as password.

Usage

Start the Server

npm start
# Or for development:
npm run dev

The server will output:

✅ Bitbucket MCP Server started
   Name: bitbucket-pullrequests v1.0.0
   Token source: environment variable

Available Tools

Tool	Description	Parameters
list_pull_requests	List PRs in a repository	workspace, repository, state (optional), author (optional)
get_pull_request	Get PR details	workspace, repository, pullRequestId
get_pull_request_activities	Get PR activities/events	workspace, repository, pullRequestId, limit (optional), start (optional)
get_pull_request_changes	Get files changed in PR	workspace, repository, pullRequestId, limit (optional), start (optional)
get_pull_request_comments	Get all PR comments	workspace, repository, pullRequestId, limit (optional), start (optional)
get_pull_request_comment	Get a specific PR comment	workspace, repository, pullRequestId, commentId
get_pull_request_commits	Get commits in PR	workspace, repository, pullRequestId, limit (optional), start (optional)
get_pull_request_diff	Get PR diff	workspace, repository, pullRequestId, path (optional), context (optional)
get_pull_request_patch	Get PR patch	workspace, repository, pullRequestId
get_pull_request_participants	Get PR participants	workspace, repository, pullRequestId
get_pull_request_reviewers	Get PR reviewers	workspace, repository, pullRequestId
get_pull_request_status	Get PR status/state	workspace, repository, pullRequestId
get_pull_request_tasks	Get PR tasks	workspace, repository, pullRequestId
get_pull_request_task_count	Get PR task count	workspace, repository, pullRequestId
get_full_pull_request	Get full PR details	workspace, repository, pullRequestId

Example MCP Call

{
  "name": "list_pull_requests",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repo",
    "state": "open"
  }
}

API Reference

list_pull_requests(workspace, repository, options?)

List pull requests in a repository.

Options:

• state: 'open' | 'closed' | 'all' (default: open)
• author: Filter by author username

Returns: Array of pull request objects with metadata.

get_pull_request(workspace, repository, pullRequestId)

Get detailed information about a specific pull request.

Returns: Complete PR object including title, description, source/destination branches, reviewers, etc.

merge_pull_request(workspace, repository, pullRequestId, options?)

Merge a pull request into the target branch.

Options:

• mergeStrategy: 'merge' | 'squash' | 'fastforward' (default: merge)
• deleteSourceBranch: boolean (default: false)

create_pull_request(workspace, repository, title, description, sourceBranch, destinationBranch)

Create a new pull request.

Returns: Created PR object with ID and URL.

Error Handling

The server handles the following errors:

Error	Cause
AuthenticationFailed	Invalid or expired token
RateLimited	API rate limit exceeded (429)
RepositoryNotFound	Workspace/repo doesn't exist
PRNotFound	Pull request ID invalid

Development

# Install dependencies
npm install

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build

License

MIT