Provides comprehensive access to Bitbucket Cloud repositories, enabling management of pull requests, comments, tasks, and branches through the Bitbucket REST API 2.0
Bitbucket MCP Server
A Model Context Protocol (MCP) server that provides LLM applications with access to Bitbucket Cloud repositories through a standardized interface.
Overview
This project implements an MCP server for Bitbucket Cloud REST API 2.0, enabling AI assistants like Claude to interact with Bitbucket repositories, pull requests, comments, tasks, and branches.
Architecture
The project is organized as a monorepo with two main packages:
bitbucket-api
: Isolated REST API client for Bitbucket Cloudbitbucket-mcp-server
: MCP server implementation using the API client
Features
Supported Operations
Pull Requests
List pull requests for a repository
Get details of a specific pull request
Get commits in a pull request
Get diff for a pull request
Comments
List all comments on a pull request
Get a specific comment
Create new comments
Delete comments
Tasks
List all tasks on a pull request
Get a specific task
Create new tasks
Update task state (resolve/unresolve)
Branches
List repository branches
Get details of a specific branch
Create new branches
Installation
Prerequisites
Node.js 18 or higher
npm or pnpm
Bitbucket Cloud account with app password
Setup
Clone the repository:
Install dependencies:
Build the packages:
Configuration
Environment Variables
Create a .env
file or set the following environment variables:
Creating a Bitbucket App Password
Go to Bitbucket Settings > Personal Bitbucket settings > App passwords
Click "Create app password"
Give it a label (e.g., "MCP Server")
Select the required permissions:
Repositories: Read, Write
Pull requests: Read, Write
Issues: Read (if using tasks)
Copy the generated password
MCP Client Configuration
Claude Desktop
Add to your claude_desktop_config.json
:
Development
Project Structure
Available Scripts
Running the MCP Server
For development:
For production:
Usage Examples
Once configured with an MCP client like Claude Desktop, you can use natural language to interact with Bitbucket:
"List all open pull requests in the main repository"
"Show me the comments on pull request #42"
"What tasks are pending on PR #15?"
"List all branches in the repository"
"Create a comment on PR #10 saying 'Looks good to me!'"
Testing
Unit Tests
Integration Tests
Set up test environment variables and run:
Documentation
Design Document - Detailed architecture and design decisions
Implementation Plan - Development roadmap and task breakdown
Bitbucket REST API - Official API documentation
Model Context Protocol - MCP specification
MCP Tools Reference
Pull Request Tools
bitbucket_list_pull_requests
List pull requests for a repository.
Parameters:
workspace
(string, required): Bitbucket workspace IDrepo_slug
(string, required): Repository slugstate
(string, optional): Filter by state (OPEN, MERGED, DECLINED)
bitbucket_get_pull_request
Get details of a specific pull request.
Parameters:
workspace
(string, required): Bitbucket workspace IDrepo_slug
(string, required): Repository slugpr_id
(number, required): Pull request ID
bitbucket_get_pr_commits
Get commits in a pull request.
Parameters:
workspace
(string, required): Bitbucket workspace IDrepo_slug
(string, required): Repository slugpr_id
(number, required): Pull request ID
bitbucket_get_pr_diff
Get diff for a pull request.
Parameters:
workspace
(string, required): Bitbucket workspace IDrepo_slug
(string, required): Repository slugpr_id
(number, required): Pull request ID
Comment Tools
bitbucket_list_pr_comments
List all comments on a pull request.
Parameters:
workspace
(string, required): Bitbucket workspace IDrepo_slug
(string, required): Repository slugpr_id
(number, required): Pull request ID
bitbucket_create_comment
Create a new comment on a pull request.
Parameters:
workspace
(string, required): Bitbucket workspace IDrepo_slug
(string, required): Repository slugpr_id
(number, required): Pull request IDcontent
(string, required): Comment content (markdown supported)
Task Tools
bitbucket_list_pr_tasks
List all tasks on a pull request.
Parameters:
workspace
(string, required): Bitbucket workspace IDrepo_slug
(string, required): Repository slugpr_id
(number, required): Pull request ID
bitbucket_update_task
Update a task's state.
Parameters:
workspace
(string, required): Bitbucket workspace IDrepo_slug
(string, required): Repository slugpr_id
(number, required): Pull request IDtask_id
(number, required): Task IDstate
(string, required): New state (RESOLVED, UNRESOLVED)
Branch Tools
bitbucket_list_branches
List repository branches.
Parameters:
workspace
(string, required): Bitbucket workspace IDrepo_slug
(string, required): Repository slug
bitbucket_get_branch
Get details of a specific branch.
Parameters:
workspace
(string, required): Bitbucket workspace IDrepo_slug
(string, required): Repository slugbranch_name
(string, required): Branch name
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request
License
MIT
Support
For issues and questions:
GitHub Issues: Project Issues
Bitbucket API Docs: https://developer.atlassian.com/cloud/bitbucket/rest/
MCP Documentation: https://modelcontextprotocol.io/
Acknowledgments
Built with the Model Context Protocol SDK
Powered by Bitbucket Cloud REST API 2.0
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables AI assistants to interact with Bitbucket Cloud repositories, allowing users to manage pull requests, comments, tasks, and branches through natural language commands.