jlromano/bitbucket-mcp

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