bitbucket-server-mcp

<div align="center">

<br>

</div>

<div align="center"> <img src="docs/demo.gif" alt="Demo: listing pending PR reviews with Claude Code" width="800"> </div>

Quickstart

Or via Claude Code:

claude mcp add bitbucket \
  -e BITBUCKET_URL=https://your-bitbucket-server.com \
  -e BITBUCKET_TOKEN=your-token \
  -- npx -y @upendra_sengar/bitbucket-server-mcp

Requirements

• Bitbucket Server / Data Center 7.21+ (the E2E suite covers 7.21, 8.5, 8.9, 8.19, 9.4 and 10.2).
• One of:
  • Node.js >= 22.14 (via npx)
  • Bun (via bunx)
  • Docker

Installation

<details> <summary><strong>VS Code</strong></summary>

Add to your workspace .vscode/mcp.json:

{
  "servers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@upendra_sengar/bitbucket-server-mcp"],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        "BITBUCKET_TOKEN": "your-access-token"
      }
    }
  }
}

</details>

<details> <summary><strong>Claude Desktop, Cursor, Windsurf, JetBrains, Neovim</strong></summary>

These clients all use the same mcpServers format. Add the JSON below to the config file for your client:

Client	Config file
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
Cursor	~/.cursor/mcp.json (one-click install)
Windsurf	~/.codeium/windsurf/mcp_config.json
JetBrains	Settings > Tools > AI Assistant > MCP, or ~/.junie/mcp/mcp.json
Neovim	mcphub.nvim mcpservers.json

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@upendra_sengar/bitbucket-server-mcp"],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        "BITBUCKET_TOKEN": "your-access-token"
      }
    }
  }
}

</details>

<details> <summary><strong>Zed</strong></summary>

Add to your Zed settings (~/.config/zed/settings.json on Linux, ~/Library/Application Support/Zed/settings.json on macOS):

{
  "context_servers": {
    "bitbucket": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@upendra_sengar/bitbucket-server-mcp"],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        "BITBUCKET_TOKEN": "your-access-token"
      }
    }
  }
}

</details>

<details> <summary><strong>Docker</strong></summary>

For environments without Node.js:

{
  "mcpServers": {
    "bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BITBUCKET_URL=https://your-bitbucket-server.com",
        "-e", "BITBUCKET_TOKEN=your-access-token",
        "ghcr.io/upendrasengar/bitbucket-server-mcp"
      ]
    }
  }
}

Or build locally: docker build -t bitbucket-mcp .

</details>

[!TIP] Bun users can replace npx -y with bunx in any of the configs above.

Tools

Repositories

Tool	Description
list_projects	List all accessible Bitbucket projects
list_repositories	List repositories in a project
browse_repository	Browse files and directories
get_file_content	Read file contents with pagination
upload_attachment	Upload a local file and get a markdown reference for PR comments
edit_file	Edit a file by committing a new version via the REST API
get_server_info	Get Bitbucket Server version and properties
get_file_blame	Get line-by-line blame/history for a file
create_repository	Create a new repository
delete_repository	Delete a repository (irreversible)

Pull Requests

Tool	Description
create_pull_request	Create a PR, including cross-repo from forks (sourceProject/sourceRepository) and drafts (draft: true). Auto-fetches default reviewers unless includeDefaultReviewers: false.
get_pull_request	Get PR details
update_pull_request	Safely update title, description, or reviewers (read-modify-write, preserves fields not explicitly changed)
merge_pull_request	Merge a PR with optional strategy (no-ff, ff, ff-only, squash, rebase-no-ff, rebase-ff-only, squash-ff-only)
decline_pull_request	Decline a PR
list_pull_requests	List PRs with filtering by state, author, direction
list_dashboard_pull_requests	List PRs across all repos for the authenticated user, filtered by role (AUTHOR/REVIEWER/PARTICIPANT), state, and review status
get_pull_request_activity	Get PR activity timeline, filtered by type (all, reviews, comments)
get_diff	Get PR diff with per-file truncation support. Use stat: true for a lightweight summary of changed files instead of the full diff.
get_pull_request_commits	List commits in a pull request
get_commit_pull_requests	List pull requests containing a specific commit

Code Review

Tool	Description
manage_comment	Unified create/edit/delete for PR comments. Supports inline anchoring (filePath/line/lineType), draft state (state: PENDING), task creation (severity: BLOCKER), threaded replies (parentId), and resolve/unresolve (state: RESOLVED/OPEN).
manage_review	Unified approve/unapprove/publish. Publish transitions all PENDING comments to visible and optionally sets participantStatus (APPROVED/NEEDS_WORK).

Branches & Commits

Tool	Description
list_branches	List branches with default branch detection
list_commits	Browse commit history with branch and author filtering
manage_branches	Create or delete branches (safety check prevents deleting default branch)
get_commit	Get details of a specific commit by its ID
compare_refs	List commits reachable from one ref but not another
list_tags	List tags in a repository
manage_tags	Create or delete tags
get_tag	Get details of a specific tag by its name

Search & Insights

Tool	Description
search	Search code and files across repositories
get_code_insights	Fetch Code Insights reports (SonarQube, security scans) and annotations
get_build_status	Get CI build status (state, name, URL) by commit ID or PR. When using prId, resolves the latest commit automatically.

Forks

Tool	Description
list_forks	List forks of a repository
fork_repository	Fork a repository into a target project

Users

Tool	Description
get_user_profile	Get a user profile by slug
search_users	Search users by filter query

Labels

Tool	Description
list_labels	List labels for a repository
manage_labels	Add or remove repository labels

Webhooks

Tool	Description
list_webhooks	List webhooks for a repository
manage_webhooks	Create, update, or delete webhooks

Commit Comments

Tool	Description
list_commit_comments	List comments on a specific commit
manage_commit_comments	Create, edit, or delete comments on a commit

Repository Settings

Tool	Description
list_default_reviewer_conditions	List default reviewer conditions
list_branch_restrictions	List branch permission restrictions
list_repository_hooks	List repository hooks and their status
manage_repository_hooks	Enable, disable, or configure repository hooks
list_merge_checks	List merge check configurations
manage_merge_checks	Configure merge check settings
list_reviewer_groups	List reviewer groups
manage_reviewer_groups	Create or delete reviewer groups
list_secret_scanning_rules	List secret scanning allowlist rules (8.5+)

Keys

Tool	Description
list_ssh_keys	List SSH keys for the authenticated user
manage_ssh_keys	Add or delete SSH keys
list_gpg_keys	List GPG keys for the authenticated user
manage_gpg_keys	Add or delete GPG keys

Prompts

Prompt	Description
review-pr	Step-by-step workflow for reviewing a PR: fetch details, read diff, check CI, create draft comments, and publish the review. Invoke via /bitbucket:review-pr in Claude Code. No arguments needed; the LLM asks for the PR interactively. You can add context, e.g. /bitbucket:review-pr PR #42 in my-repo.

Resources

Resource	URI	Description
projects	bitbucket://projects	Cached list of all accessible projects (5 min TTL). Useful as ambient context without explicit tool calls.

Configuration

Environment Variables

Variable	Required	Description
BITBUCKET_URL	Yes	Base URL of your Bitbucket Server instance
BITBUCKET_TOKEN	Yes*	Personal access token
BITBUCKET_USERNAME	Yes*	Username for basic auth
BITBUCKET_PASSWORD	Yes*	Password for basic auth
BITBUCKET_DEFAULT_PROJECT	No	Default project key when not specified in tool calls
BITBUCKET_READ_ONLY	No	Set to true to disable all write operations
BITBUCKET_CUSTOM_HEADERS	No	Extra headers for all requests (Key=Value,Key2=Value2). Useful for Zero Trust tokens.
BITBUCKET_DIFF_MAX_LINES_PER_FILE	No	Max lines per file in diffs. Set to 0 for no limit.
BITBUCKET_CACHE_TTL	No	Cache duration in seconds (default: 300). Set to 0 to disable caching.
BITBUCKET_ENABLED_TOOLS	No	Comma-separated list of tool names to enable. If not set, all tools are available.
BITBUCKET_STARTUP_HEALTHCHECK	No	Set to true to run a connectivity check against Bitbucket on startup (default: false).

*Either BITBUCKET_TOKEN or both BITBUCKET_USERNAME and BITBUCKET_PASSWORD are required.

Read-Only Mode

Set BITBUCKET_READ_ONLY=true to restrict the server to read-only operations. All create_*, update_*, delete_*, manage_*, merge_*, decline_*, fork_*, upload_*, and edit_* tools are disabled.

Tool Filtering

Set BITBUCKET_ENABLED_TOOLS to load only specific tools, reducing context window usage:

BITBUCKET_ENABLED_TOOLS=get_pull_request,get_diff,manage_comment,manage_review

Startup Healthcheck

When BITBUCKET_STARTUP_HEALTHCHECK=true, the server probes /rest/api/1.0/application-properties on startup and logs whether Bitbucket is reachable. If not, it logs a diagnostic line referencing the relevant env vars (BITBUCKET_URL, BITBUCKET_TOKEN, HTTPS_PROXY, NODE_EXTRA_CA_CERTS) without blocking the server. Useful for debugging connectivity issues before the first tool call fails with a generic error.

BITBUCKET_STARTUP_HEALTHCHECK=true

Response Curation

Read tools return compact responses by default, keeping only the fields an AI assistant typically needs. Every read tool accepts a fields parameter to customize:

• Omit fields: returns a curated summary (e.g. PR id, title, state, author, branches, reviewers, task count)
• fields: "*all": returns the complete raw Bitbucket API response
• fields: "id,title,author.user.name": returns exactly those fields (dot notation for nested paths)

Caching

The server caches frequently accessed data in memory (project lists, repository metadata, default reviewers) to reduce API calls. The cache uses LRU eviction (max 500 entries) so memory stays bounded, and write operations automatically invalidate related entries.

By default, cached entries expire after 5 minutes. Configure with BITBUCKET_CACHE_TTL (in seconds), or set to 0 to disable caching entirely.

Contributing

See CONTRIBUTING.md for development setup, architecture overview, and how to add new tools.

License

Apache 2.0