Bitbucket MCP Server

MCP server for Bitbucket — built for AI coding agents that need to work with remote repositories as if they were local clones: grep-fast code search, windowed file reads, compact token-efficient responses, and a transport layer that never trips Bitbucket's rate limits.

Supports Bitbucket Server / Data Center (primary target) and Bitbucket Cloud.

Why v3

Measured on a live Data Center instance: a repeated content search went from 519 API calls / ~7s (finding 1 of 8 real matches under burst throttling) to 0 API calls / 24ms finding all 8. Full design and verified API research: `REVAMP_PLAN.md`.

Tools (25)

Search (`search`) — Server/DC only

• `grep` — search file contents with full regex, any branch, like ripgrep on a local clone. One `archive` download per repo+commit, streamed in constant memory, cached in-process, freshness-checked every call (responses carry `as_of `). Omit `query` for filename-only glob listing. Modes: `content`, `files`, `count`; `glob`, `path`, `context`, `case_insensitive`, `max_results`.
• `search_code` — index-backed exact-term search across a whole project in one call (default branch only, case-insensitive, no regex, files ` so the agent knows exactly which state it saw.
• Truncation is never silent — every cap produces an explicit warning with continuation guidance (`next_start`, "narrow the glob", etc.).
• Mutable entities include `version`, so mutations don't need a re-read.

Installation

Using npx (recommended)

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@nexus2520/bitbucket-mcp-server"],
      "env": {
        "BITBUCKET_USERNAME": "your.username",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

For Bitbucket Cloud use `BITBUCKET_APP_PASSWORD` instead of `BITBUCKET_TOKEN` (and omit `BITBUCKET_BASE_URL`).

Credential walkthroughs: Cloud app password · Server/DC HTTP token.

From source

git clone https://github.com/pdogra1299/bitbucket-mcp-server.git
cd bitbucket-mcp-server
npm install && npm run build
# point your MCP config at: node /build/index.js

Configuration

Every numeric policy is environment-tunable — nothing is hard-coded. The full table lives in `src/config/index.ts` (`CONFIG_REFERENCE`). The ones that matter most:

The grep engine's guarantees

• Memory-bounded: the archive is streamed, never buffered whole; the cache is a hard byte budget with LRU eviction and content-hash dedup across branches. Worst case = budget + a few MB transient.
• Fresh: every query re-resolves the branch head; a moved branch can never serve stale results. Merges/deletes made through this server invalidate immediately.
• Complete: cache limits never reduce scan coverage — oversized files are still scanned; only true binaries are skipped, and they're counted in the output.

Rate limiting

All requests flow through a token bucket sized to Bitbucket DC's per-user limiter, so 429s are avoided rather than retried-after. If your instance throttles hard anyway, the error message says exactly what to do — the durable fix is asking a Bitbucket admin for a rate-limit exemption for the service account (Admin → Rate limiting → Exemptions), then setting `BITBUCKET_RATE_LIMIT_RPS=0`.

Migrating from v2

Removed tools and their v3 equivalents (same capabilities, fewer tools):

Update Claude Code permission allowlists (`mcp__bitbucket__*`) accordingly. Diff tools now return unified diff text instead of per-line JSON — line numbers come from `@@` headers. Full details in `CHANGELOG.md`.

Development

npm run build   # tsc → build/
npm test        # build + node --test (unit + snapshot-engine tests)

Architecture: `src/config` (all policy) · `src/core` (transport, snapshot engine, caches) · `src/handlers` (tool logic) · `src/tools` (definitions, guards, registry) · `src/formatting` (compact output) · `src/types` (single barrel).

License

MIT