Atlassian Bitbucket

Interaja com o Atlassian Bitbucket Cloud para gerenciar repositórios, pull requests, workspaces e código.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP Atlassian Bitbucket

Um servidor Node.js/TypeScript Model Context Protocol (MCP) para Atlassian Bitbucket Cloud. Permite que sistemas de IA (ex.: LLMs como Claude ou Cursor AI) interajam com segurança com seus repositórios, pull requests, workspaces e código em tempo real.

NPM Version Build Status

Por que usar este servidor?

  • Entrada mínima, saída máxima: Identificadores simples fornecem detalhes abrangentes sem exigir flags extras.
  • Visualização rica de código: Obtenha insights detalhados sobre mudanças de código com estatísticas de arquivos, visualizações de diff e contexto inteligente.
  • Autenticação local segura: Execute localmente com suas credenciais, nunca armazenando tokens em servidores remotos.
  • Respostas Markdown intuitivas: Formatação Markdown bem estruturada e consistente para todas as saídas.
  • Integração completa com Bitbucket: Acesse workspaces, repositórios, pull requests, comentários, busca de código e muito mais.

O que é MCP?

Model Context Protocol (MCP) é um padrão aberto para conectar com segurança sistemas de IA a ferramentas externas e fontes de dados. Este servidor implementa MCP para Bitbucket Cloud, permitindo que assistentes de IA interajam com seus dados do Bitbucket programaticamente.

Pré-requisitos

  • Node.js (>=18.x): Download
  • Conta Bitbucket Cloud

Configuração

Passo 1: Autenticar

Escolha um dos seguintes métodos de autenticação:

Opção A: Senha de aplicativo Bitbucket (recomendado)

Gere uma em Bitbucket App Passwords. Permissões mínimas:

  • Workspaces: Leitura
  • Repositórios: Leitura
  • Pull Requests: Leitura

Você também pode definir BITBUCKET_DEFAULT_WORKSPACE para especificar um workspace padrão quando não for fornecido explicitamente.

Opção B: Token da API Atlassian

Gere um em Atlassian API Tokens.

Nota: Senhas de aplicativo Bitbucket são fortemente recomendadas, pois fornecem permissões mais granulares e específicas do Bitbucket.

Passo 2: Configurar credenciais

Opção A: Arquivo de configuração MCP (recomendado)

Edite ou crie ~/.mcp/configs.json:

Usando senha de aplicativo Bitbucket:

{
	"bitbucket": {
		"environments": {
			"ATLASSIAN_BITBUCKET_USERNAME": "<your_username>",
			"ATLASSIAN_BITBUCKET_APP_PASSWORD": "<your_app_password>"
		}
	}
}

Usando token da API Atlassian:

{
	"bitbucket": {
		"environments": {
			"ATLASSIAN_SITE_NAME": "bitbucket",
			"ATLASSIAN_USER_EMAIL": "<your_email>",
			"ATLASSIAN_API_TOKEN": "<your_api_token>"
		}
	}
}

Opção B: Variáveis de ambiente

export ATLASSIAN_BITBUCKET_USERNAME="<your_username>"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="<your_app_password>"

Passo 3: Instalar e executar

Início rápido com npx

npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces

Instalação global

npm install -g @aashari/mcp-server-atlassian-bitbucket
mcp-atlassian-bitbucket ls-workspaces

Passo 4: Conectar ao assistente de IA

Configure seu cliente compatível com MCP (ex.: Claude, Cursor AI):

{
	"mcpServers": {
		"bitbucket": {
			"command": "npx",
			"args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"]
		}
	}
}

Ferramentas MCP

As ferramentas MCP usam nomes snake_case, parâmetros camelCase e retornam respostas formatadas em Markdown.

  • bb_ls_workspaces: Lista workspaces disponíveis (query: str opcional). Uso: Visualizar workspaces acessíveis.
  • bb_get_workspace: Obtém detalhes do workspace (workspaceSlug: str obrigatório). Uso: Visualizar informações do workspace.
  • bb_ls_repos: Lista repositórios (workspaceSlug: str opcional, projectKey: str opcional, query: str opcional, role: str opcional). Uso: Encontrar repositórios.
  • bb_get_repo: Obtém detalhes do repositório (workspaceSlug: str obrigatório, repoSlug: str obrigatório). Uso: Acessar informações do repositório.
  • bb_search: Pesquisa conteúdo do Bitbucket (workspaceSlug: str obrigatório, query: str obrigatório, scope: str opcional, language: str opcional, extension: str opcional). Uso: Encontrar código ou PRs.
  • bb_ls_prs: Lista pull requests (workspaceSlug: str obrigatório, repoSlug: str obrigatório, state: str opcional). Uso: Visualizar PRs abertos ou mesclados.
  • bb_get_pr: Obtém detalhes do PR (workspaceSlug: str obrigatório, repoSlug: str obrigatório, prId: str obrigatório). Uso: Visualizar detalhes do PR com diffs.
  • bb_ls_pr_comments: Lista comentários do PR (workspaceSlug: str obrigatório, repoSlug: str obrigatório, prId: str obrigatório). Uso: Visualizar discussões do PR.
  • bb_add_pr_comment: Adiciona comentário ao PR (workspaceSlug: str obrigatório, repoSlug: str obrigatório, prId: str obrigatório, content: str obrigatório, inline: obj opcional). Uso: Adicionar feedback aos PRs.
  • bb_add_pr: Cria um PR (workspaceSlug: str obrigatório, repoSlug: str obrigatório, title: str obrigatório, sourceBranch: str obrigatório, targetBranch: str opcional). Uso: Criar novos PRs.
  • bb_add_branch: Cria uma branch (workspaceSlug: str obrigatório, repoSlug: str obrigatório, newBranchName: str obrigatório, sourceBranchOrCommit: str opcional). Uso: Criar uma branch de feature.
  • bb_clone_repo: Clona um repositório (workspaceSlug: str obrigatório, repoSlug: str obrigatório, targetPath: str obrigatório). Uso: Clonar código localmente.
  • bb_get_commit_history: Obtém histórico de commits (workspaceSlug: str obrigatório, repoSlug: str obrigatório, revision: str opcional, path: str opcional). Uso: Visualizar histórico de código.
  • bb_get_file: Obtém conteúdo do arquivo (workspaceSlug: str obrigatório, repoSlug: str obrigatório, filePath: str obrigatório, revision: str opcional). Uso: Visualizar arquivo específico.
  • bb_diff_branches: Mostra diff entre branches (workspaceSlug: str obrigatório, repoSlug: str obrigatório, sourceBranch: str obrigatório, targetBranch: str obrigatório). Uso: Comparar branches.
  • bb_diff_commits: Mostra diff entre commits (workspaceSlug: str obrigatório, repoSlug: str obrigatório, sourceCommit: str obrigatório, targetCommit: str obrigatório). Uso: Comparar commits.
  • bb_list_branches: Lista branches (workspaceSlug: str obrigatório, repoSlug: str obrigatório, query: str opcional, sort: str opcional). Uso: Visualizar todas as branches.
Exemplos de ferramentas MCP (clique para expandir)

bb_ls_workspaces

Listar todos os workspaces:

{}

Pesquisar workspaces:

{ "query": "devteam" }

bb_get_workspace

Obter detalhes do workspace:

{ "workspaceSlug": "acme-corp" }

bb_ls_repos

Listar repositórios no workspace:

{ "workspaceSlug": "acme-corp", "projectKey": "PROJ" }

Listar repositórios usando workspace padrão:

{ "projectKey": "PROJ" }

bb_get_repo

Obter detalhes do repositório:

{ "workspaceSlug": "acme-corp", "repoSlug": "backend-api" }

bb_search

Pesquisar código:

{
	"workspaceSlug": "acme-corp",
	"query": "Logger",
	"scope": "code",
	"language": "typescript"
}

bb_ls_prs

Listar PRs abertos:

{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "state": "OPEN" }

bb_get_pr

Obter detalhes do PR:

{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "prId": "42" }

bb_ls_pr_comments

Listar comentários do PR:

{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "prId": "42" }

bb_add_pr_comment

Adicionar comentário geral:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"prId": "42",
	"content": "Looks good."
}

Adicionar comentário inline:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"prId": "42",
	"content": "Consider refactoring.",
	"inline": { "path": "src/utils.js", "line": 42 }
}

bb_add_pr

Criar pull request:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"title": "Add login screen",
	"sourceBranch": "feature/login"
}

bb_add_branch

Criar nova branch:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"newBranchName": "feature/new-feature",
	"sourceBranchOrCommit": "main"
}

bb_clone_repo

Clonar repositório:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api",
	"targetPath": "/Users/me/projects"
}

bb_get_commit_history

Visualizar histórico de commits:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api"
}

Histórico de commits filtrado:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api",
	"revision": "develop",
	"path": "src/main/java/com/acme/service/UserService.java"
}

bb_get_file

Obter conteúdo do arquivo:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api",
	"filePath": "src/main/java/com/acme/service/Application.java",
	"revision": "main"
}

bb_diff_branches

Comparar branches:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "web-app",
	"sourceBranch": "develop",
	"targetBranch": "main"
}

bb_diff_commits

Comparar commits:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "web-app",
	"sourceCommit": "a1b2c3d",
	"targetCommit": "e4f5g6h"
}

bb_list_branches

Listar todas as branches:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app"
}

Branches filtradas:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"query": "feature/",
	"sort": "name"
}

Comandos CLI

Os comandos CLI usam kebab-case. Execute --help para detalhes (ex.: mcp-atlassian-bitbucket ls-workspaces --help).

  • ls-workspaces: Lista workspaces (--query). Ex.: mcp-atlassian-bitbucket ls-workspaces.
  • get-workspace: Obtém detalhes do workspace (--workspace-slug). Ex.: mcp-atlassian-bitbucket get-workspace --workspace-slug acme-corp.
  • ls-repos: Lista repositórios (--workspace-slug, --project-key, --query). Ex.: mcp-atlassian-bitbucket ls-repos --workspace-slug acme-corp.
  • get-repo: Obtém detalhes do repositório (--workspace-slug, --repo-slug). Ex.: mcp-atlassian-bitbucket get-repo --workspace-slug acme-corp --repo-slug backend-api.
  • search: Pesquisa código (--workspace-slug, --query, --scope, --language). Ex.: mcp-atlassian-bitbucket search --workspace-slug acme-corp --query "auth".
  • ls-prs: Lista PRs (--workspace-slug, --repo-slug, --state). Ex.: mcp-atlassian-bitbucket ls-prs --workspace-slug acme-corp --repo-slug backend-api.
  • get-pr: Obtém detalhes do PR (--workspace-slug, --repo-slug, --pr-id). Ex.: mcp-atlassian-bitbucket get-pr --workspace-slug acme-corp --repo-slug backend-api --pr-id 42.
  • ls-pr-comments: Lista comentários do PR (--workspace-slug, --repo-slug, --pr-id). Ex.: mcp-atlassian-bitbucket ls-pr-comments --workspace-slug acme-corp --repo-slug backend-api --pr-id 42.
  • add-pr-comment: Adiciona comentário ao PR (--workspace-slug, --repo-slug, --pr-id, --content). Ex.: mcp-atlassian-bitbucket add-pr-comment --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 --content "Looks good".
  • add-pr: Cria PR (--workspace-slug, --repo-slug, --title, --source-branch). Ex.: mcp-atlassian-bitbucket add-pr --workspace-slug acme-corp --repo-slug backend-api --title "New feature" --source-branch feature/login.
  • get-file: Obtém conteúdo do arquivo (--workspace-slug, --repo-slug, --file-path). Ex.: mcp-atlassian-bitbucket get-file --workspace-slug acme-corp --repo-slug backend-api --file-path src/main.js.
  • add-branch: Cria branch (--workspace-slug, --repo-slug, --new-branch-name). Ex.: mcp-atlassian-bitbucket add-branch --workspace-slug acme-corp --repo-slug backend-api --new-branch-name feature/new.
Exemplos de comandos CLI (clique para expandir)

Listar e visualizar workspaces/repositórios

# List all workspaces
mcp-atlassian-bitbucket ls-workspaces

# Get details of a specific workspace
mcp-atlassian-bitbucket get-workspace --workspace-slug acme-corp

# List repositories in a workspace
mcp-atlassian-bitbucket ls-repos --workspace-slug acme-corp --project-key PROJ

# Get details of a specific repository
mcp-atlassian-bitbucket get-repo --workspace-slug acme-corp --repo-slug backend-api

Trabalhando com pull requests

# List open pull requests in a repository
mcp-atlassian-bitbucket ls-prs --workspace-slug acme-corp --repo-slug frontend-app --state OPEN

# Get details of a specific pull request with code changes
mcp-atlassian-bitbucket get-pr --workspace-slug acme-corp --repo-slug frontend-app --pr-id 42

# List comments on a pull request
mcp-atlassian-bitbucket ls-pr-comments --workspace-slug acme-corp --repo-slug frontend-app --pr-id 42

# Add a comment to a pull request
mcp-atlassian-bitbucket add-pr-comment --workspace-slug acme-corp --repo-slug frontend-app --pr-id 42 --content "Looks good to merge."

# Create a new pull request
mcp-atlassian-bitbucket add-pr --workspace-slug acme-corp --repo-slug frontend-app --title "Add login screen" --source-branch feature/login

Código e commits

# Search for code
mcp-atlassian-bitbucket search --workspace-slug acme-corp --query "Logger" --scope code --language typescript

# View commit history
mcp-atlassian-bitbucket get-commit-history --workspace-slug acme-corp --repo-slug backend-api --revision develop

# Get file content
mcp-atlassian-bitbucket get-file --workspace-slug acme-corp --repo-slug backend-api --file-path "src/Application.java" --revision main

# Compare branches
mcp-atlassian-bitbucket diff-branches --workspace-slug acme-corp --repo-slug web-app --source-branch develop --target-branch main

# Compare commits
mcp-atlassian-bitbucket diff-commits --workspace-slug acme-corp --repo-slug web-app --source-commit a1b2c3d --target-commit e4f5g6h

Gerenciamento de branches

# List branches
mcp-atlassian-bitbucket list-branches --workspace-slug acme-corp --repo-slug frontend-app --query "feature/" --sort name

# Create a new branch
mcp-atlassian-bitbucket add-branch --workspace-slug acme-corp --repo-slug frontend-app --new-branch-name feature/new-feature --source-branch-or-commit main

# Clone a repository
mcp-atlassian-bitbucket clone --workspace-slug acme-corp --repo-slug backend-api --target-path ./cloned-projects

Formato de resposta

Todas as respostas são formatadas em Markdown, incluindo:

  • Título: Operação realizada ou entidade visualizada.
  • Contexto: Informações do workspace, repositório, pull request ou branch.
  • Conteúdo: Dados principais, como conteúdo de arquivo, detalhes do PR ou resultados de pesquisa.
  • Metadados: Carimbos de data/hora, autores e estatísticas.
  • Diffs: Mudanças de código com realce de sintaxe para diffs entre branches/commits.
Exemplos de formato de resposta (clique para expandir)

Detalhes do repositório

# Repository: backend-api

**Workspace:** acme-corp
**Full Name:** acme-corp/backend-api
**Language:** Java
**Created:** 2024-01-15 by John Smith
**Updated:** 2025-05-10 (2 days ago)

## Overview
Spring Boot backend API for the ACME product suite.

## Statistics
- **Default Branch:** main
- **Size:** 24.5 MB
- **Commits:** 358
- **Open PRs:** 4
- **Forks:** 3

## Recent Activity
- PR #42: "Add OAuth2 support" by Jane Doe (Open)
- PR #41: "Fix pagination bug" by Alex Kim (Merged)
- PR #40: "Update dependencies" by John Smith (Merged)

*Repository URL: https://bitbucket.org/acme-corp/backend-api*

Revisão de pull request

# Pull Request #42: Add OAuth2 support

**Repository:** acme-corp/backend-api
**Author:** Jane Doe
**State:** OPEN
**Created:** 2025-05-15 (4 days ago)
**Updated:** 2025-05-18 (yesterday)

## Description
Implements OAuth2 authentication flow with support for:
- Authorization code grant
- Refresh tokens
- Token caching

## Changes
- **Files changed:** 7
- **Additions:** 245 lines
- **Deletions:** 32 lines

## Diff for src/auth/OAuthService.java


	@@ -10,6 +10,25 @@ public class OAuthService {
		private final TokenRepository tokenRepository;
		private final HttpClient httpClient;
	
	+    @Autowired
	+    public OAuthService(
	+            TokenRepository tokenRepository,
	+            HttpClient httpClient) {
	+        this.tokenRepository = tokenRepository;
	+        this.httpClient = httpClient;
	+    }
	+
	+    public TokenResponse refreshToken(String refreshToken) {
	+        // Validate refresh token
	+        if (StringUtils.isEmpty(refreshToken)) {
	+            throw new InvalidTokenException("Refresh token cannot be empty");
	+        }
	+        
	+        // Call OAuth server for new access token
	+        return httpClient.post("/oauth/token")
	+            .body(Map.of("grant_type", "refresh_token", "refresh_token", refreshToken))
	+            .execute()
	+            .as(TokenResponse.class);
	+    }

## Comments (3)
1. **John Smith** (2 days ago):
   > Please add unit tests for the refresh token flow

2. **Jane Doe** (yesterday):
   > Added tests in the latest commit

3. **Approval by:** Alex Kim (yesterday)

*Pull Request URL: https://bitbucket.org/acme-corp/backend-api/pull-requests/42*

Desenvolvimento

# Clone repository
git clone https://github.com/aashari/mcp-server-atlassian-bitbucket.git
cd mcp-server-atlassian-bitbucket

# Install dependencies
npm install

# Run in development mode
npm run dev:server

# Run tests
npm test

Contribuindo

Contribuições são bem-vindas! Por favor:

  1. Faça um fork do repositório.
  2. Crie uma branch de feature (git checkout -b feature/xyz).
  3. Faça commit das alterações (git commit -m "Add xyz feature").
  4. Envie para a branch (git push origin feature/xyz).
  5. Abra um pull request.

Consulte CONTRIBUTING.md para detalhes.

Licença

Licença ISC