Skip to main content
Glama
MCP Bitbucket Python

MCP Bitbucket Python

by Kallows

MCP Bitbucket Python 🦊

A Python implementation of an MCP server for Bitbucket integration. MCP (Model Context Protocol) enables secure, local tool access for AI applications. The server runs locally on the same machine as your AI application.

Installation

# Install the server locally
git clone https://github.com/kallows/mcp-bitbucket.git
cd mcp-bitbucket

# Install dependencies using uv (recommended) or pip
uv install
# or
pip install -e .

Related MCP server: bitbucket-python-mcp

Tools Available

This MCP server provides the following Bitbucket integration tools:

  • bb_create_repository: Create a new Bitbucket repository

    • Required: name (repository name)

    • Optional: description, workspace (defaults to kallows), project_key, is_private (default: true), has_issues (default: true)

  • bb_create_branch: Create a new branch in a repository

    • Required: repo_slug, branch (name for the new branch)

    • Optional: workspace (defaults to kallows), start_point (defaults to main)

  • bb_delete_repository: Delete a Bitbucket repository

    • Required: repo_slug

    • Optional: workspace (defaults to kallows)

  • bb_read_file: Read a file from a repository

    • Required: repo_slug, path (file path in repository)

    • Optional: workspace (defaults to kallows), branch (defaults to main/master)

  • bb_write_file: Create or update a file in a repository

    • Required: repo_slug, path, content

    • Optional: workspace (defaults to kallows), branch (defaults to main), message (commit message)

  • bb_create_issue: Create an issue in a repository

    • Required: repo_slug, title, content

    • Optional: workspace (defaults to kallows), kind (bug/enhancement/proposal/task), priority (trivial/minor/major/critical/blocker)

  • bb_delete_issue: Delete an issue from a repository

    • Required: repo_slug, issue_id

    • Optional: workspace (defaults to kallows)

  • bb_search_repositories: Search Bitbucket repositories using query syntax

    • Required: query (e.g., 'name ~ "test"' or 'project.key = "PROJ"')

    • Optional: workspace (defaults to kallows), page (default: 1), pagelen (default: 10, max: 100)

  • bb_delete_file: Delete a file from a repository

    • Required: repo_slug, path

    • Optional: workspace (defaults to kallows), branch (defaults to main), message (commit message)

  • bb_create_pull_request: Create a pull request

    • Required: repo_slug, title, source_branch

    • Optional: workspace (defaults to kallows), destination_branch (defaults to main), description, close_source_branch (default: true)

Environment Setup

The server requires Bitbucket credentials to be set up as environment variables:

export BITBUCKET_USERNAME="your-username"
export BITBUCKET_APP_PASSWORD="your-app-password"

Creating Bitbucket App Password

  1. Go to Bitbucket Settings β†’ App passwords

  2. Create a new app password with these permissions:

    • Repositories: Read, Write, Admin (for delete operations)

    • Pull requests: Read, Write

    • Issues: Read, Write

    • Account: Read (for workspace operations)

Claude Desktop Configuration

Add this configuration to your claude_desktop_config.json:

Windows

{
  "mcpServers": {
    "bitbucket-api": {
      "command": "C:\\\\Users\\\\YOURUSERNAME\\\\.local\\\\bin\\\\uv.exe",
      "args": [
        "--directory",
        "D:\\\\mcp\\\\mcp-bitbucket",
        "run",
        "-m",
        "mcp_bitbucket.server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Mac and Linux

{
  "mcpServers": {
    "bitbucket-api": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/mcp-bitbucket",
        "-m", "mcp_bitbucket.server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

⚠️ Important: You must restart Claude Desktop after modifying the configuration file.

Usage

Once configured, the Bitbucket tools will be available in Claude Desktop. You can:

  • Ask Claude to create repositories and branches

  • Read and write files in your repositories

  • Create and manage issues

  • Search for repositories

  • Create pull requests

  • Manage repository files

Example queries:

  • "Create a new repository called 'my-project' in my personal workspace"

  • "Create a new branch called 'feature-xyz' in the my-project repository"

  • "Create a README.md file in my-project with some basic content"

  • "Search for repositories that contain 'python' in the name"

Workspace Configuration

The tools default to the "kallows" workspace, but you can:

  • Specify a different workspace using the workspace parameter

  • Use workspace='~' to work with your personal workspace

  • Create repositories in team workspaces if you have permissions

Running Tests

The project includes unit and integration tests:

# Run all tests
python -m unittest discover tests

# Run specific test files
python -m unittest tests.test_bb_api
python -m unittest tests.test_bb_integration

# Run with verbose output
python -m unittest discover tests -v

Development

Adding New Tools

  1. Add the tool definition to handle_list_tools() in server.py

  2. Add the implementation to handle_call_tool() in server.py

  3. Add corresponding tests

  4. Update this README

Error Handling

The server includes comprehensive error handling:

  • Permission errors with helpful guidance

  • Network connectivity issues

  • Invalid parameters and validation

  • Bitbucket API rate limiting

Project Structure

mcp-bitbucket/
β”œβ”€β”€ README.md
β”œβ”€β”€ pyproject.toml
β”œβ”€β”€ uv.lock
β”œβ”€β”€ .gitignore
β”œβ”€β”€ .python-version
β”œβ”€β”€ src/
β”‚   └── mcp_bitbucket/
β”‚       β”œβ”€β”€ __init__.py
β”‚       └── server.py
└── tests/
    β”œβ”€β”€ README.md
    β”œβ”€β”€ test_bb_api.py
    └── test_bb_integration.py

License

This project is licensed under the MIT License.

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Add tests for your changes

  4. Ensure all tests pass

  5. Submit a pull request

Support

For issues and questions:

  • Check the Bitbucket API documentation

  • Verify your app password permissions

  • Review the test files for usage examples

  • Create an issue in this repository

Available Tools

10 tools
bb_create_branchC

Create a new branch in a Bitbucket repository

Inputs: branch (required), repo_slug (required), start_point, workspace.

bb_create_issueC

Create an issue in a Bitbucket repository

Inputs: content (required), repo_slug (required), title (required), kind, +2 more.

bb_create_pull_requestC

Create a new pull request in a Bitbucket repository

Inputs: repo_slug (required), source_branch (required), title (required), close_source_branch, +3 more.

bb_create_repositoryC

Create a new repository in Bitbucket

Inputs: name (required), description, has_issues, is_private, +2 more.

bb_delete_fileC

Delete a file from a Bitbucket repository

Inputs: path (required), repo_slug (required), branch, message, +1 more.

bb_delete_issueC

Delete an issue from a Bitbucket repository

Inputs: issue_id (required), repo_slug (required), workspace.

bb_delete_repositoryC

Delete a repository from Bitbucket

Inputs: repo_slug (required), workspace.

bb_read_fileC

Read a file from a Bitbucket repository

Inputs: path (required), repo_slug (required), branch, workspace.

bb_search_repositoriesA

Search repositories in Bitbucket using Bitbucket's query syntax. Search by name (name ~ "pattern"), project key (project.key = "PROJ"), language (language = "python"), or dates (updated_on >= "2024-01-19"). NOTE: All dates must be in ISO 8601 format (YYYY-MM-DD). For searching files within repositories, use Bitbucket's code search in the web interface.

Inputs: query (required), page, pagelen, workspace.

bb_write_fileC

Write/update a file in a Bitbucket repository

Inputs: content (required), path (required), repo_slug (required), branch, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 10 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose targeting specific Bitbucket resources and actions, with no overlap or ambiguity. For example, bb_create_branch, bb_create_issue, and bb_create_pull_request each handle different creation operations, while bb_read_file and bb_write_file are distinct file operations.

    Naming Consistency5/5

    All tools follow a consistent 'bb_verb_noun' pattern throughout, using snake_case and starting with 'bb_' as a prefix. This predictable naming convention makes it easy to understand each tool's function at a glance, with no deviations or mixed styles.

    Tool Count5/5

    With 10 tools, the server is well-scoped for Bitbucket operations, covering repository, branch, issue, pull request, and file management. Each tool earns its place by addressing a core functionality without being overly broad or sparse, fitting typical server tool counts of 3-15.

    Completeness4/5

    The tool set provides strong CRUD/lifecycle coverage for Bitbucket's key resources, including create/delete for repositories, issues, and files, and create for branches and pull requests. A minor gap exists in update operations (e.g., updating issues or pull requests), but agents can work around this with create/delete or other methods.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      C
      maintenance
      MCP server for integrating with Bitbucket Cloud and Server APIs, enabling AI assistants to interact with repositories, pull requests, pipelines, and more.
      59
      33 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Bitbucket Cloud that exposes 35 tools covering repositories, pull requests, branching models, and pipelines, enabling AI clients to automate Bitbucket workflows.
      3
      MIT