Bitbucket Server Mcp

Quickstart

Install in VS Code Install in Cursor Install in LM Studio

Or via Claude Code:

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

Requirements

• Bitbucket Server / Data Center 8.5+ (may work on 7.x but untested)
• One of:
  • Node.js >= 22.14 (via npx)
  • Bun (via bunx)
  • Docker

Installation

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

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

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

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

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

Tools

Repositories

Pull Requests

Code Review

Branches & Commits

Search & Insights

Prompts

Resources

Configuration

Environment Variables

*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. Write tools (create_pull_request, update_pull_request, merge_pull_request, decline_pull_request, manage_comment, manage_review, manage_branches, manage_tags, upload_attachment, edit_file) 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

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