Bitbucket-MCP-Cloud

Name: Bitbucket-MCP-Cloud
Availability: InStock
Author: Jonatas Miler Oliveira

Bitbucket Cloud MCP Serverは、Bitbucket Cloud APIとのシームレスな統合を提供する生産準備完了のモデルコンテキストプロトコル（MCP）サーバーです。エンタープライズグレードの品質基準に基づき、包括的なエラーハンドリングやロギング、型安全性を備えています。AIアシスタントワークフローに対応したClaude Desktop統合も特徴です。

GitHub

GitHubスター

ユーザー評価

未評価

フォーク

イシュー

閲覧数

お気に入り

README

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/