Bitbucket MCP Server

A Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to interact with Bitbucket repositories, manage pull requests, analyze code, and perform various repository operations.

🌟 Features

Repository Management

List workspaces and repositories
Get detailed repository information
Search code across repositories
Access file contents

Branch Operations

List and get branch details
Compare branches
View branch history

Pull Request Management

List, create, and manage pull requests
Approve and merge pull requests
Add comments and reviews
Filter by status (OPEN, MERGED, DECLINED)

Commit Operations

List and analyze commits
Get commit details and diffs
Filter commits by branch

🚀 Quick Start

Prerequisites

Node.js 18 or higher
Bitbucket account with App Password

Installation

Clone the repository:

git clone https://github.com/jlromano/bitbucket-mcp.git
cd bitbucket-mcp

Install dependencies:

npm install

Configure environment:

cp .env.example .env
# Edit .env with your Bitbucket credentials

Build the project:

npm run build

🔐 Authentication Setup

Creating a Bitbucket App Password

Log into your Bitbucket account
Navigate to Personal Settings → App passwords
Click Create app password
Select the following permissions:
- Account: Read
- Workspace membership: Read
- Repositories: Read, Write
- Pull requests: Read, Write
Copy the generated password

Environment Configuration

Create a .env file with your credentials:

BITBUCKET_USERNAME=your-username-or-email
BITBUCKET_APP_PASSWORD=your-app-password
BITBUCKET_WORKSPACE=default-workspace (optional)

📋 Configuration

Claude Desktop

Add to your Claude configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp/dist/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

Other MCP-Compatible Applications

Install globally and run:

npm install -g bitbucket-mcp
bitbucket-mcp

🛠️ Available Tools

The server provides the following tools for LLM interaction:

Tool	Description
`list_workspaces`	List all available workspaces
`list_repositories`	List repositories in a workspace
`get_repository`	Get repository details
`list_branches`	List repository branches
`get_branch`	Get branch details
`compare_branches`	Compare two branches
`list_pull_requests`	List pull requests with optional filters
`get_pull_request`	Get pull request details
`create_pull_request`	Create a new pull request
`approve_pull_request`	Approve a pull request
`merge_pull_request`	Merge a pull request
`add_pull_request_comment`	Add a comment to a pull request
`list_commits`	List repository commits
`get_commit`	Get commit details
`get_file_content`	Get file contents from repository
`search_code`	Search code in workspace

💻 Development

Project Structure

bitbucket-mcp/
├── src/
│   ├── index.ts           # MCP server implementation
│   └── BitbucketClient.ts # Bitbucket API client
├── dist/                  # Compiled JavaScript
├── .env.example          # Environment variables template
├── package.json
├── tsconfig.json
└── README.md

Development Commands

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build

# Run linting
npm run lint

# Format code
npm run format

# Start production server
npm start

🤝 Usage Examples

Once configured, you can interact with your Bitbucket repositories through your LLM:

"List all repositories in my workspace"
"Show open pull requests in the main repository"
"Create a pull request from feature/new-feature to main"
"Get the content of README.md from the develop branch"
"Search for 'authentication' in the codebase"
"Compare develop and main branches"
"Show recent commits with 'fix' in the message"

🔍 Troubleshooting

Common Issues

Authentication Failed

Verify your username (use email if that's your login)
Ensure App Password is valid and has correct permissions
Check that the App Password hasn't expired

Workspace Not Found

Confirm workspace slug matches URL format: bitbucket.org/WORKSPACE/
Verify you have access to the workspace

Build Errors

Ensure Node.js 18+ is installed: node --version
Clear node_modules and reinstall: rm -rf node_modules && npm install
Rebuild the project: npm run build

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

🙏 Acknowledgments

Built with the Model Context Protocol SDK
Powered by Bitbucket API
Inspired by the MCP community

📧 Support

For issues, questions, or suggestions, please open an issue on GitHub.

Note: This is not an official Atlassian product. Bitbucket is a trademark of Atlassian.