Bitbucket MCP Server

How to use

After you start the MCP server, you connect your MCP client to the server’s endpoint and begin issuing high-level actions such as listing repositories, creating a pull request, triggering a pipeline, or reading a file. This server translates those actions into Bitbucket API calls and returns structured results that you can display in your MCP client. Practical use cases include automating repository setup, auditing branch protections, reviewing PR diffs, and tracking deployment histories across environments.

How to install

Prerequisites: you need Python 3.11+ and a working Python package manager. For local development and usage, you will also use uv or uvicorn for serving the MCP endpoint.

# Install the Bitbucket MCP Server from PyPI
pipx install mcp-server-bitbucket

# Or install via pip
pip install mcp-server-bitbucket

# Start the local MCP server in stdio mode (example runtime command)
uv run python -m src.server

# Or run the HTTP server variant for remote deployment (development example)
uv run uvicorn src.http_server:app --reload --port 8080

Configuration and remote deployment

You can connect Claude Code or other MCP clients to a remote deployment of the MCP server. To connect, you typically provide the remote URL where the MCP endpoint is exposed and, if required, an authentication header.

{
  "mcpServers": {
    "bitbucket_http": {
      "type": "http",
      "url": "https://your-deployment-url.com/mcp",
      "args": []
    },
    "bitbucket_stdio": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "src.server"]
    }
  }
}

Security and credentials

Keep Bitbucket credentials and API tokens on the server side. Do not expose tokens in client configurations. Use environment variables or secret management provided by your hosting environment to supply tokens like BITBUCKET_WORKSPACE, BITBUCKET_EMAIL, and BITBUCKET_API_TOKEN when the client connects.

list_repositories

List and search repositories in the Bitbucket workspace; supports fuzzy name matching.

get_repository

Retrieve details for a specific repository.

create_repository

Create a new repository in the workspace.

delete_repository

Delete an existing repository.

update_repository

Update repository settings such as project, visibility, description, or name.

list_branches

List branches in a repository.

get_branch

Get details for a specific branch.

list_commits

List commits with optional filters by branch or file path.

get_commit

Get details for a specific commit.

compare_commits

Compare two commits or branches and view diff statistics.

list_tags

List tags in a repository.

create_tag

Create a new tag in a repository.

delete_tag

Delete a tag from a repository.

list_branch_restrictions

List branch protection rules for a repository.

create_branch_restriction

Create a branch protection rule.

delete_branch_restriction

Delete a branch protection rule.

get_file_content

Read a file's contents without cloning the repository.

list_directory

List contents of a directory in the repository.

get_commit_statuses

Get build/CI statuses associated with a commit.

create_commit_status

Report a build status from an external CI system.

list_pull_requests

List pull requests for a repository.

get_pull_request

Get details for a pull request.

create_pull_request

Create a new pull request.

merge_pull_request

Merge a pull request.

approve_pr

Approve a pull request.

unapprove_pr

Remove your approval from a pull request.

request_changes_pr

Request changes on a pull request.

decline_pr

Close a pull request.

list_pr_comments

List comments on a pull request.

add_pr_comment

Add a comment to a pull request.

get_pr_diff

Get the diff for a pull request.

list_pipelines

List recent pipeline runs for a repository.

get_pipeline

Get the status of a pipeline run.

get_pipeline_logs

View logs for a pipeline run.

trigger_pipeline

Trigger a new pipeline run.

stop_pipeline

Stop a running pipeline.

list_pipeline_variables

List CI/CD variables for a repository.

get_pipeline_variable

Get details for a pipeline variable.

create_pipeline_variable

Create a new pipeline variable.

update_pipeline_variable

Update a pipeline variable value.

delete_pipeline_variable

Delete a pipeline variable.

list_environments

List deployment environments (e.g., test, staging, prod) for a repository.

get_environment

Get details for a deployment environment.

list_deployment_history

Retrieve deployment history for an environment.

list_webhooks

List configured webhooks for a repository.

create_webhook

Create a new webhook.

get_webhook

Get details for a webhook.

delete_webhook

Delete a webhook.

list_user_permissions

List user permissions for a repository.

get_user_permission

Get a specific user's permission for a repository.

update_user_permission

Add or update user permission for a repository.

delete_user_permission

Remove a user's permission from a repository.

list_group_permissions

List group permissions for a repository.

get_group_permission

Get a specific group's permission for a repository.

update_group_permission

Add or update group permission for a repository.

delete_group_permission

Remove a group's permission from a repository.

list_projects

List projects in the workspace.

get_project

Get details for a project.