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

1. Clone the repository:

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

2. Install dependencies:

npm install

3. Configure environment:

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

4. Build the project:

npm run build

🔐 Authentication Setup

Creating a Bitbucket App Password

1. Log into your Bitbucket account

2. Navigate to Personal Settings → App passwords

3. Click Create app password

4. Select the following permissions:

   • Account: Read

   • Workspace membership: Read

   • Repositories: Read, Write

   • Pull requests: Read, Write

5. 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:

💻 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.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/AmazingFeature)

3. Commit your changes (git commit -m 'Add some AmazingFeature')

4. Push to the branch (git push origin feature/AmazingFeature)

5. 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.