MCP Bitbucket Python

MCP Bitbucket Python provides a local MCP server that exposes Bitbucket operations to AI-powered tools running on the same machine. It enables secure, context-aware actions like creating repositories, managing files, and handling issues without exposing credentials over the network."

How to use

You interact with the Bitbucket MCP server through your MCP client. After you set up the environment variables for Bitbucket credentials, you launch the local server and call its tools to perform common Bitbucket tasks. You can create repositories and branches, read or write files, manage issues, search repositories, create pull requests, and more. All actions are performed locally via the MCP interface, keeping your credentials secure on your machine.

How to install

Prerequisites you need before installing:
- Git
- Python (for building dependencies if you choose pip) or uv runtime for running the server directly
- Access to a Bitbucket account to generate an app password (for authentication) and set environment variables
- A compatible MCP client to connect to the server (for example, Claude Desktop)

Step 1: Clone the MCP Bitbucket project

git clone https://github.com/kallows/mcp-bitbucket.git

Step 2: Change into the project directory

cd mcp-bitbucket

Step 3: Install dependencies using uv (recommended) or pip

uv install

 or

pip install -e .

Step 4: Start or prepare the MCP server runtime according to your environment (see the runtime commands in the configuration section below)

Additional sections

Environment setup for Bitbucket credentials

• Set these environment variables in your shell before starting the server:
• BITBUCKET_USERNAME
• BITBUCKET_APP_PASSWORD
• Example (Unix-like shells):

export BITBUCKET_APP_PASSWORD="your-app-password"```- Example (Windows PowerShell):```$env:BITBUCKET_USERNAME = "your-username"
$env:BITBUCKET_APP_PASSWORD = "your-app-password"```
- To create an app password with the necessary permissions, follow Bitbucket's guided flow to generate a password with Read/Write/Admin for Repositories, Read/Write for Pull requests, Read/Write for Issues, and Read for Account access.

## Environment and runtime notes

The server is designed to run locally on the same machine as your AI application. It relies on your Bitbucket credentials stored in environment variables to authenticate API calls. When you develop or test, keep credentials secure and avoid exposing them in logs or external calls.

## Usage targets and examples

You can perform a wide range of Bitbucket operations through the MCP interface, such as creating repositories, creating branches, reading and writing files, creating and deleting issues, searching repositories, and creating pull requests. Use clear, descriptive parameters for repository names, workspace IDs, branch names, and file paths to ensure operations execute as intended.

## Available tools

### bb\_create\_repository

Create a new Bitbucket repository with required name and optional metadata like description, workspace, project\_key, is\_private, and has\_issues.

### bb\_create\_branch

Create a new branch in a repository with required repo\_slug and branch, plus optional workspace and start\_point.

### bb\_delete\_repository

Delete a Bitbucket repository by repo\_slug, with optional workspace.

### bb\_read\_file

Read a file from a repository by repo\_slug and path, with optional workspace and branch.

### bb\_write\_file

Create or update a file in a repository by repo\_slug, path, and content, with optional workspace, branch, and commit message.

### bb\_create\_issue

Create an issue in a repository with required repo\_slug, title, and content; optional kind and priority.

### bb\_delete\_issue

Delete an issue by issue\_id within a repository, with optional workspace.

### bb\_search\_repositories

Search Bitbucket repositories using a query string with optional workspace, page, and pagelen.

### bb\_delete\_file

Delete a file from a repository by repo\_slug and path, with optional workspace, branch, and commit message.

### bb\_create\_pull\_request

Create a pull request with required repo\_slug, title, and source\_branch; optional destination\_branch, description, and close\_source\_branch.