bb-mcp-server 1.0.1

Bitbucket MCP (Model Context Protocol) server built with FastMCP that provides programmatic access to Bitbucket API v2.0

Bitbucket MCP Server

A Model Context Protocol (MCP) server that provides programmatic access to Bitbucket API v2.0. Built with FastMCP, this server enables LLMs and other tools to interact with Bitbucket repositories, pull requests, pipelines, and workspaces.

Features

• 26 Bitbucket API Tools: Complete coverage of essential Bitbucket operations
• 3 Meta-Tools: High-level workflows for common patterns (pipeline analysis, PR reviews, workspace overview)
• 7 MCP Resources: Quick access to repository info, branches, members, and more
• Optimized for LLMs: Token-efficient design with structured outputs
• Flexible Configuration: Works with any Bitbucket workspace and repository via environment variables

Installation

From PyPI

pip install bb-mcp-server

From Source

git clone https://github.com/yourusername/bb-mcp-server.git
cd bb-mcp-server
pip install -e .

Configuration

1. Create a Bitbucket App Password:

   • Go to https://bitbucket.org/account/settings/app-passwords/
   • Create a new app password with necessary permissions
   • Save the password securely

2. Set up environment variables:

   cp .env.example .env
   

3. Edit .env with your credentials:

   BITBUCKET_USERNAME=your_username
   BITBUCKET_APP_PASSWORD=your_app_password
   BITBUCKET_WORKSPACE=your_workspace  # Optional, defaults to "busie"
   BITBUCKET_REPO=your_repo            # Optional, defaults to "fe-main"
   

Usage

Running the Server

# Using the installed package
bb-mcp-server

# Or directly with Python
python server.py

Integrating with MCP Clients

Add to your MCP client configuration:

{
  "servers": {
    "bitbucket": {
      "command": "bb-mcp-server",
      "env": {
        "BITBUCKET_USERNAME": "your_username",
        "BITBUCKET_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

Available Tools

The lean surface ships ten focused tools with summary-first payloads:

• pr.list – List PRs with compact metadata.
• pr.overview – Return digest: meta, blockers, diffstat, recent comments.
• pr.review – Generate a structured review summary based on the overview.
• pr.comment.add – Post a PR comment (optional inline path/line).
• pr.tasks.sync – Create and resolve PR tasks in one call.
• pipe.run – Start a pipeline for the given repo/ref/spec.
• pipe.fail.summary – Summarise the most recent failing pipelines.
• workspace.list – List repos, members, or projects (summary by default).
• repo.get – Repo basics plus a five-item PR sample.
• me.whoami – Minimal identity plus accessible workspaces.

Legacy names (e.g. list_pull_requests, analyze_pipeline_failure) map automatically to the new surface for backward compatibility.

Resources

• bitbucket://{workspace}/{repo}/info - Repository information
• bitbucket://{workspace}/{repo}/recent-pipelines - Recent pipeline runs
• bitbucket://{workspace}/{repo}/open-prs - Open pull requests
• bitbucket://{workspace}/workspace-members - Team members for reviewers
• bitbucket://{workspace}/{repo}/branches - Available branches
• bitbucket://{workspace}/workspace-projects - Workspace projects

Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/yourusername/bb-mcp-server.git
cd bb-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .
pip install -r requirements.txt

Running Tests

# Install test dependencies
pip install pytest pytest-asyncio pytest-cov

# Run tests
pytest tests/

# Run with coverage
pytest tests/ --cov=. --cov-report=html

Code Quality

# Linting
ruff check .

# Formatting
black .

# Type checking
mypy server.py utils/ modules/

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

License

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

Acknowledgments

• Built with FastMCP framework
• Uses Bitbucket API v2.0
• Implements Model Context Protocol (MCP) specification

Support

For issues, questions, or contributions, please visit:

• GitHub Issues: https://github.com/yourusername/bb-mcp-server/issues
• Documentation: https://github.com/yourusername/bb-mcp-server/wiki