bitbucket-server-mcp
README.md
<div align="center">
[](https://www.npmjs.com/package/@upendra_sengar/bitbucket-server-mcp)
[](https://www.npmjs.com/package/@upendra_sengar/bitbucket-server-mcp)
[](https://www.atlassian.com/software/bitbucket/enterprise)
[](https://www.typescriptlang.org/)
[](https://nodejs.org)
[](LICENSE)
<br>
[](https://github.com/upendrasengar/bitbucket-server-mcp/actions/workflows/ci.yml)
[](https://github.com/upendrasengar/bitbucket-server-mcp/actions/workflows/codeql.yml)
</div>
<div align="center">
<img src="docs/demo.gif" alt="Demo: listing pending PR reviews with Claude Code" width="800">
</div>
## Quickstart
[](https://insiders.vscode.dev/redirect/mcp/install?name=bitbucket-server&inputs=%5B%7B%22id%22%3A%22bitbucket_url%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Bitbucket%20Server%20URL%20%28e.g.%20https%3A//bitbucket.example.com%29%22%7D%2C%7B%22id%22%3A%22bitbucket_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Bitbucket%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40upendra_sengar/bitbucket-server-mcp%22%5D%2C%22env%22%3A%7B%22BITBUCKET_URL%22%3A%22%24%7Binput%3Abitbucket_url%7D%22%2C%22BITBUCKET_TOKEN%22%3A%22%24%7Binput%3Abitbucket_token%7D%22%7D%7D)
[](https://cursor.com/en/install-mcp?name=bitbucket-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB1cGVuZHJhX3Nlbmdhci9iaXRidWNrZXQtc2VydmVyLW1jcCJdLCJlbnYiOnsiQklUQlVDS0VUX1VSTCI6IllPVVJfQklUQlVDS0VUX1VSTCIsIkJJVEJVQ0tFVF9UT0tFTiI6IllPVVJfQklUQlVDS0VUX1RPS0VOIn19)
[](lmstudio://add_mcp?name=bitbucket-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB1cGVuZHJhX3Nlbmdhci9iaXRidWNrZXQtc2VydmVyLW1jcCJdLCJlbnYiOnsiQklUQlVDS0VUX1VSTCI6IllPVVJfQklUQlVDS0VUX1VSTCIsIkJJVEJVQ0tFVF9UT0tFTiI6IllPVVJfQklUQlVDS0VUX1RPS0VOIn19)
Or via Claude Code:
```console
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](https://nodejs.org) >= 22.14 (via `npx`)
- [Bun](https://bun.sh) (via `bunx`)
- [Docker](https://www.docker.com)
## Installation
<details>
<summary><strong>VS Code</strong></summary>
Add to your workspace `.vscode/mcp.json`:
```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](https://cursor.com/en/install-mcp?name=bitbucket-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB1cGVuZHJhX3Nlbmdhci9iaXRidWNrZXQtc2VydmVyLW1jcCJdLCJlbnYiOnsiQklUQlVDS0VUX1VSTCI6IllPVVJfQklUQlVDS0VUX1VSTCIsIkJJVEJVQ0tFVF9UT0tFTiI6IllPVVJfQklUQlVDS0VUX1RPS0VOIn19)) |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| JetBrains | Settings > Tools > AI Assistant > MCP, or `~/.junie/mcp/mcp.json` |
| Neovim | [mcphub.nvim](https://github.com/ravitemer/mcphub.nvim) `mcpservers.json` |
```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):
```json
{
"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:
```json
{
"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](https://bun.sh) 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`). |
| `HTTPS_PROXY` | No | HTTP/HTTPS proxy URL (e.g. `http://proxy.corp.com:8080`). Useful in corporate environments. |
| `NODE_EXTRA_CA_CERTS` | No | Path to a PEM file with additional CA certificates. Use when Bitbucket is behind a self-signed TLS cert. |
*Either `BITBUCKET_TOKEN` or both `BITBUCKET_USERNAME` and `BITBUCKET_PASSWORD` are required.
### Token Permissions
The Personal Access Token needs the following Bitbucket permissions depending on what you intend to do:
| Permission | Required for |
|------------|-------------|
| **Project read** | `list_projects`, `list_repositories`, `browse_repository`, `get_file_content` |
| **Repository read** | All read tools (branches, commits, tags, diff, blame) |
| **Repository write** | `edit_file`, `manage_branches`, `manage_tags`, `create_repository`, `delete_repository` |
| **Pull request read** | `list_pull_requests`, `get_pull_request`, `get_diff`, `get_pull_request_commits` |
| **Pull request write** | `create_pull_request`, `update_pull_request`, `merge_pull_request`, `decline_pull_request`, `manage_comment`, `manage_review` |
For a read-only setup, Project read + Repository read + Pull request read is sufficient.
### 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:
```console
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.
```console
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.
## Bitbucket Cloud
This server targets **Bitbucket Server / Data Center only**. Bitbucket Cloud (bitbucket.org) uses a different REST API and is not supported.
## Usage Examples
### List open PRs assigned to you for review
```
list_dashboard_pull_requests with role=REVIEWER, state=OPEN
```
### Create an inline draft comment on a PR
```
manage_comment with prId=42, filePath="src/auth.ts", line=17, lineType="ADDED",
text="This token is never invalidated — add expiry.", state="PENDING"
```
Then publish all draft comments at once:
```
manage_review with prId=42, action="publish", participantStatus="NEEDS_WORK"
```
### Get a lightweight diff summary without reading every line
```
get_diff with prId=42, stat=true
```
### Enable only the tools you need (reduces context window usage)
```console
BITBUCKET_ENABLED_TOOLS=get_pull_request,get_diff,manage_comment,manage_review
```
## Troubleshooting
**`UNABLE_TO_VERIFY_LEAF_SIGNATURE` or self-signed certificate errors**
Set `NODE_EXTRA_CA_CERTS=/path/to/your-ca-bundle.pem` to point Node.js at your internal CA.
**`403 Forbidden` on write operations**
Your token is missing a write-level permission. See the Token Permissions table above for the exact scope needed.
**Server starts but can't reach Bitbucket**
Enable `BITBUCKET_STARTUP_HEALTHCHECK=true` — it will log a diagnostic line showing which env vars are missing or misconfigured. In corporate environments also set `HTTPS_PROXY`.
**`401 Unauthorized`**
Token auth and basic auth are mutually exclusive. Set either `BITBUCKET_TOKEN` alone, or both `BITBUCKET_USERNAME` + `BITBUCKET_PASSWORD`. Having all three set will cause unpredictable behaviour — remove whichever pair you don't intend to use.
**Tool not found / unexpected behaviour on older Bitbucket versions**
Some tools require Bitbucket 8.5+ (e.g. `list_secret_scanning_rules`). Check the tool description in the [Tools](#tools) section for version requirements. The E2E suite covers 7.21, 8.5, 8.9, 8.19, 9.4, and 10.2.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, architecture overview, and how to add new tools.
## License
Apache 2.0
TDQS
A3.5/5.0
Scored across 59 tools
Disambiguation4/5
Most tools have distinct purposes, but with 59 tools, some overlap may occur (e.g., multiple 'manage' tools for different resources). However, naming and descriptions help differentiate.
Naming Consistency5/5
All tools follow a consistent verb_noun pattern (e.g., list_branches, create_pull_request, manage_webhooks) with no mixing of conventions.
Tool Count2/5
59 tools is excessive for a typical server. While the scope covers many Bitbucket features, many tools are narrow (e.g., manage_gpg_keys, list_ssh_keys) and could be consolidated, leading to a heavy surface.
Completeness4/5
The tool set covers a wide range of Bitbucket Server operations including browsing, commits, PRs, branches, tags, hooks, keys, and more. Minor gaps exist (e.g., no tool for creating projects directly), but overall coverage is strong.
Maintenance
ActivitySlowing
ResponsivenessNo issues