README.md
MCP server for Bitbucket Data Center to search code and manage pull requests.
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 |
|---|---|
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) |
bitbucket_create_branch |
Create a new branch from a branch, tag, or commit |
Projects & Repositories
| Tool | Description |
|---|---|
bitbucket_get_projects |
List projects (filterable by name/permission) |
bitbucket_get_project |
Get project details |
bitbucket_search_repositories |
Search repos across all projects (no project key required) |
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_update_pull_request_comment |
Update an existing PR comment |
bitbucket_delete_pull_request_comment |
Delete a PR comment |
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) |
bitbucket_get_commit |
Get full details of a single commit |
bitbucket_get_commit_diff |
Get the diff for a specific commit |
Search Query Syntax
The bitbucket_code_search tool uses Lucene-style queries:
# Simple text search
CompanyInfoUpdater
# Filter
Tools (7)
bitbucket_code_searchSearch code across all repositories using Lucene syntax.bitbucket_browseBrowse directory tree for files and folders at a specific path.bitbucket_get_file_contentRetrieve raw file content with syntax highlighting.bitbucket_list_filesRecursively list all file paths in a repository.bitbucket_get_pull_requestsList pull requests filtered by state, direction, or text.bitbucket_create_pull_requestCreate a new pull request.bitbucket_post_pull_request_commentPost a general or inline comment on a pull request.Environment Variables
BITBUCKET_HOSTrequiredThe URL of your Bitbucket Data Center instance.BITBUCKET_API_TOKENrequiredPersonal access token with repository read/write permissions.Configuration
claude_desktop_config.json
{"mcpServers": {"bitbucket-dc": {"command": "uvx", "args": ["mcp-bitbucket-dc"], "env": {"BITBUCKET_HOST": "git.yourcompany.com", "BITBUCKET_API_TOKEN": "your-personal-access-token"}}}}Try it
→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?