Bitbucket-MCP-Cloud by jhonymiler - MCP Server

Bitbucket Cloud MCP Server

A production-ready Model Context Protocol (MCP) server for seamless integration with the Bitbucket Cloud API. Built with enterprise-grade quality standards, this server provides comprehensive access to Bitbucket Cloud's functionalities through a standardized MCP interface.

🌟 Highlights

✅ Complete Bitbucket Cloud API Coverage - All essential features implemented
✅ Production Ready - Comprehensive error handling, logging, and type safety
✅ Multiple Installation Methods - PyPI, direct execution, or development mode
✅ Claude Desktop Integration - Ready for AI assistant workflows
✅ Fully Tested - Comprehensive test suite with automated CI/CD
✅ Clean Architecture - Modular design following SOLID principles

🛠️ Features (15 Tools)

🎯 Project & Repository Management

list_projects - List all accessible projects in workspace
list_repositories - List repositories by workspace or project
list_commits - Browse commit history with filtering options

🔄 Pull Request Lifecycle

list_pull_requests - List PRs with state filtering (OPEN, MERGED, DECLINED)
get_pull_request - Get detailed PR information
create_pull_request - Create new pull requests with reviewers
update_pull_request - Update pull request title and/or description
approve_pull_request - Approve pull requests
decline_pull_request - Decline pull requests
merge_pull_request - Merge approved PRs with strategy selection

💬 Comment System

list_pull_request_comments - List all PR comments
create_pull_request_comment - Add general comments
create_pull_request_inline_comment - Add line-specific code comments

📊 Code Analysis

get_pull_request_diff - Get full diff for code review
get_pull_request_diffstat - Get summary of changes (files, lines added/removed)

🚀 Installation & Usage

Method 1: Direct Execution via uvx (Recommended)

# No installation needed - run directly from PyPI
uvx bitbucket-mcp-cloud

# For MCP tools that support it
mcp run bitbucket-mcp-cloud

Method 2: Global Installation

# Install globally
pip install bitbucket-mcp-cloud

# Run the server
bitbucket-mcp-cloud

Method 3: Development Mode

# Clone and setup for development
git clone https://github.com/jhonymiler/Bitbucket-MCP-Cloud.git
cd Bitbucket-MCP-Cloud

# Using uv (recommended)
uv sync
uv run server.py

# Or using pip
pip install -e .
python server.py

Method 4: MCP Tools Integration

# Using the MCP CLI
mcp run server.py

# For development and testing
uv run mcp dev server.py

📋 Prerequisites

Python 3.10+
A Bitbucket Cloud account
Configured Bitbucket App Password

⚙️ Setup

1. Create Bitbucket App Password

Go to: Account Settings > App Passwords
Click "Create app password"
Select the required permissions:
- Repositories: Read, Write
- Pull requests: Read, Write
- Projects: Read

2. Configure Environment Variables

# Option 1: Using .env file (for development)
cp .env.example .env
# Edit .env with your credentials

# Option 2: Export environment variables
export BITBUCKET_USERNAME=your_username
export BITBUCKET_TOKEN=your_app_password
export BITBUCKET_DEFAULT_WORKSPACE=your_workspace

3. Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "bitbucket": {
      "command": "uvx",
      "args": ["bitbucket-mcp-cloud"],
      "env": {
        "BITBUCKET_USERNAME": "your_username",
        "BITBUCKET_TOKEN": "your_app_password",
        "BITBUCKET_DEFAULT_WORKSPACE": "your_workspace"
      }
    }
  }
}

🔧 Tool Usage Examples

Projects and Repositories

# List projects
await list_projects(workspace="my-workspace", limit=25)

# List all repositories
await list_repositories(workspace="my-workspace")

# List repositories for a specific project
await list_repositories(workspace="my-workspace", project="PROJ")

Pull Requests

# List open PRs
await list_pull_requests(repository="my-repo", state="OPEN")

# Get PR details
await get_pull_request(repository="my-repo", pr_id=123)

# Create new PR
await create_pull_request(
    repository="my-repo",
    title="New feature",
    source_branch="feature/new-feature",
    target_branch="main",
    description="Implements new feature X"
)

# Update PR description
await update_pull_request(
    repository="my-repo",
    pr_id=123,
    description="Updated description with more details"
)

# Approve and merge PR
await approve_pull_request(repository="my-repo", pr_id=123)
await merge_pull_request(repository="my-repo", pr_id=123, merge_strategy="squash")

Comments and Code Review

# Create inline comment on specific line
await create_pull_request_inline_comment(
    repository="my-repo",
    pr_id=123,
    content="This function could be optimized",
    filename="src/main.py",
    line_number=42
)

# Get diff for analysis
diff_text = await get_pull_request_diff(repository="my-repo", pr_id=123)

# Get summary of changes
diffstat = await get_pull_request_diffstat(repository="my-repo", pr_id=123)

🏗️ Architecture

bitbucket-mcp-cloud/
├── server.py              # Main MCP server (entry point)
├── src/
│   ├── models.py          # Pydantic models for type safety
│   ├── utils.py           # Utility functions and logging
│   └── __init__.py
├── tests/                 # Comprehensive test suite
│   └── test_bitbucket_mcp.py
├── pyproject.toml         # Project configuration
├── .env.example          # Configuration template
├── .github/
│   └── workflows/
│       └── publish.yml   # CI/CD pipeline
└── README.md             # This documentation

Key Components

BitbucketCloudClient: Async HTTP client with comprehensive API coverage
FastMCP: MCP server with auto-generated tool definitions
Pydantic Models: Type-safe data structures for all API responses
Comprehensive Logging: Detailed operation tracking and debugging
Error Handling: Robust error handling with proper HTTP status codes

🧪 Testing

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=src --cov-report=html

# Run specific test categories
uv run pytest tests/test_bitbucket_mcp.py::TestMCPTools -v

# Type checking
uv run mypy server.py src/

# Code formatting
uv run black server.py src/ tests/

🔒 Security Features

Secure Authentication: Uses Bitbucket App Passwords (no OAuth complexity)
Input Validation: Comprehensive validation using Pydantic models
Error Handling: Sanitized error messages (no credential leakage)
Rate Limiting Awareness: Respects Bitbucket API rate limits
HTTPS Only: All communications encrypted

📊 Quality Assurance

Type Safety: Full type annotations with mypy validation
Code Quality: Black formatting and comprehensive linting
Testing: 17 test cases covering all major functionality
CI/CD: Automated testing and PyPI publishing
Documentation: Comprehensive docstrings and examples

🔗 API Reference

This MCP server implements the complete Bitbucket Cloud REST API v2.0. Key API endpoints covered:

/workspaces/{workspace}/projects - Project management
/repositories/{workspace} - Repository operations
/repositories/{workspace}/{repo}/pullrequests - PR lifecycle
/repositories/{workspace}/{repo}/commits - Commit history
/pullrequests/{pr_id}/comments - Comment system
/pullrequests/{pr_id}/diff - Code analysis

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Run tests (uv run pytest)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone and setup
git clone https://github.com/jhonymiler/Bitbucket-MCP-Cloud.git
cd Bitbucket-MCP-Cloud
uv sync --extra dev

# Run quality checks
uv run pytest
uv run mypy server.py src/
uv run black --check server.py src/ tests/

📝 Changelog

v1.3.5 (Latest)

✅ Package restructured for optimal PyPI distribution
✅ Server.py in root with conditional imports
✅ All execution methods tested and working
✅ Enhanced build system and CI/CD
✅ Production-ready package structure

v1.3.4

✅ Server correctly included in PyPI wheel
✅ All execution methods working (uvx, pip, development)
✅ Complete test coverage
✅ Claude Desktop integration ready

v1.3.x Series

✅ Complete Bitbucket Cloud API implementation
✅ Comprehensive error handling and logging
✅ Type safety with mypy validation
✅ Production-ready architecture

📄 License

MIT License - see the file for details.

🆘 Support

Issues: GitHub Issues
Documentation: This README and inline code documentation
API Reference: Bitbucket Cloud REST API

🔗 Related Links

Made with ❤️ for the MCP community