Personal Bitbucket MCP Server

Servidor MCP Bitbucket construído sobre o framework Quarkus

Documentação

Personal Bitbucket MCP Server

Um servidor Model Context Protocol (MCP) que fornece aos assistentes de IA ferramentas para interagir com repositórios do Bitbucket Cloud. Construído com Quarkus, o Supersonic Subatomic Java Framework.

Autor: Tedy Saputro | Contato: tedy@saputro.dev

O que é MCP?

O Model Context Protocol (MCP) é um protocolo aberto que padroniza como aplicações fornecem contexto a Modelos de Linguagem de Grande Porte (LLMs). Este servidor implementa MCP para expor operações do Bitbucket como ferramentas que assistentes de IA como Claude, ChatGPT ou outras aplicações baseadas em LLM podem usar.

Recursos

🔧 11 Ferramentas MCP para operações do Bitbucket
🚀 Suporte a Imagem Nativa com GraalVM para inicialização rápida e baixo consumo de memória
🐳 Imagens Docker Multi-Arquitetura (AMD64 & ARM64)
🔐 Autenticação Segura usando Senhas de Aplicativo do Bitbucket
📦 API RESTful para acesso HTTP direto
⚡ Múltiplas Opções de Transporte - stdio (universal), SSE e HTTP Stream
🎯 Suporte Universal a Clientes - stdio funciona com todos os clientes MCP (Claude Desktop, Cursor, VS Code, Cherry Studio e mais)

Se você quiser saber mais sobre Quarkus, visite seu site: https://quarkus.io/.

Início Rápido

Pré-requisitos

Token de API do Bitbucket: Crie um token de API em https://bitbucket.org/account/settings/api-token/
- Permissões necessárias: repository:read, pullrequest:read, pullrequest:write
- Veja Criando um Token de API do Bitbucket para instruções detalhadas
Docker (opcional): Para executar a versão containerizada

Usando Docker (Recomendado)

docker run -p 8080:8080 \
  -e BITBUCKET_EMAIL=your-email@example.com \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  subrutin/bitbucket-mcp-server:latest

Usando MCP com Clientes Suportados

Este servidor suporta múltiplos protocolos de transporte. Escolha o método que funciona melhor para o seu cliente:

🎯 Método 1: Transporte stdio (Recomendado - Funciona com Todos os Clientes)

O transporte stdio permite comunicação direta entre processos sem precisar de um servidor HTTP em execução. Este é o método universal que funciona com todos os clientes MCP.

Para Claude Desktop, adicione isto ao seu arquivo de configuração:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bitbucket": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "BITBUCKET_EMAIL=your-email@example.com",
        "-e", "BITBUCKET_API_TOKEN=your-api-token",
        "-e", "BITBUCKET_WORKSPACE=your-workspace",
        "subrutin/bitbucket-mcp-server:stdio-0.0.2"
      ]
    }
  }
}

Reinicie o Claude Desktop e você verá as ferramentas do Bitbucket disponíveis no menu de ferramentas 🔨.

Para Cursor IDE, adicione às configurações do Cursor (mesmo formato do Claude Desktop):

{
  "mcpServers": {
    "bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BITBUCKET_EMAIL=your-email@example.com",
        "-e", "BITBUCKET_API_TOKEN=your-api-token",
        "-e", "BITBUCKET_WORKSPACE=your-workspace",
        "subrutin/bitbucket-mcp-server:stdio-0.0.2"
      ]
    }
  }
}

Para VS Code com extensão MCP (mesmo formato):

{
  "mcp.servers": {
    "bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BITBUCKET_EMAIL=your-email@example.com",
        "-e", "BITBUCKET_API_TOKEN=your-api-token",
        "-e", "BITBUCKET_WORKSPACE=your-workspace",
        "subrutin/bitbucket-mcp-server:stdio-0.0.2"
      ]
    }
  }
}

Para outros clientes MCP, use o mesmo padrão de comando Docker com transporte stdio.

🌐 Método 2: Transporte SSE (Alternativa para Clientes Baseados na Web)

O transporte SSE requer que o servidor esteja em execução e acessível via HTTP.

Passo 1: Inicie o servidor usando Docker:

docker run -d \
  --name bitbucket-mcp \
  -p 8080:8080 \
  -e BITBUCKET_EMAIL=your-email@example.com \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  subrutin/bitbucket-mcp-server:latest

Passo 2: Configure seu cliente MCP:

✅ Cursor IDE

Adicione às configurações do Cursor:

{
  "mcpServers": {
    "bitbucket": {
      "url": "http://localhost:8080/mcp/sse"
    }
  }
}

✅ VS Code

Instale a extensão MCP e adicione às suas configurações:

{
  "mcp.servers": {
    "bitbucket": {
      "url": "http://localhost:8080/mcp/sse"
    }
  }
}

✅ Cherry Studio

Vá para Configurações
Selecione MCP
Clique no botão Criar

  "Type": sse
  "url": "http://localhost:8080/mcp/sse",
  "name": "Bitbucket MCP"

Transportes Suportados

✅ stdio - Comunicação direta entre processos (Universal - Recomendado)
- Funciona com: TODOS os clientes MCP (Claude Desktop, Cursor, VS Code, Cherry Studio, etc.)
- Não precisa de servidor HTTP
- Configuração mais simples
- Use a imagem: subrutin/bitbucket-mcp-server:stdio-0.0.2
✅ SSE (Server-Sent Events) - Transporte baseado em HTTP
- Opção alternativa para clientes baseados na web
- Requer servidor HTTP em execução
- Conexões de longa duração
- Atualizações em tempo real
- Use a imagem: subrutin/bitbucket-mcp-server:latest
✅ HTTP Stream - Para clientes MCP personalizados
- Padrões de requisição/resposta
- Acesso programático
- Use a imagem: subrutin/bitbucket-mcp-server:latest
⚠️ HTTPS/TLS - Ainda não suportado
- Atualmente apenas HTTP disponível para SSE
- Suporte a HTTPS planejado para versão futura

Referência de Ferramentas MCP

Este servidor fornece 11 ferramentas para interagir com o Bitbucket:

Ferramentas de Pull Request

1. `findAllPullRequest`

Retorna todos os pull requests no repositório especificado.

Parâmetros:

workspace (string): O ID ou slug do workspace onde o repositório está localizado
reposlug (string): O slug ou nome do repositório do qual obter pull requests

Exemplo:

Use the findAllPullRequest tool with workspace "myteam" and reposlug "myrepo"

2. `findAPullRequest`

Retorna um pull request específico por ID com informações detalhadas.

Parâmetros:

workspace (string): O ID ou slug do workspace
reposlug (string): O slug do repositório
pullRequestId (inteiro): O ID do pull request para obter detalhes

Exemplo:

Get details of pull request #42 from myteam/myrepo

3. `findDiffStatForPullRequest`

Retorna o diffstat (estatísticas sobre alterações) de um pull request.

Parâmetros:

workspace (string): O ID ou slug do workspace
reposlug (string): O slug do repositório
id (inteiro): O ID do pull request

Exemplo:

Show me the diffstat for PR #42

4. `findListChangesInAPullRequest`

Retorna o diff/alterações reais em um pull request, mostrando linhas adicionadas/removidas.

Parâmetros:

workspace (string): O ID ou slug do workspace
reposlug (string): O slug do repositório
id (inteiro): O ID do pull request

Exemplo:

Show me all the code changes in PR #42

Ferramentas de Comentário em Pull Request

5. `createComment`

Cria um comentário geral em um pull request.

Parâmetros:

workspace (string): O ID ou slug do workspace
reposlug (string): O slug do repositório
pullRequestId (inteiro): O ID do pull request para comentar
commentText (string): O texto do comentário (suporta Markdown)

Exemplo:

Add a comment to PR #42 saying "LGTM! Great work on the refactoring."

6. `updateComment`

Atualiza um comentário existente em um pull request.

Parâmetros:

workspace (string): O ID ou slug do workspace
reposlug (string): O slug do repositório
pullRequestId (inteiro): O ID do pull request
commentId (inteiro): O ID do comentário a ser atualizado
commentText (string): O texto atualizado do comentário

Exemplo:

Update comment #123 on PR #42 with new text

7. `createInlineComment`

Cria um comentário inline em uma linha específica de código no diff de um pull request.

Parâmetros:

workspace (string): O ID ou slug do workspace
reposlug (string): O slug do repositório
pullRequestId (inteiro): O ID do pull request
filePath (string): O caminho EXATO do arquivo conforme mostrado no diff do PR (sensível a maiúsculas/minúsculas)
lineNumber (inteiro): O número da linha na versão NOVA do arquivo
commentText (string): O texto do comentário em formato Markdown

Notas Importantes:

O filePath deve corresponder EXATAMENTE ao caminho do arquivo mostrado no diff do PR
O lineNumber deve ser da versão NOVA/MODIFICADA (linhas com '+' no diff)
A linha deve existir no diff do PR - você não pode comentar em linhas inalteradas
Fluxo de Trabalho: Primeiro chame findListChangesInAPullRequest para obter o diff, depois identifique o caminho correto do arquivo e o número da linha

Exemplo:

First, get the diff for PR #42, then add an inline comment on line 25 of src/main/java/Service.java

8. `findAComment`

Retorna um comentário específico de pull request com seus detalhes.

Parâmetros:

workspace (string): O ID ou slug do workspace
reposlug (string): O slug do repositório
pullRequestId (inteiro): O ID do pull request
commentId (inteiro): O ID do comentário a ser recuperado

Exemplo:

Get details of comment #123 from PR #42

9. `findCommentList`

Retorna uma lista paginada de comentários para um pull request específico.

Parâmetros:

workspace (string): O ID ou slug do workspace
reposlug (string): O slug do repositório
pullRequestId (inteiro): O ID do pull request
page (inteiro): O número da página para paginação
pageLength (inteiro): O número de itens por página
size (inteiro): O número total de itens

Exemplo:

Get the first 10 comments from PR #42

Ferramentas de Perfil de Usuário

10. `Fetch user profile`

Retorna as informações de perfil do usuário autenticado no Bitbucket.

Parâmetros: Nenhum

Exemplo:

Show me my Bitbucket profile

Configuração

Variáveis de Ambiente

Este servidor requer as seguintes variáveis de ambiente para autenticação com o Bitbucket Cloud:

Variável	Obrigatória	Descrição	Exemplo
`BITBUCKET_EMAIL`	Sim	O e-mail da sua conta Bitbucket	`user@example.com`
`BITBUCKET_API_TOKEN`	Sim	Token de API com permissões de repositório e PR	`ATBBxxx...`
`BITBUCKET_WORKSPACE`	Sim	Slug padrão do workspace para operações	`myteam`

Criando um Token de API do Bitbucket

Vá para https://bitbucket.org/account/settings/api-token/
Clique em "Criar token de API"
Dê um rótulo (ex.: "MCP Server")
Selecione as permissões:
- Repositórios: Leitura
- Pull requests: Leitura, Escrita
Clique em "Criar" e copie o token gerado (use-o como BITBUCKET_API_TOKEN)

Nota: Tokens de API são diferentes de senhas de aplicativo. Tokens de API fornecem permissões mais granulares e são o método de autenticação recomendado. Para mais informações, veja a documentação de Token de API da Atlassian.

Configuração da Aplicação

A configuração do servidor está em src/main/resources/application.yml:

bitbucket:
  api:
    email: ${BITBUCKET_EMAIL:}
    token: ${BITBUCKET_API_TOKEN:}
    workspace: ${BITBUCKET_WORKSPACE:}

quarkus:
  rest-client:
    bitbucket-api:
      url: https://api.bitbucket.org/2.0

Transportes Suportados

Este servidor MCP suporta os seguintes protocolos de transporte:

✅ stdio - Comunicação direta entre processos (Universal - Recomendado)
- Funciona com: TODOS os clientes MCP (Claude Desktop, Cursor, VS Code, Cherry Studio e mais)
- Não precisa de servidor HTTP
- Configuração e integração mais simples
- Imagem Docker: subrutin/bitbucket-mcp-server:stdio-0.0.2
✅ SSE (Server-Sent Events) - GET /mcp/sse
- Alternativa para clientes baseados na web
- Requer servidor HTTP em execução
- Conexões de longa duração
- Atualizações em tempo real
- Atualmente apenas HTTP (HTTPS em breve)
- Imagem Docker: subrutin/bitbucket-mcp-server:latest
✅ HTTP Stream - POST /mcp/stream
- Para clientes MCP personalizados
- Padrões de requisição/resposta
- Acesso programático
- Imagem Docker: subrutin/bitbucket-mcp-server:latest
⚠️ HTTPS/TLS - Ainda não suportado (em desenvolvimento)
- Permitirá conexões SSE seguras
- Configuração de certificado SSL necessária
- Veja o Roteiro para o cronograma

Executando com Docker

Imagens Docker Disponíveis

Este projeto fornece duas imagens Docker para diferentes casos de uso:

subrutin/bitbucket-mcp-server:latest - Transporte SSE/HTTP
- Para Cursor, VS Code, Cherry Studio
- Requer servidor HTTP em execução
- Suporta SSE e HTTP Stream
subrutin/bitbucket-mcp-server:stdio-0.0.2 - Transporte stdio (Recomendado)
- Para TODOS os clientes MCP (Claude Desktop, Cursor, VS Code, Cherry Studio, etc.)
- Comunicação direta entre processos
- Não precisa de servidor HTTP
- Configuração mais simples

Baixar e Executar (Transporte SSE/HTTP)

# Pull the latest image
docker pull subrutin/bitbucket-mcp-server:latest

# Run the container
docker run -d \
  --name bitbucket-mcp \
  -p 8080:8080 \
  -e BITBUCKET_EMAIL=your-email@example.com \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  subrutin/bitbucket-mcp-server:latest

Executar com Transporte stdio (Todos os Clientes MCP - Recomendado)

# Pull the stdio image
docker pull subrutin/bitbucket-mcp-server:stdio-0.0.2

# Run interactively (for testing)
docker run -i --rm \
  -e BITBUCKET_EMAIL=your-email@example.com \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  subrutin/bitbucket-mcp-server:stdio-0.0.2

Nota: Para clientes MCP (Claude Desktop, Cursor, VS Code, etc.), use a configuração mostrada em Método 1: Transporte stdio em vez de executar manualmente.

Usando Docker Compose

Crie um docker-compose.yml:

version: '3.8'

services:
  bitbucket-mcp:
    image: subrutin/bitbucket-mcp-server:latest
    ports:
      - "8080:8080"
    environment:
      BITBUCKET_EMAIL: ${BITBUCKET_EMAIL}
      BITBUCKET_API_TOKEN: ${BITBUCKET_API_TOKEN}
      BITBUCKET_WORKSPACE: ${BITBUCKET_WORKSPACE}
    restart: unless-stopped

Depois execute:

docker-compose up -d

Verificação de Saúde

Verifique se o servidor está em execução:

curl http://localhost:8080/q/health

Desenvolvimento

Executando em Modo de Desenvolvimento

Execute a aplicação em modo de desenvolvimento com codificação ao vivo habilitada:

./mvnw quarkus:dev

A interface de desenvolvimento (Dev UI) está disponível em http://localhost:8080/q/dev/

Testando Ferramentas MCP Localmente

Depois que o servidor estiver em execução, você pode testar os endpoints MCP:

# Test SSE connection (Server-Sent Events)
curl -N http://localhost:8080/mcp/sse

# Test HTTP Stream connection
curl -N http://localhost:8080/mcp

# Test with MCP Inspector (if installed)
npx @modelcontextprotocol/inspector http://localhost:8080/mcp/sse

Transportes MCP Disponíveis:

stdio - Comunicação direta entre processos (Universal - funciona com TODOS os clientes MCP - use a imagem stdio-0.0.2) ⭐ Recomendado
GET /mcp/sse - Transporte SSE (Alternativa - requer servidor HTTP)
POST /mcp/stream - Transporte HTTP Stream (para clientes MCP personalizados)

Compilação

Compilando Imagens Docker Multi-Arquitetura

Este projeto inclui um script para construir imagens Docker nativas para arquiteturas AMD64 e ARM64:

# Build and push multi-platform image
./build-multiplatform.sh subrutin/bitbucket-mcp-server 0.0.1

# The script will:
# 1. Use Docker buildx to create multi-arch images
# 2. Build native executables with GraalVM
# 3. Push to Docker Hub registry

Construindo a Versão JVM

Empacote a aplicação como uma aplicação JVM:

./mvnw package

Isso produz quarkus-run.jar no diretório target/quarkus-app/.

Execute com:

java -jar target/quarkus-app/quarkus-run.jar

Construindo o Executável Nativo

Construa um executável nativo com GraalVM:

# With local GraalVM installation
./mvnw package -Dnative

# Or using Docker (no GraalVM installation required)
./mvnw package -Dnative -Dquarkus.native.container-build=true

Execute o executável nativo:

./target/bitbucket-mcp-server-1.0.0-SNAPSHOT-runner

Benefícios da Native Image:

⚡ Tempo de inicialização rápido (~0,01s vs ~1-2s para JVM)
💾 Baixo consumo de memória (~20-30MB vs ~100-200MB para JVM)
📦 Tamanho de imagem pequeno (~50-100MB vs ~300-400MB para JVM)

Construindo a Imagem Docker Manualmente

# Build native image
docker build -f src/main/docker/Dockerfile.multiplatform -t bitbucket-mcp-server:native .

# Build JVM image
docker build -f src/main/docker/Dockerfile.jvm -t bitbucket-mcp-server:jvm .

Documentação da API

Endpoints MCP

O servidor MCP oferece três opções de transporte:

1. stdio - Comunicação Direta por Processo ✨ Novo! (Universal - Recomendado)

# Use with Docker
docker run -i --rm \
  -e BITBUCKET_EMAIL=your-email@example.com \
  -e BITBUCKET_API_TOKEN=your-api-token \
  -e BITBUCKET_WORKSPACE=your-workspace \
  subrutin/bitbucket-mcp-server:stdio-0.0.2

Ideal para:

TODOS os clientes MCP (Claude Desktop, Cursor, VS Code, Cherry Studio, etc.)
Nenhum servidor HTTP necessário
Comunicação direta por processo
Configuração mais simples
Recomendado para todos os casos de uso

2. SSE (Server-Sent Events)

GET http://localhost:8080/mcp/sse

Ideal para:

Opção alternativa quando stdio não é preferido
Clientes baseados na web
Conexões de longa duração
Atualizações em tempo real

3. HTTP Stream

POST http://localhost:8080/mcp/stream
Content-Type: application/json

Ideal para:

Clientes MCP personalizados
Padrões de requisição/resposta
Acesso programático

Endpoints da API REST

Além das ferramentas MCP, o servidor também expõe endpoints REST:

Obter Repositórios

GET /bitbucket/repositories?workspace={workspace}&page={page}&pagelen={pagelen}

Exemplo:

curl "http://localhost:8080/bitbucket/repositories?workspace=myteam&page=1&pagelen=10"

Saúde e Métricas

# Health check
curl http://localhost:8080/q/health

# Readiness check
curl http://localhost:8080/q/health/ready

# Liveness check
curl http://localhost:8080/q/health/live

# Metrics (if enabled)
curl http://localhost:8080/q/metrics

Casos de Uso

Automação de Revisão de Código

Use assistentes de IA para:

Revisar pull requests e fornecer feedback
Verificar problemas de qualidade de código
Sugerir melhorias
Adicionar comentários inline em linhas específicas

Exemplo de prompt para Claude:

Review pull request #42 in workspace "myteam" repository "myrepo". 
Check for:
1. Code quality issues
2. Potential bugs
3. Best practice violations
Add inline comments where improvements are needed.

Gerenciamento de PRs

Listar todos os pull requests abertos
Obter informações detalhadas sobre PRs específicos
Visualizar diffs e alterações
Gerenciar comentários e discussões

Exemplo de prompt:

Show me all open pull requests in myteam/myrepo and summarize what each one does

Colaboração em Equipe

Buscar perfis de usuários
Acompanhar atividade de PRs
Monitorar alterações de código
Facilitar discussões de revisão de código

Solução de Problemas

Problemas Comuns

Problema: "Falha na autenticação"

Verifique se seu BITBUCKET_EMAIL e BITBUCKET_API_TOKEN estão corretos
Garanta que o token da API tenha as permissões necessárias (Repositórios: Leitura, Pull requests: Leitura e Escrita)
Verifique se o workspace existe e você tem acesso
Certifique-se de estar usando um token de API, não uma senha de aplicativo

Problema: "Repositório não encontrado"

Verifique se o workspace e o slug do repositório estão corretos
Garanta que você tenha acesso de leitura ao repositório
Verifique se o repositório existe no workspace especificado

Problema: "Não é possível criar comentário inline"

Primeiro chame findListChangesInAPullRequest para obter os caminhos exatos dos arquivos
Garanta que o caminho do arquivo corresponda exatamente (sensível a maiúsculas/minúsculas)
Verifique se o número da linha é da versão NOVA do arquivo
A linha deve fazer parte das alterações do PR (não linhas inalteradas)

Problema: "A imagem Docker não inicia"

Verifique se todas as variáveis de ambiente necessárias estão definidas
Verifique se a porta 8080 não está em uso
Verifique os logs do Docker: docker logs bitbucket-mcp

Logs

Visualize os logs da aplicação:

# Docker logs
docker logs -f bitbucket-mcp

# Local development
# Logs are printed to console when running ./mvnw quarkus:dev

Roadmap

Estamos trabalhando ativamente para melhorar o Bitbucket MCP Server. Aqui está o que está planejado:

✅ Recentemente Concluído

Suporte ao Transporte stdio - ✨ Agora disponível!
- Transporte universal para TODOS os clientes MCP
- Comunicação direta por processo sem servidor HTTP
- Funciona com Claude Desktop, Cursor, VS Code, Cherry Studio e mais
- Use a imagem: subrutin/bitbucket-mcp-server:stdio-0.0.2
- Lançado na versão 0.0.2

🚧 Em Desenvolvimento

Suporte HTTPS/TLS - Habilitar conexões seguras para o transporte SSE
- Permitirá que o Claude Desktop use o transporte SSE
- Configuração de certificado SSL
- Redirecionamento automático de HTTP para HTTPS
- Esperado na próxima versão principal

📋 Recursos Planejados

Autenticação Aprimorada
- Suporte a OAuth 2.0
- Suporte a múltiplos workspaces
- Mecanismo de renovação de token

💡 Considerações Futuras

Integração com GitHub (servidor MCP semelhante para GitHub)
Integração com GitLab
Suporte a webhooks para atualizações em tempo real
Sistema de plugins de ferramentas personalizadas

Quer contribuir? Confira nossa seção Contribuindo!

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Como Contribuir

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add some amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Configuração de Desenvolvimento

Consulte a seção Desenvolvimento para instruções sobre como configurar seu ambiente local.

Licença

Este projeto é open source. Verifique o arquivo LICENSE para detalhes.

Autor

Tedy Saputro

📧 Email: tedy@saputro.dev
🌐 Website: tedy.saputro.dev

Recursos

Suporte

Para problemas, perguntas ou contribuições:

📧 Email: tedy@saputro.dev
🌐 Website: tedy.saputro.dev
💻 GitHub: Visite o repositório do projeto para problemas e pull requests

Personal Bitbucket MCP Server

Documentação