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.
Enables searching code, browsing files, managing pull requests, and exploring repositories and projects within a Bitbucket Data Center instance.
Click on "Install 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-dcSearch 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
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 outputjson: raw structured API response
Code Search
Tool | Description |
| Search code across all repos with Lucene syntax ( |
File Browsing
Tool | Description |
| Browse directory tree (files & folders at a path) |
| Get raw file content with syntax highlighting |
| Recursively list all file paths in a repo |
| List branches (filterable) |
| List tags (filterable) |
Projects & Repositories
Tool | Description |
| List projects (filterable by name/permission) |
| Get project details |
| List repos in a project |
| Get repo details with clone URLs |
Pull Requests
Tool | Description |
| List PRs (filter by state, direction, text) |
| Get PR details with reviewers |
| Get PR comments and activity |
| Get files changed in a PR |
| Get diff for a file in a PR |
| Post a comment (general or inline) |
| Create a new PR |
| Update PR title/description/reviewers |
| Get required reviewers for a branch pair |
Commits
Tool | Description |
| 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:COREConfiguration
Environment Variable | Required | Description |
| Yes* | Bitbucket DC hostname (e.g. |
| Yes* | Full base URL alternative (e.g. |
| 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 ( |
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 8000By 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 -qContributor/agent workflow guidance: see AGENTS.md.
License
MIT — see LICENSE.