Bitbucket

This MCP server provides a Python-based Bitbucket API integration built around the Model Context Protocol (MCP). It runs in containers and offers a set of tools to interact with repositories, pull requests, comments, pipelines, and build statuses, enabling automation and integration workflows in your development environment.

How to use

You connect to the Bitbucket MCP Server from your MCP client by running the server in a container and invoking the provided commands. You can operate through a local container runtime, such as Podman, and you’ll interact with the server via stdio transport or other configured integrations.

How to install

Prerequisites: ensure you have Python 3.12 or later and Podman or Docker installed on your system. You also need a Bitbucket API token for authentication.

pip install bitbucket-mcp-py

Configure credentials by copying the example environment file and editing it with your API token.

cp .env.example .env
# Edit .env with your credentials

Obtain your API token from your Bitbucket account at the API tokens management page.

Get your API token at: https://id.atlassian.com/manage-profile/security/api-tokens

To run the server, build the container image, start it, and verify authentication.

make build
make up
make verify  # Test authentication

If you plan to use your client with Claude Desktop or VS Code, configure the MCP connection as shown in the examples below.

Additional setup for client integrations

Claude Desktop integration requires an MCP server entry that launches the MCP runtime inside your container and uses stdio transport.

{
  "mcpServers": {
    "bitbucket": {
      "command": "podman",
      "args": ["exec", "-i", "bitbucket-mcp", "python", "-m", "src.main", "--transport", "stdio"]
    }
  }
}

Using with VS Code (GitHub Copilot)

Add the MCP configuration to your VS Code settings to enable Copilot to communicate with the Bitbucket MCP server.

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "podman",
      "args": ["exec", "-i", "bitbucket-mCP", "python", "-m", "src.main", "--transport", "stdio"]
    }
  }
}

Make commands

Use these common commands to manage the MCP server during development.

make build    # Build container
make up       # Start container
make down     # Stop container
make test     # Run tests
make verify   # Test Bitbucket auth
make logs     # View logs
make clean    # Remove container/image

Secure credentials (optional)

For enhanced security, you can store credentials in the system keychain instead of relying solely on environment variables.

# Install keyring support
pip install 'bitbucket-mcp-py[keyring]'

# Store in macOS Keychain (example)
python3 -c "import keyring; keyring.set_password('bitbucket-mcp', 'bitbucket_token', 'YOUR_TOKEN')"

Development and requirements

To contribute or run tests locally, ensure you have the necessary tooling installed and then execute the test suite.

# Run tests
make test

# Run a specific test
pytest tests/test_client.py -v

Notes and requirements

Required: Python 3.12+, Podman or Docker, and a Bitbucket API token. The server is optimized for container execution and supports easy integration with popular MCP clients.

Available tools

list_repositories

Fetch a list of repositories accessible to the authenticated user.

get_repository

Retrieve details for a specific repository.

get_pull_requests

Obtain pull requests for a repository or project.

get_pull_request

Fetch details of a single pull request.

create_pull_request

Create a new pull request between branches.

update_pull_request

Update fields of an existing pull request.

approve_pull_request

Approve a pull request to indicate approval.

unapprove_pull_request

Remove an existing approval from a pull request.

decline_pull_request

Decline a pull request to mark it as closed without merging.

get_pull_request_comments

List comments on a pull request.

add_pull_request_comment

Add a new comment to a pull request.

get_pull_request_activity

Retrieve activity events for a pull request.

get_pull_request_diff

Show the diff for a pull request.

get_pull_request_commits

List commits included in a pull request.

get_pull_request_statuses

Get build/status information for a pull request.

get_pull_request_diffstat

Obtain diff statistics for a pull request.

list_pipeline_runs

List runs of a pipeline associated with a repository.

get_pipeline_run

Get details of a specific pipeline run.

get_pipeline_steps

Retrieve steps for a pipeline run.

get_pipeline_step_logs

Fetch logs for a pipeline step.