Bitbucket

Servidor MCP Bitbucket

Servidor MCP para Bitbucket — construído para agentes de codificação de IA que precisam trabalhar com repositórios remotos como se fossem clones locais: busca de código rápida como grep, leituras de arquivo em janelas, respostas compactas e eficientes em tokens, e uma camada de transporte que nunca esbarra nos limites de taxa do Bitbucket.

Suporta Bitbucket Server / Data Center (alvo principal) e Bitbucket Cloud.

Por que v3

	v2	v3
Busca de conteúdo em um repositório	1 listagem + até 3.000 GETs de arquivos	1 chamada de archive a frio, 0–1 chamada aquecido
Completude da busca	parcialmente silenciosa sob throttling do servidor	completa, com cada limite reportado
Tokens de diff de PR	JSON por linha (~4× maior)	diff unificado bruto
Ler uma janela de 100 linhas	2 chamadas, arquivo inteiro transferido	1 chamada, apenas a janela
Blame de uma janela de um arquivo enorme	até 100 chamadas	1 chamada
Segurança contra limite de taxa	nenhuma (rajada → 429/403)	pacing no lado do cliente dimensionado para o limitador do DC
Ferramentas	33	25 (~30% menos contexto de definição)

Medido em uma instância Data Center ativa: uma busca de conteúdo repetida passou de 519 chamadas de API / ~7s (encontrando 1 de 8 correspondências reais sob throttling de rajada) para 0 chamadas de API / 24ms encontrando todas as 8. Design completo e pesquisa de API verificada: REVAMP_PLAN.md.

Ferramentas (25)

Busca (search) — apenas Server/DC

• grep — busca o conteúdo de arquivos com regex completa, em qualquer branch, como ripgrep em um clone local. Um download de archive por repositório+commit, transmitido em memória constante, cache em processo, verificação de frescor a cada chamada (as respostas carregam as_of <commit>). Omita query para listagem de glob apenas com nomes de arquivos. Modos: content, files, count; glob, path, context, case_insensitive, max_results.
• search_code — busca por termo exato com índice em um projeto inteiro em uma única chamada (apenas branch padrão, sem diferenciar maiúsculas/minúsculas, sem regex, arquivos <512 KiB, janela de ~1000 resultados). Melhor para buscas de identificadores entre repositórios; use grep para todo o resto.
• search_repositories — encontra repositórios por nome/descrição.

Pull requests (pr_core)

• get_pull_request — metadados + status do revisor + informações de merge em 1 chamada; include_comments / include_file_changes (padrão true), include_tasks, comment_limit. Retorna version para mutações de acompanhamento.
• list_pull_requests — escopo por repositório; omita repository (Server) para seus PRs em todos os repositórios em uma única chamada (filtro role).
• create_pull_request, update_pull_request, merge_pull_request, decline_pull_request — todas as mutações aceitam version de uma leitura anterior (economiza um fetch; re-busca automática + nova tentativa uma vez em conflitos 409).

Comentários e tarefas (pr_comments)

• add_comment — geral, resposta em thread, inline (file_path + line_number, ou resolução automática code_snippet), código suggestion, ou tarefa (severity: "BLOCKER", Server). Anexos são enviados via parâmetro attachments (Server).
• manage_comment — edit / delete / resolve / reopen / to_task / to_comment em qualquer comentário ou tarefa, uma chamada com version.

Revisão (pr_review)

• get_pull_request_diff — texto bruto de diff unificado; escopo com file_path (no servidor), include_patterns/exclude_patterns, context_lines, ignore_whitespace.
• set_review_status — APPROVED / NEEDS_WORK / UNAPPROVED (mutuamente exclusivos; uma chamada).

Commits (commits)

• list_pr_commits, list_branch_commits (filtros since-rev/merges no servidor; caminhada de páginas limitada para author/until/search no cliente), get_commit_detail (diff unificado, ou detail: "files" para a lista de arquivos alterados sem os corpos).

Branches (branches)

• list_branches, get_branch (branch + seus PRs), delete_branch (expected_head pula a chamada de lookup).

Arquivos (files)

• get_file_content — em janelas no servidor: start_line/line_count transferem apenas essa janela (≤5000 linhas/chamada). full_content / start_line negativo para leituras de arquivo inteiro ou do final.
• get_file_blame — blame por intervalo de commits para uma janela de linhas em 1 chamada (Server).
• list_directory_content — paginado, compacto.

Anexos (attachments, Server) / Descoberta (discovery)

• manage_attachments (limitado por download, delete), list_projects, list_repositories.

Convenções de saída

• Conteúdo em massa (diffs, arquivos, resultados de grep) é texto puro, não strings escapadas em JSON; listas são JSON compacto sem pretty-printing. Datas no formato ISO-8601.
• Respostas derivadas de conteúdo carregam as_of <commit> para que o agente saiba exatamente qual estado viu.
• Truncamento nunca é silencioso — todo limite produz um aviso explícito com orientação de continuação (next_start, "estreite o glob", etc.).
• Entidades mutáveis incluem version, então mutações não precisam de nova leitura.

Instalação

Usando npx (recomendado)

{
  "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"
      }
    }
  }
}

Para Bitbucket Cloud use BITBUCKET_APP_PASSWORD em vez de BITBUCKET_TOKEN (e omita BITBUCKET_BASE_URL).

Passo a passo de credenciais: Senha de aplicativo Cloud · Token HTTP Server/DC.

A partir do código-fonte

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 <repo>/build/index.js

Configuração

Toda política numérica é ajustável por variável de ambiente — nada é hard-coded. A tabela completa está em src/config/index.ts (CONFIG_REFERENCE). As mais importantes:

Variável	Padrão	Finalidade
BITBUCKET_RATE_LIMIT_RPS	5	Taxa sustentada de requisições no cliente (o refill por usuário do DC é 5/s). 0 desativa o pacing — defina isto se sua conta tiver isenção de limite de taxa de administrador
BITBUCKET_RATE_LIMIT_BURST	50	Capacidade de rajada (o bucket do servidor do DC é 60)
BITBUCKET_GLOBAL_MAX_CONCURRENCY	8	Máximo de requisições em voo em todas as ferramentas
BITBUCKET_SNAPSHOT_MAX_MB	256	Orçamento do cache de grep em memória. 0 = streaming puro (sem retenção, ainda 2 chamadas por busca)
BITBUCKET_SNAPSHOT_MAX_FILE_KB	2048	Arquivos maiores que isto são escaneados mas não armazenados em cache
BITBUCKET_REF_RESOLVE_TTL_MS	15000	Memo de frescor Branch→SHA; 0 = validar em cada chamada individual
BITBUCKET_STREAM_ABORT_MB	2048	Aborta varreduras de archive após este número de MB extraídos (recai em varredura de arquivo por arquivo limitada)
BITBUCKET_HTTP_TIMEOUT_MS	30000	Timeout por requisição
BITBUCKET_TOOL_GROUPS	all	Grupos separados por vírgula a expor (validados, aplicados no dispatch, fecham com falha)

As garantias do mecanismo de grep

• Limitado em memória: o archive é transmitido em streaming, nunca armazenado inteiro em buffer; o cache é um orçamento de bytes rígido com evicção LRU e deduplicação por hash de conteúdo entre branches. Pior caso = orçamento + alguns MB transitórios.
• Fresco: cada consulta re-resolve o head do branch; um branch movido nunca pode servir resultados obsoletos. Merges/deletes feitos através deste servidor invalidam imediatamente.
• Completo: limites de cache nunca reduzem a cobertura da varredura — arquivos superdimensionados ainda são escaneados; apenas binários verdadeiros são pulados, e eles são contabilizados na saída.

Limite de taxa

Todas as requisições passam por um token bucket dimensionado para o limitador por usuário do Bitbucket DC, então 429s são evitados em vez de tentados novamente depois. Se sua instância limitar fortemente mesmo assim, a mensagem de erro diz exatamente o que fazer — a correção duradoura é pedir a um administrador do Bitbucket uma isenção de limite de taxa para a conta de serviço (Admin → Rate limiting → Exemptions), e então definir BITBUCKET_RATE_LIMIT_RPS=0.

Migrando do v2

Ferramentas removidas e seus equivalentes no v3 (mesmas capacidades, menos ferramentas):

v2	v3
find_in_files	grep com query
search_files	grep sem query (use glob)
list_pr_tasks	get_pull_request + include_tasks: true
create_pr_task	add_comment + severity: "BLOCKER"
update_pr_task	manage_comment action: "edit"
delete_pr_task, delete_comment	manage_comment action: "delete"
set_pr_task_status	manage_comment action: "resolve" / "reopen"
convert_pr_item	manage_comment action: "to_task" / "to_comment"
set_pr_approval	set_review_status status: "APPROVED" / "UNAPPROVED"

Atualize as allowlists de permissão do Claude Code (mcp__bitbucket__*) de acordo. As ferramentas de diff agora retornam texto de diff unificado em vez de JSON por linha — os números de linha vêm dos cabeçalhos @@. Detalhes completos em CHANGELOG.md.

Desenvolvimento

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

Arquitetura: src/config (toda a política) · src/core (transporte, mecanismo de snapshot, caches) · src/handlers (lógica das ferramentas) · src/tools (definições, guards, registry) · src/formatting (saída compacta) · src/types (barrel único).

Licença

MIT