Atlassian Bitbucket

Interactúa con Atlassian Bitbucket Cloud para gestionar repositorios, solicitudes de extracción, espacios de trabajo y código.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor MCP de Atlassian Bitbucket

Un servidor Node.js/TypeScript Model Context Protocol (MCP) para Atlassian Bitbucket Cloud. Permite que sistemas de IA (por ejemplo, LLMs como Claude o Cursor AI) interactúen de forma segura con tus repositorios, pull requests, espacios de trabajo y código en tiempo real.

¿Por qué usar este servidor?

Entrada mínima, salida máxima: Identificadores simples proporcionan detalles completos sin requerir banderas adicionales.
Visualización rica de código: Obtén información detallada sobre cambios de código con estadísticas de archivos, vistas de diff y contexto inteligente.
Autenticación local segura: Ejecuta localmente con tus credenciales, sin almacenar tokens en servidores remotos.
Respuestas Markdown intuitivas: Formato Markdown bien estructurado y consistente para todas las salidas.
Integración completa con Bitbucket: Accede a espacios de trabajo, repositorios, pull requests, comentarios, búsqueda de código y más.

¿Qué es MCP?

Model Context Protocol (MCP) es un estándar abierto para conectar de forma segura sistemas de IA a herramientas externas y fuentes de datos. Este servidor implementa MCP para Bitbucket Cloud, permitiendo que asistentes de IA interactúen con tus datos de Bitbucket programáticamente.

Requisitos previos

Node.js (>=18.x): Descargar
Cuenta de Bitbucket Cloud

Configuración

Paso 1: Autenticación

Elige uno de los siguientes métodos de autenticación:

Opción A: Contraseña de aplicación de Bitbucket (Recomendada)

Genera una desde Contraseñas de aplicación de Bitbucket. Permisos mínimos:

Espacios de trabajo: Lectura
Repositorios: Lectura
Pull Requests: Lectura

También puedes configurar BITBUCKET_DEFAULT_WORKSPACE para especificar un espacio de trabajo predeterminado cuando no se proporcione explícitamente.

Opción B: Token API de Atlassian

Genera uno desde Tokens API de Atlassian.

Nota: Se recomiendan encarecidamente las Contraseñas de aplicación de Bitbucket, ya que proporcionan permisos más granulares y específicos de Bitbucket.

Paso 2: Configurar credenciales

Opción A: Archivo de configuración MCP (Recomendado)

Edita o crea ~/.mcp/configs.json:

Usando Contraseña de aplicación de Bitbucket:

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

Usando Token API de Atlassian:

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

Opción B: Variables de entorno

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

Paso 3: Instalar y ejecutar

Inicio rápido con `npx`

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

Instalación global

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

Paso 4: Conectar al asistente de IA

Configura tu cliente compatible con MCP (por ejemplo, Claude, Cursor AI):

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

Herramientas MCP

Las herramientas MCP usan nombres snake_case, parámetros camelCase y devuelven respuestas con formato Markdown.

bb_ls_workspaces: Lista los espacios de trabajo disponibles (query: str opt). Uso: Ver espacios de trabajo accesibles.
bb_get_workspace: Obtiene detalles del espacio de trabajo (workspaceSlug: str req). Uso: Ver información del espacio de trabajo.
bb_ls_repos: Lista repositorios (workspaceSlug: str opt, projectKey: str opt, query: str opt, role: str opt). Uso: Encontrar repositorios.
bb_get_repo: Obtiene detalles del repositorio (workspaceSlug: str req, repoSlug: str req). Uso: Acceder a información del repositorio.
bb_search: Busca contenido en Bitbucket (workspaceSlug: str req, query: str req, scope: str opt, language: str opt, extension: str opt). Uso: Encontrar código o PRs.
bb_ls_prs: Lista pull requests (workspaceSlug: str req, repoSlug: str req, state: str opt). Uso: Ver PRs abiertos o fusionados.
bb_get_pr: Obtiene detalles del PR (workspaceSlug: str req, repoSlug: str req, prId: str req). Uso: Ver detalles del PR con diffs.
bb_ls_pr_comments: Lista comentarios del PR (workspaceSlug: str req, repoSlug: str req, prId: str req). Uso: Ver discusiones del PR.
bb_add_pr_comment: Agrega comentario al PR (workspaceSlug: str req, repoSlug: str req, prId: str req, content: str req, inline: obj opt). Uso: Agregar comentarios a los PRs.
bb_add_pr: Crea un PR (workspaceSlug: str req, repoSlug: str req, title: str req, sourceBranch: str req, targetBranch: str opt). Uso: Crear nuevos PRs.
bb_add_branch: Crea una rama (workspaceSlug: str req, repoSlug: str req, newBranchName: str req, sourceBranchOrCommit: str opt). Uso: Crear una rama de funcionalidad.
bb_clone_repo: Clona un repositorio (workspaceSlug: str req, repoSlug: str req, targetPath: str req). Uso: Clonar código localmente.
bb_get_commit_history: Obtiene historial de commits (workspaceSlug: str req, repoSlug: str req, revision: str opt, path: str opt). Uso: Ver historial de código.
bb_get_file: Obtiene contenido de archivo (workspaceSlug: str req, repoSlug: str req, filePath: str req, revision: str opt). Uso: Ver archivo específico.
bb_diff_branches: Muestra diff entre ramas (workspaceSlug: str req, repoSlug: str req, sourceBranch: str req, targetBranch: str req). Uso: Comparar ramas.
bb_diff_commits: Muestra diff entre commits (workspaceSlug: str req, repoSlug: str req, sourceCommit: str req, targetCommit: str req). Uso: Comparar commits.
bb_list_branches: Lista ramas (workspaceSlug: str req, repoSlug: str req, query: str opt, sort: str opt). Uso: Ver todas las ramas.

Ejemplos de herramientas MCP (clic para expandir)

`bb_ls_workspaces`

Listar todos los espacios de trabajo:

{}

Buscar espacios de trabajo:

{ "query": "devteam" }

`bb_get_workspace`

Obtener detalles del espacio de trabajo:

{ "workspaceSlug": "acme-corp" }

`bb_ls_repos`

Listar repositorios en el espacio de trabajo:

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

Listar repositorios usando el espacio de trabajo predeterminado:

{ "projectKey": "PROJ" }

`bb_get_repo`

Obtener detalles del repositorio:

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

`bb_search`

Buscar código:

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

`bb_ls_prs`

Listar PRs abiertos:

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

`bb_get_pr`

Obtener detalles del PR:

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

`bb_ls_pr_comments`

Listar comentarios del PR:

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

`bb_add_pr_comment`

Agregar comentario general:

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

Agregar comentario en línea:

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

`bb_add_pr`

Crear pull request:

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

`bb_add_branch`

Crear nueva rama:

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

`bb_clone_repo`

Clonar repositorio:

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

`bb_get_commit_history`

Ver historial de commits:

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

Historial de commits filtrado:

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

`bb_get_file`

Obtener contenido de archivo:

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

`bb_diff_branches`

Comparar ramas:

{
	"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 las ramas:

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

Ramas filtradas:

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

Comandos CLI

Los comandos CLI usan kebab-case. Ejecuta --help para más detalles (por ejemplo, mcp-atlassian-bitbucket ls-workspaces --help).

ls-workspaces: Lista espacios de trabajo (--query). Ej: mcp-atlassian-bitbucket ls-workspaces.
get-workspace: Obtiene detalles del espacio de trabajo (--workspace-slug). Ej: mcp-atlassian-bitbucket get-workspace --workspace-slug acme-corp.
ls-repos: Lista repositorios (--workspace-slug, --project-key, --query). Ej: mcp-atlassian-bitbucket ls-repos --workspace-slug acme-corp.
get-repo: Obtiene detalles del repositorio (--workspace-slug, --repo-slug). Ej: mcp-atlassian-bitbucket get-repo --workspace-slug acme-corp --repo-slug backend-api.
search: Busca código (--workspace-slug, --query, --scope, --language). Ej: mcp-atlassian-bitbucket search --workspace-slug acme-corp --query "auth".
ls-prs: Lista PRs (--workspace-slug, --repo-slug, --state). Ej: mcp-atlassian-bitbucket ls-prs --workspace-slug acme-corp --repo-slug backend-api.
get-pr: Obtiene detalles del PR (--workspace-slug, --repo-slug, --pr-id). Ej: mcp-atlassian-bitbucket get-pr --workspace-slug acme-corp --repo-slug backend-api --pr-id 42.
ls-pr-comments: Lista comentarios del PR (--workspace-slug, --repo-slug, --pr-id). Ej: mcp-atlassian-bitbucket ls-pr-comments --workspace-slug acme-corp --repo-slug backend-api --pr-id 42.
add-pr-comment: Agrega comentario al PR (--workspace-slug, --repo-slug, --pr-id, --content). Ej: mcp-atlassian-bitbucket add-pr-comment --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 --content "Looks good".
add-pr: Crea PR (--workspace-slug, --repo-slug, --title, --source-branch). Ej: mcp-atlassian-bitbucket add-pr --workspace-slug acme-corp --repo-slug backend-api --title "New feature" --source-branch feature/login.
get-file: Obtiene contenido de archivo (--workspace-slug, --repo-slug, --file-path). Ej: mcp-atlassian-bitbucket get-file --workspace-slug acme-corp --repo-slug backend-api --file-path src/main.js.
add-branch: Crea rama (--workspace-slug, --repo-slug, --new-branch-name). Ej: mcp-atlassian-bitbucket add-branch --workspace-slug acme-corp --repo-slug backend-api --new-branch-name feature/new.

Ejemplos de comandos CLI (clic para expandir)

Listar y ver espacios de trabajo/repositorios

# 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

Trabajar con 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 y 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

Gestión de ramas

# 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 respuesta

Todas las respuestas tienen formato Markdown, incluyendo:

Título: Operación realizada o entidad visualizada.
Contexto: Información del espacio de trabajo, repositorio, pull request o rama.
Contenido: Datos principales como contenido de archivo, detalles del PR o resultados de búsqueda.
Metadatos: Marcas de tiempo, autores y estadísticas.
Diffs: Cambios de código con resaltado de sintaxis para diffs entre ramas/commits.

Ejemplos de formato de respuesta (clic para expandir)

Detalles del repositorio

# 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*

Revisión 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*

Desarrollo

# 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

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

Haz un fork del repositorio.
Crea una rama de funcionalidad (git checkout -b feature/xyz).
Realiza los commits de cambios (git commit -m "Add xyz feature").
Haz push a la rama (git push origin feature/xyz).
Abre un pull request.

Consulta CONTRIBUTING.md para más detalles.

Licencia

Licencia ISC