Bitbucket Server MCP

An MCP (Model Context Protocol) server for Atlassian Bitbucket Server / Data Center (Enterprise). Provides 66 tools for reading and writing projects, repositories, branches, files, commits, pull requests, and code search — with opt-in gated deletion operations (disabled by default, see SECURITY.md.

Installation

From PyPI (recommended)

pip install bitbucket-server-mcp

Or with uv:

uv pip install bitbucket-server-mcp

From source

git clone https://github.com/ManpreetShuann/bitbucket-server-mcp.git
cd bitbucket-server-mcp
uv sync

Via Docker (no local Python required)

cd bitbucket-server-mcp
docker build -t bitbucket-server-mcp .

Prerequisites

Python 3.10+
Bitbucket Server 7.x+ with HTTP access tokens enabled

Configuration

Set two required environment variables (plus optional ones):

Variable	Required	Description
`BITBUCKET_URL`	Yes	Base URL of your Bitbucket Server (e.g., `https://bitbucket.yourcompany.com`). Must use HTTPS.
`BITBUCKET_TOKEN`	Yes	HTTP access token (create in Bitbucket > User Settings > HTTP Access Tokens)
`BITBUCKET_LOG_LEVEL`	No	Log level for stderr output: `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`)
`BITBUCKET_ALLOW_DANGEROUS_DELETE`	No	Set to `1` to enable Tier-1 delete tools (branch, tag, PR, comment, task, attachment)
`BITBUCKET_ALLOW_DESTRUCTIVE_DELETE`	No	Set to `1` to enable Tier-2 delete tools (project, repository). Requires `BITBUCKET_ALLOW_DANGEROUS_DELETE=1`

Integration

This server runs locally via stdio rather than as a hosted HTTP service. Running locally keeps your Bitbucket access token on your own machine, avoids exposing an authenticated API endpoint over the network, and removes the need to manage server infrastructure or TLS certificates.

Claude Code

Add to ~/.claude.json or project .claude/settings.json:

With pip (recommended)

pip install bitbucket-server-mcp

{
  "mcpServers": {
    "bitbucket": {
      "command": "bitbucket-server-mcp",
      "env": {
        "BITBUCKET_URL": "https://bitbucket.yourcompany.com",
        "BITBUCKET_TOKEN": "your-token-here"
      }
    }
  }
}

With Docker

{
  "mcpServers": {
    "bitbucket": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "BITBUCKET_URL", "-e", "BITBUCKET_TOKEN", "bitbucket-server-mcp"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.yourcompany.com",
        "BITBUCKET_TOKEN": "your-token-here"
      }
    }
  }
}

With uv (from source, for development)

git clone https://github.com/ManpreetShuann/bitbucket-server-mcp.git
cd bitbucket-server-mcp
uv sync

{
  "mcpServers": {
    "bitbucket": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/bitbucket-server-mcp", "bitbucket-server-mcp"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.yourcompany.com",
        "BITBUCKET_TOKEN": "your-token-here"
      }
    }
  }
}

GitHub Copilot (VS Code)

Add to .vscode/mcp.json in your workspace:

With pip (recommended)

pip install bitbucket-server-mcp

{
  "servers": {
    "bitbucket": {
      "type": "stdio",
      "command": "bitbucket-server-mcp",
      "env": {
        "BITBUCKET_URL": "https://bitbucket.yourcompany.com",
        "BITBUCKET_TOKEN": "${input:bitbucket-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "bitbucket-token",
      "description": "Bitbucket Server HTTP access token",
      "password": true
    }
  ]
}

With Docker

{
  "servers": {
    "bitbucket": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "BITBUCKET_URL", "-e", "BITBUCKET_TOKEN", "bitbucket-server-mcp"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.yourcompany.com",
        "BITBUCKET_TOKEN": "${input:bitbucket-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "bitbucket-token",
      "description": "Bitbucket Server HTTP access token",
      "password": true
    }
  ]
}

With uv (from source, for development)

git clone https://github.com/ManpreetShuann/bitbucket-server-mcp.git
cd bitbucket-server-mcp
uv sync

{
  "servers": {
    "bitbucket": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/bitbucket-server-mcp", "bitbucket-server-mcp"],
      "env": {
        "BITBUCKET_URL": "https://bitbucket.yourcompany.com",
        "BITBUCKET_TOKEN": "${input:bitbucket-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "bitbucket-token",
      "description": "Bitbucket Server HTTP access token",
      "password": true
    }
  ]
}

OpenAI Codex

Add to ~/.codex/config.toml:

With pip (recommended)

pip install bitbucket-server-mcp

[mcp_servers.bitbucket]
command = "bitbucket-server-mcp"
args = []

[mcp_servers.bitbucket.env]
BITBUCKET_URL = "https://bitbucket.yourcompany.com"
BITBUCKET_TOKEN = "your-token-here"

Or via CLI:

codex mcp add bitbucket \
  --env BITBUCKET_URL=https://bitbucket.yourcompany.com \
  --env BITBUCKET_TOKEN=your-token-here \
  -- bitbucket-server-mcp

With Docker

[mcp_servers.bitbucket]
command = "docker"
args = ["run", "--rm", "-i", "-e", "BITBUCKET_URL", "-e", "BITBUCKET_TOKEN", "bitbucket-server-mcp"]

[mcp_servers.bitbucket.env]
BITBUCKET_URL = "https://bitbucket.yourcompany.com"
BITBUCKET_TOKEN = "your-token-here"

Or via CLI:

codex mcp add bitbucket \
  --env BITBUCKET_URL=https://bitbucket.yourcompany.com \
  --env BITBUCKET_TOKEN=your-token-here \
  -- docker run --rm -i -e BITBUCKET_URL -e BITBUCKET_TOKEN bitbucket-server-mcp

With uv (from source, for development)

git clone https://github.com/ManpreetShuann/bitbucket-server-mcp.git
cd bitbucket-server-mcp
uv sync

[mcp_servers.bitbucket]
command = "uv"
args = ["run", "--directory", "/path/to/bitbucket-server-mcp", "bitbucket-server-mcp"]

[mcp_servers.bitbucket.env]
BITBUCKET_URL = "https://bitbucket.yourcompany.com"
BITBUCKET_TOKEN = "your-token-here"

Or via CLI:

codex mcp add bitbucket \
  --env BITBUCKET_URL=https://bitbucket.yourcompany.com \
  --env BITBUCKET_TOKEN=your-token-here \
  -- uv run --directory /path/to/bitbucket-server-mcp bitbucket-server-mcp

Tools (66 total)

Projects

Tool	Description
`list_projects`	List all projects (paginated)
`get_project`	Get project details by key

Repositories

Tool	Description
`list_repositories`	List repos in a project (paginated)
`get_repository`	Get repo details
`create_repository`	Create a new repo

Branches & Tags

Tool	Description
`list_branches`	List branches (paginated, filterable)
`get_default_branch`	Get default branch
`create_branch`	Create a branch from a start point
`list_tags`	List tags (paginated, filterable)

Files & Content

Tool	Description
`browse_files`	Browse directory/file tree at a path and revision
`get_file_content`	Get raw file content
`list_files`	List file paths in a directory

Commits

Tool	Description
`list_commits`	List commits (paginated, filterable by branch/path)
`get_commit`	Get commit details
`get_commit_diff`	Get diff for a commit
`get_commit_changes`	Get changed files for a commit

Pull Requests

Tool	Description
`list_pull_requests`	List PRs with state/direction/draft/title/participant filters (paginated)
`get_pull_request`	Get PR details
`create_pull_request`	Create a PR with reviewers (supports draft mode)
`update_pull_request`	Update PR title/description/reviewers/draft status
`create_draft_pull_request`	Create a PR in draft mode
`publish_draft_pull_request`	Publish a draft PR (mark as ready for review)
`convert_to_draft`	Convert an open PR back to draft
`can_merge_pull_request`	Check merge readiness (canMerge, conflicts, vetoes)
`merge_pull_request`	Merge a PR with optional strategy
`decline_pull_request`	Decline a PR
`reopen_pull_request`	Reopen a declined PR
`approve_pull_request`	Approve a PR
`unapprove_pull_request`	Remove your approval
`request_changes_pull_request`	Request changes on a PR
`remove_change_request_pull_request`	Remove your change request
`list_pull_request_participants`	List reviewers with roles and statuses
`watch_pull_request`	Subscribe as a watcher
`unwatch_pull_request`	Unsubscribe from watching
`get_commit_message_suggestion`	Get suggested commit message for merge
`get_pull_request_diff`	Get PR diff
`get_pull_request_diff_stat`	Get per-file change list (added/modified/deleted)
`list_pull_request_commits`	List commits in a PR
`get_pull_request_activities`	Get PR activity feed
`list_pull_request_comments`	List comments on a PR
`get_pull_request_comment`	Get a specific comment
`add_pull_request_comment`	Add a comment (general, inline, reply, or blocker task)
`update_pull_request_comment`	Edit a comment
`resolve_pull_request_comment`	Resolve a comment thread
`reopen_pull_request_comment`	Reopen a resolved thread
`list_pull_request_tasks`	List PR tasks
`create_pull_request_task`	Create a task (optionally linked to a comment)
`get_pull_request_task`	Get a specific task
`update_pull_request_task`	Update task content or state

Dashboard

Tool	Description
`list_dashboard_pull_requests`	List PRs visible to the authenticated user across all repos (paginated)
`list_inbox_pull_requests`	List PRs in the user's inbox needing review action (paginated)

Search

Tool	Description
`search_code`	Search code across repos (requires Elasticsearch)
`find_file`	Find files by name or path pattern with wildcards

Users

Tool	Description
`find_user`	Search users by name, username, or email

Attachments

Tool	Description
`get_attachment`	Download an attachment by ID
`get_attachment_metadata`	Get attachment metadata
`save_attachment_metadata`	Create or update attachment metadata

Dangerous Delete (Tier-1, requires `BITBUCKET_ALLOW_DANGEROUS_DELETE=1`)

Tool	Description
`delete_branch`	Delete a branch (irreversible)
`delete_tag`	Delete a tag (irreversible)
`delete_pull_request`	Delete a PR and all its contents
`delete_pull_request_comment`	Delete a PR comment
`delete_pull_request_task`	Delete a PR task
`delete_attachment`	Delete an attachment
`delete_attachment_metadata`	Delete attachment metadata

Destructive Delete (Tier-2, requires both `BITBUCKET_ALLOW_DANGEROUS_DELETE=1` and `BITBUCKET_ALLOW_DESTRUCTIVE_DELETE=1`)

Tool	Description
`delete_project`	Delete a project and all its repositories (irreversible)
`delete_repository`	Delete a repository and all its contents (irreversible)

Development

git clone https://github.com/ManpreetShuann/bitbucket-server-mcp.git
cd bitbucket-server-mcp
uv sync                # Install all dependencies (including dev)
uv run pytest -v       # Run tests
uv run ruff check src/ tests/   # Lint
uv run ruff format src/ tests/  # Format

See CONTRIBUTING.md for full development guidelines.

Pagination

All list tools accept start (default 0) and limit (default 25) parameters. Responses include isLastPage and nextPageStart for fetching subsequent pages.

Security

See SECURITY.md for our security policy and vulnerability reporting instructions.

License

MIT

Metadata

Release files for bitbucket-server-mcp 1.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bitbucket-server-mcp 1.7.0
File	Size	Uploaded
bitbucket_server_mcp-1.7.0.tar.gz	108.9 kB	Mar 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for bitbucket-server-mcp 1.7.0
File	Interpreter	ABI	Platform	Reset
bitbucket_server_mcp-1.7.0-py3-none-any.whl 32.7 kB Mar 23, 2026	Python 3	none	any	Details

Total release size: 141.7 kB

Release files / bitbucket_server_mcp-1.7.0.tar.gz

Download URL	bitbucket_server_mcp-1.7.0.tar.gz
Size	108.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`e124454e191b8b4f209a78a9676f0a56fefef28aa9db2a517c4da8f7419e50bf`
BLAKE2b-256 checksum How to use checksums	`1006aa6bf02724a5415181d69b401307e150e981bd6a7dc9347cd8c333d131eb`
Upload date	Mar 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ManpreetShuann/bitbucket-server-mcp
Publishing commit: github.com/ManpreetShuann/bitbucket-server-mcp/tree/91bcd705272435b94d7fd5fd03c947d24e6c16c0

Workflow

Publishing configuration: github.com/ManpreetShuann/bitbucket-server-mcp/blob/91bcd705272435b94d7fd5fd03c947d24e6c16c0/.github/workflows/release.yml
Publishing logs: github.com/ManpreetShuann/bitbucket-server-mcp/actions/runs/23431063832/attempts/1

Artifact

Subject: bitbucket_server_mcp-1.7.0.tar.gz
SHA-256 checksum: e124454e191b8b4f209a78a9676f0a56fefef28aa9db2a517c4da8f7419e50bf Verifying attestations

Release files / bitbucket_server_mcp-1.7.0-py3-none-any.whl

Download URL	bitbucket_server_mcp-1.7.0-py3-none-any.whl
Size	32.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`237433c5cc9ee73c3c78ba0adf93def41f22728a452d72275afcc656c02e3fd2`
BLAKE2b-256 checksum How to use checksums	`0b3517981befedf0a1e20460a6964fc21e33332f819839917e30ca6627cf7d37`
Upload date	Mar 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ManpreetShuann/bitbucket-server-mcp
Publishing commit: github.com/ManpreetShuann/bitbucket-server-mcp/tree/91bcd705272435b94d7fd5fd03c947d24e6c16c0

Workflow

Publishing configuration: github.com/ManpreetShuann/bitbucket-server-mcp/blob/91bcd705272435b94d7fd5fd03c947d24e6c16c0/.github/workflows/release.yml
Publishing logs: github.com/ManpreetShuann/bitbucket-server-mcp/actions/runs/23431063832/attempts/1

Artifact

Subject: bitbucket_server_mcp-1.7.0-py3-none-any.whl
SHA-256 checksum: 237433c5cc9ee73c3c78ba0adf93def41f22728a452d72275afcc656c02e3fd2 Verifying attestations