BitBucket MCP Server

A Model Context Protocol (MCP) server for BitBucket Cloud operations. This server enables AI coding agents like Claude Code CLI and Codex CLI to interact with BitBucket repositories, branches, and pull requests.

Features

• Repository Management: Create, delete, update, and list repositories
• Branch Management: Create, delete, and list branches
• Pull Request Operations: Create, review, approve, comment on pull requests
• Code Search: Search repositories and browse file contents
• Memory System: Store and retrieve workspace standards and learnings from PR reviews
• Auto-detection: Automatically detects current BitBucket repository from git remote

Installation

Using uvx (Recommended)

uvx bitbucket-python-mcp

Using pip

pip install bitbucket-python-mcp

From Source

git clone https://github.com/yourusername/bitbucket-python-mcp.git
cd bitbucket-python-mcp
uv sync

Configuration

The server requires the following environment variables:

Creating an App Password

1. Go to BitBucket App Passwords
2. Click "Create app password"
3. Give it a descriptive name (e.g., "MCP Server")
4. Select the required permissions:
   • Repositories: Read, Write, Admin (for create/delete)
   • Pull requests: Read, Write
5. Click "Create" and copy the generated password

Usage with AI Agents

Claude Code CLI

Add to your ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bitbucket": {
      "command": "uvx",
      "args": ["bitbucket-python-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_API_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      }
    }
  }
}

OpenAI Codex CLI

Add to your ~/.codex/config.toml:

[mcp_servers.bitbucket]
command = "uvx"
args = ["bitbucket-python-mcp"]

[mcp_servers.bitbucket.env]
BITBUCKET_USERNAME = "your-username"
BITBUCKET_API_TOKEN = "your-api-token"
BITBUCKET_WORKSPACE = "your-workspace"

Alternatively, use the Codex CLI to add the server:

codex mcp add bitbucket \
  --env BITBUCKET_USERNAME=your-username \
  --env BITBUCKET_API_TOKEN=your-api-token \
  --env BITBUCKET_WORKSPACE=your-workspace \
  -- uvx bitbucket-python-mcp

Verify the server is configured:

codex mcp list

Running Locally

# Set environment variables
export BITBUCKET_USERNAME="your-username"
export BITBUCKET_API_TOKEN="your-api-token"
export BITBUCKET_WORKSPACE="your-workspace"

# Run the server
uvx bitbucket-python-mcp
# or
uv run bitbucket-python-mcp

Available Tools

Repository Tools

Branch Tools

Pull Request Tools

Search Tools

Memory Tools

Memories are stored in ~/.bitbucket-python-mcp/memory/ and persist across sessions.

Examples

Create a Repository

User: Create a new private repository named "my-new-project" with description "My awesome project"

Create a Branch

User: Create a new branch named "feature-login" from development

Review a Pull Request

User: Show me the details of the newest pull request
User: What are the comments on PR #42?
User: Approve PR #42

Search Code

User: Search for "authentication" in the project-api repository
User: Show me the contents of src/main.py

Store and Retrieve Memories

User: Remember that we should use shared-pipeline for SonarQube scans
User: What standards should I follow for this workspace?
User: Search memories for "pipeline"

Development

Setup

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

# Install dependencies
uv sync --all-extras

# or using just
just install-dev

Running Tests

uv run pytest

# or using just
just test

Linting

uv run ruff check src tests
uv run ruff format src tests

# or using just
just fmt
just lint

Building

uv build

# or using just
just build

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

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

Acknowledgments

• Model Context Protocol - The protocol specification
• atlassian-python-api - BitBucket API client