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

1. Log in to your Bitbucket Data Center instance
2. Go to Manage Account → HTTP access tokens
3. Click Create token
4. Set permissions: Repository Read (and Write if you need PR creation/commenting)
5. 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

File Browsing

Projects & Repositories

Pull Requests

Commits

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

* Provide either BITBUCKET_HOST or BITBUCKET_URL, not both.

Disabling SSL verification

For Bitbucket DC instances behind a self-signed certificate or an internal CA that isn't trusted by the system store, set BITBUCKET_VERIFY_SSL=false:

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

⚠️ Disabling SSL verification means traffic is not protected against man-in-the-middle attacks. Only use this against trusted internal networks.

Support 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.

Versioning & Stability

This project follows Semantic Versioning. From v1.0.0 onward, tool names, required parameters, and output contracts are stable — breaking changes only in major version bumps.

Upgrade: uvx mcp-bitbucket-dc always uses the latest. Pin with uvx mcp-bitbucket-dc==X.Y.Z.

Release notes: See GitHub Releases for changelogs.

License

MIT — see LICENSE.