Servidor MCP de Atlassian Bitbucket
Un servidor de Protocolo de Contexto de Modelo (MCP) Node.js/TypeScript para Atlassian Bitbucket Cloud. Permite que los sistemas de IA (p. ej., LLM como Claude o Cursor AI) interactúen de forma segura con sus repositorios, solicitudes de extracción, espacios de trabajo y código en tiempo real.
¿Por qué utilizar este servidor?
- Entrada mínima, salida máxima : los identificadores simples proporcionan detalles completos sin necesidad de indicadores adicionales.
- Visualización de código enriquecido : obtenga información detallada sobre los cambios de código con estadísticas de archivos, vistas de diferencias y contexto inteligente.
- Autenticación local segura : ejecútela localmente con sus credenciales y nunca almacene tokens en servidores remotos.
- Respuestas intuitivas de Markdown : formato de Markdown consistente y bien estructurado para todas las salidas.
- Integración completa con Bitbucket : acceda a espacios de trabajo, repositorios, solicitudes de extracción, comentarios, búsqueda de código y más.
¿Qué es MCP?
El Protocolo de Contexto de Modelo (MCP) es un estándar abierto para conectar de forma segura sistemas de IA a herramientas y fuentes de datos externas. Este servidor implementa MCP para Bitbucket Cloud, lo que permite que los asistentes de IA interactúen con sus datos de Bitbucket mediante programación.
Prerrequisitos
- Node.js (>=18.x): Descargar
- Cuenta en la nube de Bitbucket
Configuración
Paso 1: Autenticar
Elija uno de los siguientes métodos de autenticación:
Opción A: Contraseña de la aplicación Bitbucket (recomendada)
Genera una desde las contraseñas de la aplicación Bitbucket . Permisos mínimos:
- Espacios de trabajo: Leer
- Repositorios: Leer
- Solicitudes de extracción: lectura
También puede configurar BITBUCKET_DEFAULT_WORKSPACE para especificar un espacio de trabajo predeterminado cuando no se proporciona explícitamente.
Opción B: Token de API de Atlassian
Genere uno a partir de tokens API de Atlassian .
Nota: Se recomienda encarecidamente utilizar contraseñas de aplicaciones 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)
Editar o crear ~/.mcp/configs.json :
Usando la contraseña de la aplicación Bitbucket:
{
"bitbucket": {
"environments": {
"ATLASSIAN_BITBUCKET_USERNAME": "<your_username>",
"ATLASSIAN_BITBUCKET_APP_PASSWORD": "<your_app_password>"
}
}
}
Uso del 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: Conéctese al Asistente de IA
Configure su 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 utilizan nombres snake_case , parámetros camelCase y devuelven respuestas con formato Markdown.
- bb_ls_workspaces : Enumera 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 los repositorios (
workspaceSlug : str opt, projectKey : str opt, query : str opt, role : str opt). Uso: Buscar repositorios. - bb_get_repo : Obtiene los detalles del repositorio (
workspaceSlug : str req, repoSlug : str req). Uso: Accede a la información del repositorio. - bb_search : Busca contenido de Bitbucket (
workspaceSlug : str req, query : str req, scope : str opt, language : str opt, extension : str opt). Uso: Buscar código o solicitudes de solicitud (PR). - bb_ls_prs : Lista las solicitudes de extracción (
workspaceSlug : str req, repoSlug : str req, state : str opt). Uso: Ver solicitudes de extracción abiertas o fusionadas. - bb_get_pr : Obtiene los detalles de la solicitud de retorno (
workspaceSlug : str req, repoSlug : str req, prId : str req). Uso: Ver detalles de la solicitud de retorno con diferencias. - bb_ls_pr_comments : Lista los comentarios de la solicitud de relaciones públicas (
workspaceSlug : str req, repoSlug : str req, prId : str req). Uso: Ver las discusiones de la solicitud de relaciones públicas. - bb_add_pr_comment : Agrega un comentario a la solicitud de relaciones públicas (
workspaceSlug : str req, repoSlug : str req, prId : str req, content : str req, inline : obj opt). Uso: Agrega comentarios a las solicitudes de relaciones públicas. - bb_add_pr : Crea una solicitud de solicitud (
workspaceSlug : str req, repoSlug : str req, title : str req, sourceBranch : str req, targetBranch : str opt). Uso: Crea nuevas solicitudes de solicitud. - bb_add_branch : Crea una rama (
workspaceSlug : str req, repoSlug : str req, newBranchName : str req, sourceBranchOrCommit : str opt). Uso: Crea una rama de funciones. - bb_clone_repo : Clona un repositorio (
workspaceSlug : str req, repoSlug : str req, targetPath : str req). Uso: Clona código localmente. - bb_get_commit_history : Obtiene el historial de confirmaciones (
workspaceSlug : str req, repoSlug : str req, revision : str opt, path : str opt). Uso: Ver el historial de código. - bb_get_file : Obtiene el contenido del archivo (
workspaceSlug : str req, repoSlug : str req, filePath : str req, revision : str opt). Uso: Ver archivo específico. - bb_diff_branches : Muestra la diferencia entre ramas (
workspaceSlug : str req, repoSlug : str req, sourceBranch : str req, targetBranch : str req). Uso: Compara ramas. - bb_diff_commits : Muestra la diferencia entre confirmaciones (
workspaceSlug : str req, repoSlug : str req, sourceCommit : str req, targetCommit : str req). Uso: Comparar confirmaciones. - bb_list_branches : Lista las ramas (
workspaceSlug : str req, repoSlug : str req, query : str opt, sort : str opt). Uso: Ver todas las ramas.
bb_ls_workspaces
Listar todos los espacios de trabajo:
Buscar espacios de trabajo:
bb_get_workspace
Obtener detalles del espacio de trabajo:
{ "workspaceSlug": "acme-corp" }
bb_ls_repos
Lista de repositorios en el espacio de trabajo:
{ "workspaceSlug": "acme-corp", "projectKey": "PROJ" }
Lista de repositorios que utilizan el espacio de trabajo predeterminado:
bb_get_repo
Obtener detalles del repositorio:
{ "workspaceSlug": "acme-corp", "repoSlug": "backend-api" }
bb_search
Código de búsqueda:
{
"workspaceSlug": "acme-corp",
"query": "Logger",
"scope": "code",
"language": "typescript"
}
bb_ls_prs
Lista de PR abiertas:
{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "state": "OPEN" }
bb_get_pr
Obtenga detalles de relaciones públicas:
{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "prId": "42" }
Lista de comentarios de relaciones públicas:
{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "prId": "42" }
Añadir 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 solicitud de extracción:
{
"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
Repositorio de clones:
{
"workspaceSlug": "acme-corp",
"repoSlug": "backend-api",
"targetPath": "/Users/me/projects"
}
bb_get_commit_history
Ver historial de confirmaciones:
{
"workspaceSlug": "acme-corp",
"repoSlug": "backend-api"
}
Historial de confirmaciones filtrado:
{
"workspaceSlug": "acme-corp",
"repoSlug": "backend-api",
"revision": "develop",
"path": "src/main/java/com/acme/service/UserService.java"
}
bb_get_file
Obtener el contenido del archivo:
{
"workspaceSlug": "acme-corp",
"repoSlug": "backend-api",
"filePath": "src/main/java/com/acme/service/Application.java",
"revision": "main"
}
bb_diff_branches
Comparar sucursales:
{
"workspaceSlug": "acme-corp",
"repoSlug": "web-app",
"sourceBranch": "develop",
"targetBranch": "main"
}
bb_diff_commits
Comparar confirmaciones:
{
"workspaceSlug": "acme-corp",
"repoSlug": "web-app",
"sourceCommit": "a1b2c3d",
"targetCommit": "e4f5g6h"
}
bb_list_branches
Listar todas las sucursales:
{
"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 . Ejecute --help para obtener más información (p. ej., mcp-atlassian-bitbucket ls-workspaces --help ).
- ls-workspaces : Enumera los espacios de trabajo (
--query ). Ejemplo: mcp-atlassian-bitbucket ls-workspaces . - get-workspace : Obtiene los detalles del espacio de trabajo (
--workspace-slug ). Ejemplo: mcp-atlassian-bitbucket get-workspace --workspace-slug acme-corp . - ls-repos : Lista los repositorios (
--workspace-slug , --project-key , --query ). Ejemplo: mcp-atlassian-bitbucket ls-repos --workspace-slug acme-corp . - get-repo : Obtiene los detalles del repositorio (
--workspace-slug , --repo-slug ). Ejemplo: mcp-atlassian-bitbucket get-repo --workspace-slug acme-corp --repo-slug backend-api . - búsqueda : Busca código (
--workspace-slug , --query , --scope , --language ). Ejemplo: mcp-atlassian-bitbucket search --workspace-slug acme-corp --query "auth" . - ls-prs : Enumera las solicitudes de solicitud (
--workspace-slug , --repo-slug , --state ). Ejemplo: mcp-atlassian-bitbucket ls-prs --workspace-slug acme-corp --repo-slug backend-api . - get-pr : Obtiene los detalles de la solicitud de registro (
--workspace-slug , --repo-slug , --pr-id ). Ejemplo: mcp-atlassian-bitbucket get-pr --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 . - ls-pr-comments : Lista los comentarios de PR (
--workspace-slug , --repo-slug , --pr-id ). Ejemplo: mcp-atlassian-bitbucket ls-pr-comments --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 . - add-pr-comment : Añade un comentario de PR (
--workspace-slug , --repo-slug , --pr-id , --content ). Ejemplo: mcp-atlassian-bitbucket add-pr-comment --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 --content "Looks good" . - add-pr : Crea una solicitud de registro (
--workspace-slug , --repo-slug , --title , --source-branch ). Ejemplo: mcp-atlassian-bitbucket add-pr --workspace-slug acme-corp --repo-slug backend-api --title "New feature" --source-branch feature/login . - get-file : Obtiene el contenido del archivo (
--workspace-slug , --repo-slug , --file-path ). Ejemplo: mcp-atlassian-bitbucket get-file --workspace-slug acme-corp --repo-slug backend-api --file-path src/main.js . - add-branch : Crea una rama (
--workspace-slug , --repo-slug , --new-branch-name ). Ejemplo: mcp-atlassian-bitbucket add-branch --workspace-slug acme-corp --repo-slug backend-api --new-branch-name feature/new .
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
# 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 confirmaciones
# 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 sucursales
# 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
Todas las respuestas están en formato Markdown, incluidas:
- Título : Operación realizada o entidad visualizada.
- Contexto : espacio de trabajo, repositorio, solicitud de extracción o información de rama.
- Contenido : datos primarios como contenido de archivo, detalles de relaciones públicas o resultados de búsqueda.
- Metadatos : marcas de tiempo, autores y estadísticas.
- Diferencias : cambios de código con resaltado de sintaxis para diferencias entre ramas/confirmaciones.
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*
# 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
Contribuyendo
¡Agradecemos sus contribuciones! Por favor:
- Bifurcar el repositorio.
- Crea una rama de características (
git checkout -b feature/xyz ). - Confirmar cambios (
git commit -m "Add xyz feature" ). - Empujar a la rama (
git push origin feature/xyz ). - Abrir una solicitud de extracción.
Consulte CONTRIBUTING.md para obtener más detalles.
Licencia
Licencia ISC