Bitbucket MCP Server

A local Model Context Protocol (MCP) server that enables Claude to browse and interact with Bitbucket repositories directly. This server runs on your machine and provides tools to list repositories, branches, read files, and view commits.

Features

• List Repositories - View all repositories in your Bitbucket workspace
• List Branches - Browse all branches in a repository
• Read Files - Access file contents from your repositories
• List Commits - View commit history
• Local Execution - Runs entirely on your machine (no data sent to external servers)

Prerequisites

• Python 3.10 or newer
• Claude Code or Claude with MCP support
• Bitbucket account with API access

Setup Instructions

1. Install Python Dependencies

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\Activate.ps1
pip install -r requirements.txt

2. Configure Credentials

Create a .env file in the project root with your Bitbucket credentials:

BITBUCKET_USERNAME=your-email@example.com
BITBUCKET_WORKSPACE=your-workspace-id
BITBUCKET_APP_PASSWORD=your-api-token

How to get your credentials:

• Username: Your Atlassian/Bitbucket email
• Workspace ID: The workspace slug from bitbucket.org/<workspace-id>/
• App Password: Generate at Bitbucket Account Settings → Personal Bitbucket settings → App passwords

3. Connect to Claude Code

1. Open Claude Code
2. Go to Settings → MCP Servers
3. Add a new server with these settings:
   • Name: bitbucket-mcp
   • Command: python /path/to/bitbucket_mcp/main.py
4. Save and restart Claude Code

Usage

Once connected, you can ask Claude:

• "List all repositories in my workspace"
• "Show me the branches in the main-app repo"
• "Read the contents of src/main.py from my-repo"
• "Show recent commits in my-project"

Project Structure

.
├── main.py              # Entry point
├── server.py            # MCP server implementation
├── bitbucket.py         # Bitbucket API client
├── requirements.txt     # Python dependencies
├── .env                 # Credentials (create this)
└── SETUP.txt           # Additional setup notes

Requirements

• mcp>=1.0.0 - Model Context Protocol
• httpx>=0.27.0 - HTTP client
• python-dotenv>=1.0.0 - Environment variable management

Troubleshooting

• "Module not found" error: Make sure you activated the virtual environment and ran pip install -r requirements.txt
• Authentication failed: Verify your .env file has correct credentials
• Server won't start: Check that Python 3.10+ is installed