Bitbucket Server MCP

Gestiona solicitudes de extracción en Bitbucket Server.

Documentación

Bitbucket Server MCP

Servidor MCP (Model Context Protocol) para la gestión de Pull Requests en Bitbucket Server. Este servidor proporciona herramientas y recursos para interactuar con la API de Bitbucket Server a través del protocolo MCP.

✨ Nuevas Funcionalidades

🔧 Cabeceras HTTP Personalizadas: Añade cabeceras personalizadas a todas las solicitudes mediante la variable de entorno BITBUCKET_CUSTOM_HEADERS (útil para tokens Zero Trust o proxies)
📋 Descubrimiento de PR: Lista y filtra pull requests por estado, autor o dirección usando list_pull_requests (corrige #14)
🌿 Gestión de Ramas: Lista ramas con detección de rama predeterminada usando list_branches, elimina ramas fusionadas con delete_branch
📝 Historial de Commits: Explora el historial de commits con filtrado por rama y autor usando list_commits
✅ Aprobación de PR: Aprueba y desaprueba pull requests con approve_pull_request y unapprove_pull_request
🔍 Búsqueda Avanzada: Busca código y archivos en repositorios con filtrado por proyecto/repositorio usando la herramienta search
📄 Operaciones de Archivos: Lee contenidos de archivos y explora directorios de repositorios con get_file_content y browse_repository
💬 Gestión de Comentarios: Extrae y filtra comentarios de PR con la herramienta get_comments
🔍 Descubrimiento de Proyectos: Lista todos los proyectos de Bitbucket accesibles con list_projects
📁 Exploración de Repositorios: Explora repositorios en todos los proyectos con list_repositories
🔧 Soporte Flexible de Proyectos: Haz que el proyecto predeterminado sea opcional - especifícalo por comando o usa BITBUCKET_DEFAULT_PROJECT
📖 Documentación Mejorada: README mejorado con ejemplos de uso y mejor guía de configuración

Requisitos

Node.js >= 16

Instalación

Instalación mediante Smithery

Para instalar Bitbucket Server para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @garc33/bitbucket-server-mcp-server --client claude

Instalación Manual

npm install

Compilación

npm run build

Funcionalidades

El servidor proporciona las siguientes herramientas para una integración completa con Bitbucket Server:

`list_projects`

Descubre y explora proyectos de Bitbucket: Lista todos los proyectos accesibles con sus detalles. Esencial para el descubrimiento de proyectos y para encontrar las claves de proyecto correctas para usar en otras operaciones.

Casos de uso:

Encuentra proyectos disponibles cuando no conoces la clave de proyecto exacta
Explora la estructura y los permisos de los proyectos
Descubre nuevos proyectos a los que tienes acceso

Parámetros:

limit: Número de proyectos a devolver (predeterminado: 25, máximo: 1000)
start: Índice de inicio para la paginación (predeterminado: 0)

`list_repositories`

Explora y descubre repositorios: Explora repositorios dentro de proyectos específicos o en todos los proyectos accesibles. Devuelve información completa del repositorio, incluyendo URLs de clonación y metadatos.

Casos de uso:

Encuentra slugs de repositorio para otras operaciones
Explora la estructura del código en todos los proyectos
Descubre repositorios a los que tienes acceso
Explora los repositorios de un proyecto específico

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
limit: Número de repositorios a devolver (predeterminado: 25, máximo: 1000)
start: Índice de inicio para la paginación (predeterminado: 0)

`create_pull_request`

Propone cambios de código para revisión: Crea una nueva pull request para enviar cambios de código, solicitar revisiones o fusionar ramas de funcionalidad. Maneja automáticamente las referencias de ramas y la asignación de revisores.

Casos de uso:

Envía desarrollo de funcionalidades para revisión
Propone correcciones de errores
Solicita la integración de código desde ramas de funcionalidad
Colabora en cambios de código

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
title (obligatorio): Título de PR claro y descriptivo
description: Descripción detallada con contexto (soporta Markdown)
sourceBranch (obligatorio): Rama de origen que contiene los cambios
targetBranch (obligatorio): Rama de destino para la fusión
reviewers: Matriz de nombres de usuario de revisores
sourceProject: Clave de proyecto del repositorio de origen (para PRs entre repositorios desde forks)
sourceRepository: Slug del repositorio de origen (para PRs entre repositorios desde forks)
includeDefaultReviewers: Obtener e incluir automáticamente los revisores predeterminados configurados para la rama de destino (predeterminado: true)

`update_pull_request`

Actualiza una pull request de forma segura: Modifica el título, la descripción o los revisores de una pull request existente sin perder metadatos. Utiliza un patrón de lectura-modificación-escritura para preservar todos los campos que no se cambian explícitamente.

Casos de uso:

Corrige el título o la descripción del PR después de su creación
Añade o reemplaza revisores sin perder los existentes
Actualiza los metadatos del PR sin afectar el estado de aprobación

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request a actualizar
title: Nuevo título (si se omite, se conserva el título actual)
description: Nueva descripción (si se omite, se conserva la descripción actual)
reviewers: Nueva lista de revisores como matriz de nombres de usuario (si se omite, se conservan los revisores actuales)

`get_pull_request`

Información completa del PR: Recupera información detallada de la pull request, incluyendo estado, revisores, commits y todos los metadatos. Esencial para comprender el estado del PR antes de tomar acciones.

Casos de uso:

Verifica el estado de aprobación del PR
Revisa los detalles y el progreso del PR
Comprende los cambios antes de fusionar
Monitorea el estado del PR

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request

`merge_pull_request`

Integra cambios aprobados: Fusiona una pull request aprobada en la rama de destino. Soporta diferentes estrategias de fusión según tus preferencias de flujo de trabajo.

Casos de uso:

Completa el proceso de revisión de código
Integra funcionalidades aprobadas
Aplica correcciones de errores a las ramas principales
Publica cambios de código

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request
message: Mensaje de commit de fusión personalizado
strategy: Estrategia de fusión:
- merge-commit (predeterminado): Crea un commit de fusión preservando el historial
- squash: Combina todos los commits en uno solo
- fast-forward: Mueve el puntero de la rama sin commit de fusión

`decline_pull_request`

Rechaza cambios no adecuados: Rechaza una pull request que no debería fusionarse, proporcionando retroalimentación al autor.

Casos de uso:

Rechaza cambios que no cumplen los estándares
Cierra PRs que entran en conflicto con la dirección del proyecto
Solicita un retrabajo significativo
Evita la integración de código no deseado

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request
message: Motivo del rechazo (útil para la retroalimentación al autor)

`add_comment`

Participa en la revisión de código: Añade comentarios a las pull requests para retroalimentación de revisión, discusiones y colaboración. Soporta conversaciones en hilos.

Casos de uso:

Proporciona retroalimentación de revisión de código
Haz preguntas sobre cambios específicos
Sugiere mejoras
Participa en discusiones técnicas
Documenta decisiones de revisión

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request
text (obligatorio): Contenido del comentario (soporta Markdown)
parentId: ID del comentario padre para respuestas en hilos
state: Estado del comentario: OPEN (predeterminado, publicado inmediatamente) o PENDING (borrador, visible solo para ti hasta que se publique la revisión)

`get_diff`

Analiza cambios de código: Recupera las diferencias de código mostrando exactamente qué se añadió, eliminó o modificó en la pull request. Soporta truncamiento por archivo para gestionar diffs grandes de manera efectiva.

Casos de uso:

Revisa cambios de código específicos
Comprende el alcance de las modificaciones
Analiza el impacto antes de fusionar
Inspecciona los detalles de implementación
Evaluación de la calidad del código
Maneja archivos grandes sin abrumar la salida

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request
contextLines: Líneas de contexto alrededor de los cambios (predeterminado: 10)
maxLinesPerFile: Número máximo de líneas a mostrar por archivo (opcional, usa la variable de entorno BITBUCKET_DIFF_MAX_LINES_PER_FILE si no se especifica, establece 0 para sin límite)

Manejo de Archivos Grandes: Cuando un archivo supera el límite de maxLinesPerFile, se muestra:

Cabeceras y metadatos del archivo (siempre preservados)
Primer 60% de las líneas permitidas desde el principio
Mensaje de truncamiento con estadísticas del archivo
Último 40% de las líneas permitidas desde el final
Indicación clara de cómo ver el diff completo

`get_reviews`

Sigue el progreso de la revisión: Obtiene el historial de revisiones, el estado de aprobación y la retroalimentación de los revisores para comprender el estado de la revisión.

Casos de uso:

Verifica si el PR está listo para fusionarse
Ve quién ha revisado los cambios
Comprende la retroalimentación de la revisión
Monitorea los requisitos de aprobación
Sigue el progreso de la revisión

`get_activities`

Recupera actividades de la pull request: Obtiene la línea de tiempo completa de actividades de una pull request, incluyendo comentarios, revisiones, commits y otros eventos.

Casos de uso:

Lee discusiones de comentarios y retroalimentación
Revisa la línea de tiempo completa del PR
Sigue los commits añadidos/eliminados del PR
Ve el historial de aprobaciones y revisiones
Comprende el ciclo de vida completo del PR

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request

`get_comments`

Extrae solo comentarios del PR: Filtra las actividades de la pull request para devolver solo los comentarios, facilitando el enfoque en el contenido de la discusión sin revisiones u otras actividades.

Casos de uso:

Lee hilos de discusión del PR
Extrae retroalimentación y preguntas
Enfócate en el contenido de los comentarios sin ruido
Analiza el flujo de la conversación

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request

`search`

Búsqueda avanzada de código y archivos: Busca en repositorios usando la API de búsqueda de Bitbucket con soporte para filtrado por proyecto/repositorio y optimización de consultas. Busca tanto en contenidos de archivos como en nombres de archivos. Nota: La búsqueda solo funciona en la rama predeterminada de los repositorios.

Casos de uso:

Encuentra patrones de código específicos en todos los proyectos
Localiza archivos por nombre o contenido
Busca dentro de proyectos o repositorios específicos
Filtra por extensiones de archivo

Parámetros:

query (obligatorio): Cadena de consulta de búsqueda
project: Clave de proyecto de Bitbucket para limitar el alcance de la búsqueda
repository: Slug del repositorio para búsqueda específica de repositorio
type: Optimización de consulta - "file" (envuelve la consulta entre comillas para coincidencia exacta de nombre de archivo) o "code" (comportamiento de búsqueda predeterminado)
limit: Número de resultados a devolver (predeterminado: 25, máximo: 100)
start: Índice de inicio para la paginación (predeterminado: 0)

Ejemplos de sintaxis de consulta:

"README.md" - Encuentra nombre de archivo exacto
config ext:yml - Encuentra config en archivos YAML
function project:MYPROJECT - Busca "function" en un proyecto específico
bug fix repo:PROJ/my-repo - Busca en un repositorio específico

`get_file_content`

Leer contenido de archivos con paginación: Recupera el contenido de archivos específicos de repositorios con soporte para archivos grandes mediante paginación.

Casos de uso:

Leer archivos de código fuente
Ver archivos de configuración
Extraer contenido de documentación
Inspeccionar versiones específicas de archivos

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
filePath (obligatorio): Ruta al archivo en el repositorio
branch: Rama o hash de commit (opcional, por defecto main/master)
limit: Máximo de líneas por solicitud (por defecto: 100, máximo: 1000)
start: Número de línea inicial para paginación (por defecto: 0)

`browse_repository`

Explorar estructura del repositorio: Navega por archivos y directorios en repositorios para comprender la organización del proyecto y localizar archivos específicos.

Casos de uso:

Explorar la estructura del repositorio
Navegar por árboles de directorios
Encontrar archivos y carpetas
Comprender la organización del proyecto

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
path: Ruta del directorio a explorar (opcional, por defecto la raíz)
branch: Rama o hash de commit (opcional, por defecto main/master)
limit: Máximo de elementos a devolver (por defecto: 50)

`list_pull_requests`

Descubrir y filtrar pull requests: Lista pull requests en un repositorio con filtrado por estado, autor y dirección. Devuelve metadatos de PR que incluyen título, autor, ramas, revisores y estado.

Casos de uso:

Encontrar PRs abiertas en un repositorio
Listar tus propias pull requests
Ver PRs pendientes de revisión
Obtener una visión general de PRs fusionadas o rechazadas
Monitorear la actividad de PRs en un proyecto

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
state: Filtrar por estado de PR — OPEN (por defecto), MERGED, DECLINED o ALL
author: Filtrar por nombre de usuario del autor (coincidencia exacta)
direction: INCOMING (PRs dirigidas a este repositorio, por defecto) o OUTGOING (PRs desde este repositorio)
limit: Número de PRs a devolver (por defecto: 25, máximo: 1000)
start: Índice inicial para paginación (por defecto: 0)

`list_branches`

Explorar ramas del repositorio: Lista ramas en un repositorio con filtrado opcional. Identifica la rama predeterminada y muestra información del último commit para cada rama.

Casos de uso:

Encontrar nombres de ramas para creación de PR o checkout
Verificar la existencia de ramas antes de operaciones
Identificar la rama predeterminada
Buscar ramas por nombre

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
filterText: Filtrar ramas por nombre (coincidencia parcial sin distinción de mayúsculas)
limit: Número de ramas a devolver (por defecto: 25, máximo: 1000)
start: Índice inicial para paginación (por defecto: 0)

`list_commits`

Explorar historial de commits: Lista commits en un repositorio con filtrado opcional por rama y autor. Úsalo para revisar cambios, rastrear contribuciones o comprender la evolución de una rama.

Casos de uso:

Revisar cambios recientes en una rama
Encontrar commits de un autor específico
Rastrear el historial de commits antes de fusionar
Comprender la evolución de una rama

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
branch: Nombre de la rama para listar commits (por defecto, la rama predeterminada del repositorio)
author: Filtrar por nombre o correo del autor (coincidencia parcial sin distinción de mayúsculas, aplicada en el cliente)
limit: Número de commits a devolver (por defecto: 25, máximo: 1000)
start: Índice inicial para paginación (por defecto: 0)

`delete_branch`

Limpiar ramas fusionadas: Elimina una rama de un repositorio. Incluye una verificación de seguridad para evitar la eliminación de la rama predeterminada.

Casos de uso:

Limpiar ramas de características después de fusionar PRs
Eliminar ramas obsoletas o abandonadas
Mantenimiento e higiene del repositorio

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
branch (obligatorio): Nombre de la rama a eliminar

`approve_pull_request`

Aprobar cambios de código: Aprueba una pull request como el usuario autenticado actual. Registra tu aprobación en la PR, indicando que los cambios están listos para fusionarse.

Casos de uso:

Aprobar pull requests revisadas
Señalar que está listo para fusionar
Completar el flujo de trabajo de revisión de código

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request a aprobar

`unapprove_pull_request`

Retirar aprobación: Elimina tu aprobación de una pull request. Úsalo cuando necesites retirar una aprobación previa después de descubrir problemas o cuando la PR haya cambiado.

Casos de uso:

Retirar aprobación después de descubrir problemas
Eliminar aprobación cuando cambia el alcance de la PR
Corregir aprobaciones accidentales

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request de la que se eliminará la aprobación

`edit_comment`

Editar un comentario existente: Modifica el texto de un comentario en una pull request. Funciona tanto con comentarios publicados como pendientes (borradores). Requiere la versión del comentario para bloqueo optimista.

Casos de uso:

Corregir errores tipográficos o de formato en comentarios de revisión
Actualizar información en un comentario existente
Reformatear comentarios (por ejemplo, al estilo Conventional Comments)

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request a la que pertenece el comentario
commentId (obligatorio): ID del comentario a editar
text (obligatorio): Nuevo contenido de texto (soporta Markdown)
version (obligatorio): Versión actual del comentario para bloqueo optimista (de la respuesta de get_comments o add_comment)

`delete_comment`

Eliminar un comentario: Elimina un comentario de una pull request. Requiere la versión del comentario para bloqueo optimista.

Casos de uso:

Eliminar comentarios publicados incorrectamente
Limpiar comentarios borradores que ya no son necesarios

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request a la que pertenece el comentario
commentId (obligatorio): ID del comentario a eliminar
version (obligatorio): Versión actual del comentario para bloqueo optimista

`publish_review`

Publicar una revisión por lotes: Publica todos los comentarios pendientes (borradores) de una vez, opcionalmente estableciendo tu estado de revisión y añadiendo un comentario general. Esto equivale a hacer clic en "Finalizar revisión" en la interfaz de Bitbucket.

Casos de uso:

Publicar todos los comentarios de revisión en borrador en una sola acción
Aprobar una PR junto con comentarios de revisión
Solicitar cambios con un estado de "necesita trabajo" y comentarios

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request
commentText: Comentario general opcional para la revisión
participantStatus: Estado de revisión opcional: APPROVED (listo para fusionar) o NEEDS_WORK (se requieren cambios). Omitir para comentarios generales.

`get_code_insights`

Recuperar resultados de análisis CI/CD: Obtén informes de Code Insights (SonarQube, escaneos de seguridad, etc.) y sus anotaciones para una pull request.

Casos de uso:

Verificar el estado del quality gate de SonarQube
Revisar hallazgos de escaneos de seguridad
Inspeccionar métricas de cobertura de código
Ver anotaciones de análisis CI/CD por archivo

Parámetros:

project: Clave de proyecto de Bitbucket (opcional, usa BITBUCKET_DEFAULT_PROJECT si no se proporciona)
repository (obligatorio): Slug del repositorio
prId (obligatorio): ID de la pull request

`get_dashboard_pull_requests`

Panel de PRs entre repositorios: Lista pull requests en todos los repositorios para el usuario autenticado. Úsalo para ver PRs que necesitas revisar, PRs que has creado o PRs en las que participas, sin necesidad de especificar cada proyecto y repositorio.

Casos de uso:

Ver todas las PRs pendientes de tu revisión
Listar tus propias PRs abiertas en todos los proyectos
Encontrar PRs recientemente fusionadas en las que participaste
Obtener una visión general de tu carga de trabajo de PRs

Parámetros:

state: Filtrar por estado de PR: OPEN (por defecto), MERGED, DECLINED o ALL
role: Filtrar por tu rol: AUTHOR, REVIEWER o PARTICIPANT
participantStatus: Filtrar por tu estado de revisión: APPROVED, UNAPPROVED o NEEDS_WORK
order: Orden de clasificación: OLDEST o NEWEST (por defecto)
closedSince: Incluir solo PRs cerradas actualizadas después de esta marca de tiempo (epoch ms)
limit: Número de PRs a devolver (por defecto: 25)
start: Índice inicial para paginación (por defecto: 0)

Ejemplos de uso

Listar proyectos y repositorios

# List all accessible projects
list_projects

# List repositories in the default project (if BITBUCKET_DEFAULT_PROJECT is set)
list_repositories

# List repositories in a specific project
list_repositories --project "MYPROJECT"

# List projects with pagination
list_projects --limit 10 --start 0

Operaciones de búsqueda y archivos

# Search for README files across all projects
search --query "README" --type "file" --limit 10

# Search for specific code patterns in a project
search --query "function getUserData" --type "code" --project "MYPROJECT"

# Search with file extension filter
search --query "config ext:yml" --project "MYPROJECT"

# Browse repository structure
browse_repository --project "MYPROJECT" --repository "my-repo"

# Browse specific directory
browse_repository --project "MYPROJECT" --repository "my-repo" --path "src/components"

# Read file contents
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "package.json" --limit 20

# Read specific lines from a large file
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "docs/CHANGELOG.md" --start 100 --limit 50

Trabajar con pull requests

# Create a pull request (using default project)
create_pull_request --repository "my-repo" --title "Feature: New functionality" --sourceBranch "feature/new-feature" --targetBranch "main"

# Create a pull request with specific project
create_pull_request --project "MYPROJECT" --repository "my-repo" --title "Bugfix: Critical issue" --sourceBranch "bugfix/critical" --targetBranch "develop" --description "Fixes critical issue #123"

# Get pull request details
get_pull_request --repository "my-repo" --prId 123

# Get only comments from a PR (no reviews/commits)
get_comments --project "MYPROJECT" --repository "my-repo" --prId 123

# Get full PR activity timeline
get_activities --repository "my-repo" --prId 123

# Merge a pull request with squash strategy
merge_pull_request --repository "my-repo" --prId 123 --strategy "squash" --message "Feature: New functionality (#123)"

Descubrir pull requests

# List open PRs in a repository (default state: OPEN)
list_pull_requests --repository "my-repo"

# List all PRs regardless of state
list_pull_requests --repository "my-repo" --state "ALL"

# Find PRs by a specific author
list_pull_requests --repository "my-repo" --author "john.doe"

# List merged PRs with pagination
list_pull_requests --repository "my-repo" --state "MERGED" --limit 10 --start 0

Gestión de ramas

# List all branches in a repository
list_branches --repository "my-repo"

# Filter branches by name
list_branches --project "MYPROJECT" --repository "my-repo" --filterText "feature"

# Delete a merged branch
delete_branch --repository "my-repo" --branch "feature/completed-work"

Historial de commits

# List recent commits on the default branch
list_commits --repository "my-repo"

# List commits on a specific branch
list_commits --repository "my-repo" --branch "develop" --limit 10

# Filter commits by author
list_commits --repository "my-repo" --author "john.doe"

# Combine branch and author filters
list_commits --project "MYPROJECT" --repository "my-repo" --branch "main" --author "jane"

Flujo de trabajo de aprobación de PRs

# Approve a pull request
approve_pull_request --repository "my-repo" --prId 123

# Remove your approval
unapprove_pull_request --repository "my-repo" --prId 123

# Full workflow: review diff, approve, merge
get_diff --repository "my-repo" --prId 123
approve_pull_request --repository "my-repo" --prId 123
merge_pull_request --repository "my-repo" --prId 123 --strategy "squash"

Dependencias

@modelcontextprotocol/sdk - SDK para la implementación del protocolo MCP
axios - Cliente HTTP para solicitudes de API
winston - Marco de registro (logging)

Configuración

El servidor requiere configuración en el archivo de configuración MCP de VSCode. Aquí tienes una configuración de ejemplo:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/bitbucket-server/build/index.js"],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        // Authentication (choose one):
        // Option 1: Personal Access Token
        "BITBUCKET_TOKEN": "your-access-token",
        // Option 2: Username/Password
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_PASSWORD": "your-password",
        // Optional: Default project
        "BITBUCKET_DEFAULT_PROJECT": "your-default-project"
      }
    }
  }
}

Variables de entorno

BITBUCKET_URL (obligatorio): URL base de tu instancia de Bitbucket Server
Autenticación (se requiere una de las siguientes):
- BITBUCKET_TOKEN: Token de acceso personal
- BITBUCKET_USERNAME y BITBUCKET_PASSWORD: Credenciales de autenticación básica
BITBUCKET_DEFAULT_PROJECT (opcional): Clave de proyecto predeterminada para usar cuando no se especifique en las llamadas de herramientas
BITBUCKET_DIFF_MAX_LINES_PER_FILE (opcional): Máximo de líneas predeterminado para mostrar por archivo en los diffs. Configúralo para evitar que archivos grandes abrumen la salida. Puede ser anulado por el parámetro maxLinesPerFile en las llamadas a get_diff.
BITBUCKET_LOG_PATH (opcional): Ruta personalizada para el archivo de registro (por defecto: ~/.bitbucket-server-mcp/bitbucket.log)
BITBUCKET_READ_ONLY (opcional): Establecer en true para habilitar el modo de solo lectura
BITBUCKET_CUSTOM_HEADERS (opcional): Lista separada por comas de encabezados HTTP personalizados para añadir a todas las solicitudes (formato: Header-Name=value,Another-Header=value2). Útil para tokens Zero Trust o encabezados de proxy

Nota: Con el nuevo soporte de proyecto opcional, ahora puedes:

Establecer BITBUCKET_DEFAULT_PROJECT para trabajar con un proyecto específico por defecto
Usar list_projects para descubrir proyectos disponibles
Usar list_repositories para explorar repositorios entre proyectos
Anular el proyecto predeterminado especificando el parámetro project en cualquier llamada de herramienta

Modo de solo lectura

El servidor admite un modo de solo lectura para implementaciones donde desees evitar cualquier modificación en tus repositorios de Bitbucket. Cuando está habilitado, solo están disponibles operaciones seguras y no modificadoras.

Para habilitar el modo de solo lectura: Establece la variable de entorno BITBUCKET_READ_ONLY=true

Herramientas disponibles en modo de solo lectura:

list_projects - Explorar y listar proyectos
list_repositories - Explorar y listar repositorios
get_pull_request - Ver detalles de solicitudes de extracción
list_pull_requests - Listar y filtrar solicitudes de extracción
get_diff - Ver cambios de código y diferencias
get_reviews - Ver historial de revisiones y estado
get_activities - Ver cronología de solicitudes de extracción
get_comments - Ver comentarios de solicitudes de extracción
search - Buscar código y archivos en repositorios
get_file_content - Leer contenido de archivos
browse_repository - Explorar estructura de repositorios
list_branches - Listar ramas de repositorios
list_commits - Explorar historial de confirmaciones
get_code_insights - Recuperar informes de análisis CI/CD y anotaciones
get_dashboard_pull_requests - Listar solicitudes de extracción en todos los repositorios del usuario autenticado

Herramientas deshabilitadas en modo de solo lectura:

create_pull_request - Crear nuevas solicitudes de extracción
update_pull_request - Actualizar título, descripción o revisores de solicitudes de extracción
merge_pull_request - Fusionar solicitudes de extracción
decline_pull_request - Rechazar solicitudes de extracción
add_comment - Agregar comentarios a solicitudes de extracción
add_comment_inline - Agregar comentarios en línea a solicitudes de extracción
edit_comment - Editar comentarios existentes
delete_comment - Eliminar comentarios
publish_review - Publicar revisiones por lotes
delete_branch - Eliminar ramas
approve_pull_request - Aprobar solicitudes de extracción
unapprove_pull_request - Eliminar aprobaciones de solicitudes de extracción

Comportamiento:

Cuando BITBUCKET_READ_ONLY no está configurado o está configurado con un valor distinto de true, todas las herramientas funcionan normalmente (compatible con versiones anteriores)
Cuando BITBUCKET_READ_ONLY=true, las operaciones de escritura se filtran y devolverán un error si se invocan
Esto es perfecto para implementaciones en producción, integración CI/CD o cualquier escenario donde necesites acceso seguro de solo lectura a Bitbucket

Registro de eventos

El servidor registra todas las operaciones usando Winston para fines de depuración y monitoreo.

Ubicación del archivo de registro (en orden de prioridad):

Variable de entorno BITBUCKET_LOG_PATH — ruta personalizada
~/.bitbucket-server-mcp/bitbucket.log — ubicación predeterminada

El directorio de registro se crea automáticamente si no existe.

Ejemplo: Establece una ruta de registro personalizada en tu configuración de MCP:

{
  "env": {
    "BITBUCKET_LOG_PATH": "/var/log/bitbucket-mcp/server.log"
  }
}

Encabezados HTTP personalizados

Puedes agregar encabezados HTTP personalizados a todas las solicitudes de API usando la variable de entorno BITBUCKET_CUSTOM_HEADERS. Esto es útil para tokens de seguridad Zero Trust, encabezados de proxy o cualquier otro encabezado requerido por tu infraestructura.

Formato: Pares clave-valor separados por comas donde los valores pueden contener signos igual:

Header-Name=value,Another-Header=value2

Ejemplo de un solo encabezado:

{
  "env": {
    "BITBUCKET_CUSTOM_HEADERS": "X-Zero-Trust-Token=your-token-here"
  }
}

Ejemplo de múltiples encabezados:

{
  "env": {
    "BITBUCKET_CUSTOM_HEADERS": "X-Custom-Header=value1,X-Proxy-Auth=token123"
  }
}