Skip to main content
Glama

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 .

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
Install Server
A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

local-only server

The server can only run on the client's local machine because it depends on local resources.

A Python implementation of an MCP server that enables secure, local Bitbucket integration for AI applications, providing tools for repository management, branch creation, file operations, issue tracking, and pull request creation.

  1. Installation
    1. Tools Available
      1. Environment Setup
        1. Project Structure

          Related MCP Servers

          • -
            security
            F
            license
            -
            quality
            A Python implementation of the MCP server that enables AI models to connect with external tools and data sources through a standardized protocol, supporting tool invocation and resource access via JSON-RPC.
            Last updated -
            1
            Python
          • A
            security
            A
            license
            A
            quality
            An MCP server that enables interaction with Bitbucket repositories through the Model Context Protocol, supporting both Bitbucket Cloud and Server with features for PR lifecycle management and code review.
            Last updated -
            19
            1,318
            7
            TypeScript
            MIT License
          • -
            security
            A
            license
            -
            quality
            A dynamic MCP server that automatically discovers Python files in a directory and exposes them as tools to any MCP-compatible AI client, allowing users to easily create and deploy custom AI tools.
            Last updated -
            Python
            MIT License
          • -
            security
            F
            license
            -
            quality
            A high-speed MCP server that enables AI assistants like Claude to interact with local filesystems, manage Git repositories, and provide interactive experiences through a standardized JSON-based protocol.
            Last updated -
            3
            Python
            • Apple

          View all related MCP servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/Kallows/mcp-bitbucket'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server