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 — no Node.js required.

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

Code Search (NEW)

| 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 (NEW)

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

Alternative Transports

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

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

Development

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

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

# Run tests
uv run pytest

License

MIT — see LICENSE.

MCP Servers