MCP Bitbucket Python
Provides tools for repository management (creating, deleting, searching), branch operations, file handling (read, write, delete), issue tracking (creating, deleting issues), and pull request creation in Bitbucket repositories.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Bitbucket Python create a new branch called 'feature-login' in the auth-service repository"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 .Related MCP server: bitbucket-python-mcp
Tools Available
This MCP server provides the following Bitbucket integration tools:
bb_create_repository: Create a new Bitbucket repositoryRequired: 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 repositoryRequired: repo_slug, branch (name for the new branch)
Optional: workspace (defaults to kallows), start_point (defaults to main)
bb_delete_repository: Delete a Bitbucket repositoryRequired: repo_slug
Optional: workspace (defaults to kallows)
bb_read_file: Read a file from a repositoryRequired: 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 repositoryRequired: repo_slug, path, content
Optional: workspace (defaults to kallows), branch (defaults to main), message (commit message)
bb_create_issue: Create an issue in a repositoryRequired: 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 repositoryRequired: repo_slug, issue_id
Optional: workspace (defaults to kallows)
bb_search_repositories: Search Bitbucket repositories using query syntaxRequired: 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 repositoryRequired: repo_slug, path
Optional: workspace (defaults to kallows), branch (defaults to main), message (commit message)
bb_create_pull_request: Create a pull requestRequired: 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
Go to Bitbucket Settings β App passwords
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
workspaceparameterUse
workspace='~'to work with your personal workspaceCreate 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 -vDevelopment
Adding New Tools
Add the tool definition to
handle_list_tools()inserver.pyAdd the implementation to
handle_call_tool()inserver.pyAdd corresponding tests
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.pyLicense
This project is licensed under the MIT License.
Contributing
Fork the repository
Create a feature branch
Add tests for your changes
Ensure all tests pass
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
Available Tools
10 toolsbb_create_branchC
Create a new branch in a Bitbucket repository
Inputs: branch (required), repo_slug (required), start_point, workspace.
bb_create_issueC
Create an issue in a Bitbucket repository
Inputs: content (required), repo_slug (required), title (required), kind, +2 more.
bb_create_pull_requestC
Create a new pull request in a Bitbucket repository
Inputs: repo_slug (required), source_branch (required), title (required), close_source_branch, +3 more.
bb_create_repositoryC
Create a new repository in Bitbucket
Inputs: name (required), description, has_issues, is_private, +2 more.
bb_delete_fileC
Delete a file from a Bitbucket repository
Inputs: path (required), repo_slug (required), branch, message, +1 more.
bb_delete_issueC
Delete an issue from a Bitbucket repository
Inputs: issue_id (required), repo_slug (required), workspace.
bb_delete_repositoryC
Delete a repository from Bitbucket
Inputs: repo_slug (required), workspace.
bb_read_fileC
Read a file from a Bitbucket repository
Inputs: path (required), repo_slug (required), branch, workspace.
bb_search_repositoriesA
Search repositories in Bitbucket using Bitbucket's query syntax. Search by name (name ~ "pattern"), project key (project.key = "PROJ"), language (language = "python"), or dates (updated_on >= "2024-01-19"). NOTE: All dates must be in ISO 8601 format (YYYY-MM-DD). For searching files within repositories, use Bitbucket's code search in the web interface.
Inputs: query (required), page, pagelen, workspace.
bb_write_fileC
Write/update a file in a Bitbucket repository
Inputs: content (required), path (required), repo_slug (required), branch, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 10 tools
Every tool has a clearly distinct purpose targeting specific Bitbucket resources and actions, with no overlap or ambiguity. For example, bb_create_branch, bb_create_issue, and bb_create_pull_request each handle different creation operations, while bb_read_file and bb_write_file are distinct file operations.
All tools follow a consistent 'bb_verb_noun' pattern throughout, using snake_case and starting with 'bb_' as a prefix. This predictable naming convention makes it easy to understand each tool's function at a glance, with no deviations or mixed styles.
With 10 tools, the server is well-scoped for Bitbucket operations, covering repository, branch, issue, pull request, and file management. Each tool earns its place by addressing a core functionality without being overly broad or sparse, fitting typical server tool counts of 3-15.
The tool set provides strong CRUD/lifecycle coverage for Bitbucket's key resources, including create/delete for repositories, issues, and files, and create for branches and pull requests. A minor gap exists in update operations (e.g., updating issues or pull requests), but agents can work around this with create/delete or other methods.
Maintenance
Related MCP Connectors
Nifty's MCP server β exposes tasks, projects, messages, and files as tools for AI agents.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yoβ¦
A MCP server built for developers enabling Git based project management with project and personalβ¦
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Related MCP Servers
- AlicenseCqualityCmaintenanceMCP server for integrating with Bitbucket Cloud and Server APIs, enabling AI assistants to interact with repositories, pull requests, pipelines, and more.5933 npm3MIT
- AlicenseAqualityDmaintenanceAn MCP server for BitBucket Cloud operations that enables AI agents to manage repositories, branches, pull requests, and search code.3228 PyPIMIT
- FlicenseBqualityDmaintenanceMCP server for Bitbucket Cloud that enables AI agents to manage repositories, branches, pull requests, and deployments via typed tools.17-
- AlicenseNot gradedqualityDmaintenanceMCP server for Bitbucket Cloud that exposes 35 tools covering repositories, pull requests, branching models, and pipelines, enabling AI clients to automate Bitbucket workflows.3MIT