bb-mcp-server 1.2.3

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

• 11 MCP Tools: Lean surface covering pull requests, pipelines, and workspace insights
• 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 or HTTP headers
• Context-Aware Credentials: Per-request headers are cached in the FastMCP context so every tool call shares the same configuration

Installation

From PyPI

pip install bb-mcp-server

From Source

git clone https://github.com/jasonpaulso/bitbucket-openapi-generated.git
cd bitbucket-openapi-generated
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. Supply credentials on every request via HTTP headers (see below). You can also set environment variables as server defaults for single-tenant deployments.

3. Environment variable template (optional server defaults):

   BITBUCKET_USERNAME=your_username
   BITBUCKET_APP_PASSWORD=your_app_password
   BITBUCKET_WORKSPACE=your_workspace  # Optional; auto-discovered when absent
   BITBUCKET_REPO=your_repo
   REQUIRE_CLIENT_CREDENTIALS=false  # Set true to require HTTP headers for sensitive values
   

4. HTTP header equivalents (case-insensitive):

   Header	Purpose
   X-Bitbucket-Username	Bitbucket username
   X-Bitbucket-App-Password	Bitbucket app password
   X-Bitbucket-Workspace	Workspace slug (optional; auto-detected when only one exists)
   X-Bitbucket-Repo	Repository slug
   Authorization: Bearer <token>	Optional bearer token (overrides basic auth)
   Authorization: Basic <...>	Optional pre-encoded basic credential

   When REQUIRE_CLIENT_CREDENTIALS=true, the server refuses to fall back to environment variables for sensitive keys during HTTP requests.

   You can also suffix requests with ?repo=<workspace>/<repo> (or simply ?repo=<repo> in a single-workspace account) instead of sending the X-Bitbucket-Repo header. Add ?workspace=<workspace> to override the workspace explicitly. Query parameters take precedence over headers and inferred defaults, making it easy to pin a repo/workspace for a single request.

   Examples:

   • ...?repo=busie/fe-main
   • ...?repo=fe-main&workspace=busie (equivalent)

   Single-workspace accounts can skip the workspace header altogether; the server will auto-discover the slug on first use.

5. Project-level configuration lives in fastmcp.json, which you can customise and run via fastmcp run fastmcp.json in any environment that supports the FastMCP CLI.

Usage

Running the Server

# Using the installed package (HTTP transport only)
bb-mcp-server --host 0.0.0.0 --port 8000

# Or run directly from source
python server.py --host 0.0.0.0 --port 8000

# Via the FastMCP CLI with declarative config
fastmcp run fastmcp.json

# Skip environment bootstrapping when dependencies are preinstalled (e.g., Docker)
fastmcp run fastmcp.json --skip-env

Both bb-mcp-server and python server.py accept --host, --port, and --transport flags (HTTP only). The fastmcp.json file in this repository mirrors those defaults so fastmcp run starts an HTTP server without additional arguments.

Integrating with MCP Clients

Forward the headers listed in the configuration section with every request. See AGENTS.md for agent integration details and context behaviour.

Tools automatically reuse the scoped workspace/repo from the FastMCP context, so the HTTP schemas hide those arguments—use request-level overrides (headers or ?workspace=/?repo=) when you need to switch context.

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.

Resources

• repo://{repo}/info – Repository information
• pipelines://{repo}/recent – Recent pipeline runs
• pull-requests://{repo}/open – Open pull requests
• workspace://{workspace}/members – Team members for reviewers
• workspace://{workspace}/default-reviewers – Suggested reviewers
• repo://{repo}/branches – Available branches
• repo://{repo}/branching-model – Branching configuration

Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/jasonpaulso/bitbucket-openapi-generated.git
cd bitbucket-openapi-generated

# 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/jasonpaulso/bitbucket-openapi-generated/issues
• Documentation: https://github.com/jasonpaulso/bitbucket-openapi-generated/wiki

Next Steps?

• Built-in Auth Providers: if you plan to expand beyond simple bearer/basic auth, FastMCP’s auth providers (see docs/fast-mcp/auth-overview.md) can replace the custom middleware with reusable token/OAuth flows and built-in metadata hints for clients.