What can you do with this server?

mcp-bitbucket-dc is an MCP server that enables AI assistants to interact with Bitbucket Data Center for code search, file browsing, repository management, pull request operations, and commit history. * Code Search: Search code across all repositories using Lucene-style queries with filters for file extension, language, repository, project, and path * File Browsing: Browse directory trees, retrieve raw file content, and recursively list all file paths in a repository or subdirectory * Branch & Tag Management: List and filter branches and tags in a repository * Projects & Repositories: List projects and repositories, get detailed info including clone URLs * Pull Request Reading: List PRs with filters for state/direction/text, get full PR details, view comments and activity, see changed files, and view file-specific diffs * Pull Request Writing: Post general or inline code comments, create new pull requests, and update PR title/description/reviewers * Required Reviewers: Discover mandatory reviewers for a branch pair before creating a PR * Commit History: List commits with optional filters by file path or commit range Most tools support both human-readable markdown and raw JSON output, and the server supports local and remote deployments via SSE or Streamable HTTP transports.

Which integrations are available for this server?

Enables searching code, browsing files, managing pull requests, and exploring repositories and projects within a Bitbucket Data Center instance.

How do I use mcp-bitbucket-dc?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-bitbucket-dc Search for the DatabaseHelper class in the backend-api 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-dc

PyPI Version Main Push Checks CD: Publish to PyPI License: MIT

MCP (Model Context Protocol) server for Bitbucket Data Center. Enables AI assistants to search code, browse files, manage pull requests, and explore repositories through a standardized interface.

Built with FastMCP in Python. Installs via uvx.

Acknowledgements

Many tools in this project were inspired by atlassian-dc-mcp.
Code search functionality was inspired by @beapirate and prior related implementation work.

Quick Start

1. Generate a Personal Access Token

Log in to your Bitbucket Data Center instance
Go to Manage Account → HTTP access tokens
Click Create token
Set permissions: Repository Read (and Write if you need PR creation/commenting)
Copy the token

2. Configure Your IDE

Add to your MCP configuration (mcp.json in VS Code, claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "bitbucket-dc": {
      "command": "uvx",
      "args": ["mcp-bitbucket-dc"],
      "env": {
        "BITBUCKET_HOST": "git.yourcompany.com",
        "BITBUCKET_API_TOKEN": "your-personal-access-token"
      }
    }
  }
}

That's it. The server starts automatically when your IDE connects.

3. Start Using

Ask your AI assistant:

"Search for CompanyInfoUpdater in the codebase"
"Show me the file structure of the api-service repo in PROJECT"
"Get the content of src/main/Application.java from repo backend"
"List open pull requests in PROJECT/my-repo"
"What branches exist in PROJECT/my-repo?"

Tools Reference

Most read/query tools support response_format:

markdown (default): human-readable output
json: raw structured API response

Code Search

Tool	Description
`bitbucket_code_search`	Search code across all repos with Lucene syntax (`ext:java`, `lang:python`, `repo:name`, `project:KEY`, `AND`/`OR`/`NOT`)

File Browsing

Tool	Description
`bitbucket_browse`	Browse directory tree (files & folders at a path)
`bitbucket_get_file_content`	Get raw file content with syntax highlighting
`bitbucket_list_files`	Recursively list all file paths in a repo
`bitbucket_get_branches`	List branches (filterable)
`bitbucket_get_tags`	List tags (filterable)

Projects & Repositories

Tool	Description
`bitbucket_get_projects`	List projects (filterable by name/permission)
`bitbucket_get_project`	Get project details
`bitbucket_get_repositories`	List repos in a project
`bitbucket_get_repository`	Get repo details with clone URLs

Pull Requests

Tool	Description
`bitbucket_get_pull_requests`	List PRs (filter by state, direction, text)
`bitbucket_get_pull_request`	Get PR details with reviewers
`bitbucket_get_pull_request_comments`	Get PR comments and activity
`bitbucket_get_pull_request_changes`	Get files changed in a PR
`bitbucket_get_pull_request_diff`	Get diff for a file in a PR
`bitbucket_post_pull_request_comment`	Post a comment (general or inline)
`bitbucket_create_pull_request`	Create a new PR
`bitbucket_update_pull_request`	Update PR title/description/reviewers
`bitbucket_get_required_reviewers`	Get required reviewers for a branch pair

Commits

Tool	Description
`bitbucket_get_commits`	List commits (filter by path, ref range)

Search Query Syntax

The bitbucket_code_search tool uses Lucene-style queries:

# Simple text search
CompanyInfoUpdater

# Filter by file extension
function ext:java

# Filter by language
config lang:python

# Filter by repository or project
DatabaseHelper repo:backend-api
service project:PLATFORM

# Filter by path
controller path:src/main

# Boolean operators (must be UPPERCASE)
config AND (yaml OR yml)
test NOT unit
UserService AND ext:java AND project:CORE

Configuration

Environment Variable	Required	Description
`BITBUCKET_HOST`	Yes*	Bitbucket DC hostname (e.g. `git.company.com`)
`BITBUCKET_URL`	Yes*	Full base URL alternative (e.g. `https://git.company.com`)
`BITBUCKET_API_TOKEN`	Yes	Personal Access Token

* Provide either BITBUCKET_HOST or BITBUCKET_URL, not both.

Support Matrix

Component	Version(s)	Verification
Bitbucket Data Center	8.19.5	Live smoke tests run locally against a real server
Python runtime	3.10, 3.11, 3.12, 3.13	GitHub Actions CI (`test` workflow matrix)

If you run on a different Bitbucket DC version, please open an issue with results.

Alternative Transports

# SSE transport (for remote/multi-user setups)
uvx mcp-bitbucket-dc --transport sse --host 0.0.0.0 --port 8000

# Streamable HTTP
uvx mcp-bitbucket-dc --transport streamable-http --host 0.0.0.0 --port 8000

By default, HTTP-based transports bind to 127.0.0.1 for safer local development.

Development

# Clone and install
git clone https://github.com/christopherekfeldt/mcp-bitbucket-dc.git
cd mcp-bitbucket-dc
uv sync

# Install git hooks
uv run pre-commit install

# Run locally
export BITBUCKET_HOST=git.yourcompany.com
export BITBUCKET_API_TOKEN=your-token
uv run mcp-bitbucket-dc

# Run tests
uv run pytest

# Run live smoke tests against a real/staging Bitbucket DC
# (requires BITBUCKET_HOST or BITBUCKET_URL + BITBUCKET_API_TOKEN)
RUN_LIVE_SMOKE=1 uv run pytest -m integration -q

Contributor/agent workflow guidance: see AGENTS.md.