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:

Variable	Required	Description
BITBUCKET_USERNAME	Yes	Your BitBucket username (not email)
BITBUCKET_API_TOKEN	Yes	App password/API token from BitBucket settings
BITBUCKET_WORKSPACE	Yes	Default workspace slug
BITBUCKET_MCP_DEBUG	No	Enable debug logging (1/true/yes)

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

Tool	Description
list_repositories	List all repositories in a workspace
get_repository	Get detailed repository information
create_repository	Create a new repository
delete_repository	Delete a repository (requires confirmation)
update_repository	Update repository settings

Branch Tools

Tool	Description
list_branches	List all branches in a repository
get_branch	Get branch details
create_branch	Create a new branch
delete_branch	Delete a branch (requires confirmation)

Pull Request Tools

Tool	Description
list_pull_requests	List pull requests (open/merged/declined)
get_pull_request	Get PR details (defaults to newest)
get_pull_request_diff	Get the diff for a PR
get_pull_request_comments	Get all comments on a PR
add_pull_request_comment	Add a comment (general or inline)
approve_pull_request	Approve a PR
request_changes	Request changes on a PR
create_pull_request	Create a new PR

Search Tools

Tool	Description
search_repositories	Search for repositories by name
get_repository_contents	Browse repository files/directories
search_code	Search for code patterns
get_file_content	Get raw file content

Memory Tools

Tool	Description
add_memory	Store a new learning/standard for future reference
list_memories	List stored memories filtered by workspace/category
search_memories	Search memories by keyword
get_relevant_memories	Get memories relevant to current context
delete_memory	Delete a stored memory
remember_from_pr_comment	Extract and store learning from a PR comment

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