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](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](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](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