Servidor MCP de Bitbucket

Un servidor MCP (Model Context Protocol) que proporciona herramientas para interactuar con la API de Bitbucket, compatible tanto con Bitbucket Cloud como con Bitbucket Server.

Características

Herramientas disponibles (29 en total)

Núcleo de PR (pr_core)

• get_pull_request - Detalles completos de la PR, incluyendo comentarios, cambios de archivo e información de fusión

• list_pull_requests - Listar PRs con filtros (estado, autor, paginación)

• create_pull_request - Crear nuevas solicitudes de extracción (pull requests)

• update_pull_request - Actualizar detalles de la PR (título, descripción, revisores, rama de destino)

• merge_pull_request - Fusionar solicitudes de extracción con varias estrategias

• decline_pull_request - Rechazar una solicitud de extracción

Comentarios de PR (pr_comments)

• add_comment - Añadir comentarios generales, en línea, en hilos o sugerencias a una PR

• delete_comment - Eliminar un comentario de una solicitud de extracción

Revisión de código (pr_review)

• get_pull_request_diff - Diferencias estructuradas línea por línea con tipos ADDED/REMOVED/CONTEXT

• set_pr_approval - Aprobar (approved: true) o retirar aprobación (approved: false) de una PR

• set_review_status - Solicitar cambios (request_changes: true) o eliminar la solicitud (false)

Tareas de PR — Solo Bitbucket Server (pr_tasks)

• list_pr_tasks - Listar todas las tareas en una solicitud de extracción

• create_pr_task - Crear una nueva tarea en una solicitud de extracción

• update_pr_task - Actualizar el texto de una tarea existente

• set_pr_task_status - Marcar una tarea como hecha (done: true) o reabrirla (done: false)

• delete_pr_task - Eliminar una tarea de una solicitud de extracción

• convert_pr_item - Convertir un comentario en una tarea (direction: "to_task") o viceversa ("to_comment")

Commits (commits)

• list_pr_commits - Listar todos los commits en una solicitud de extracción

• list_branch_commits - Listar commits en una rama con filtros de fecha/autor/mensaje

• get_commit_detail - Obtener la diferencia estructurada para un commit específico por SHA

Ramas (branches)

• list_branches - Listar ramas con filtrado y paginación

• get_branch - Información detallada de la rama, incluyendo PRs asociadas y estadísticas

• delete_branch - Eliminar una rama

Archivos (files)

• list_directory_content - Listar archivos y directorios en una ruta del repositorio

• get_file_content - Obtener contenido de archivo con truncamiento inteligente para archivos grandes

• search_files - Buscar archivos por patrón glob (sin distinción entre mayúsculas y minúsculas, como Ctrl+P en VS Code)

Búsqueda — Solo Bitbucket Server (search)

• search_code - Buscar código en todos los repositorios

• search_repositories - Buscar repositorios por nombre o descripción

Descubrimiento (discovery)

• list_projects - Listar todos los proyectos/espacios de trabajo de Bitbucket accesibles

• list_repositories - Listar repositorios en un proyecto o en todos los proyectos accesibles

Optimización de tokens

v2.0.0 introduce un ahorro significativo de tokens en cada solicitud de LLM:

Bitbucket Cloud oculta automáticamente las 10 herramientas exclusivas de servidor sin necesidad de configuración.

BITBUCKET_TOOL_GROUPS le permite exponer solo los grupos relevantes para su flujo de trabajo — vea Filtrado de grupos de herramientas a continuación.

Related MCP server: MCP Server

Instalación

Usando npx (Recomendado)

La forma más fácil de usar este servidor MCP es directamente con npx:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Para Bitbucket Server:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

Desde el código fuente

1. Clone o descargue este repositorio

2. Instale las dependencias:

   npm install

3. Compile el código TypeScript:

   npm run build

Configuración de autenticación

Este servidor utiliza contraseñas de aplicación (App Passwords) de Bitbucket para la autenticación.

Creación de una contraseña de aplicación

1. Inicie sesión en su cuenta de Bitbucket

2. Navegue a: https://bitbucket.org/account/settings/app-passwords/

3. Haga clic en "Create app password"

4. Asígnele una etiqueta descriptiva (ej., "MCP Server")

5. Seleccione los siguientes permisos:

   • Account: Read

   • Repositories: Read, Write

   • Pull requests: Read, Write

6. Haga clic en "Create"

7. Importante: Copie la contraseña generada inmediatamente (¡no podrá volver a verla!)

Ejecución del script de configuración

node scripts/setup-auth.js

Esto le guiará a través del proceso de configuración de autenticación.

Configuración

Añada el servidor a su archivo de configuración de MCP (generalmente ubicado en ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Reemplace:

• /absolute/path/to/bitbucket-mcp-server con la ruta real a este directorio

• your-username con su nombre de usuario de Bitbucket (no el correo electrónico)

• your-app-password con la contraseña de aplicación que creó

Para Bitbucket Server, use:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

Importante para usuarios de Bitbucket Server:

• Use su dirección de correo electrónico completa como nombre de usuario (ej., "john.doe@company.com")

• Esto es necesario para que las acciones de aprobación/revisión funcionen correctamente

Filtrado de grupos de herramientas

Reduzca el número de herramientas enviadas al LLM en cada solicitud configurando BITBUCKET_TOOL_GROUPS con una lista de nombres de grupos separados por comas. Solo se expondrán las herramientas de los grupos listados.

Grupos disponibles

Preajustes de ejemplo

Flujo de trabajo de revisión de PR (~2,100 tokens):

"env": {
  "BITBUCKET_TOOL_GROUPS": "pr_core,pr_review,files"
}

Gestión completa de PR (~3,500 tokens):

"env": {
  "BITBUCKET_TOOL_GROUPS": "pr_core,pr_comments,pr_review,pr_tasks"
}

Solo exploración de código (~1,400 tokens):

"env": {
  "BITBUCKET_TOOL_GROUPS": "files,search,discovery"
}

Cuando BITBUCKET_TOOL_GROUPS no está configurado, se exponen todas las herramientas aplicables (comportamiento predeterminado). Los usuarios de Bitbucket Cloud siempre tienen las herramientas exclusivas de servidor ocultas automáticamente, independientemente de esta configuración.

Uso

Una vez configurado, puede usar las herramientas disponibles:

Obtener solicitud de extracción (Get Pull Request)

{
  "tool": "get_pull_request",
  "arguments": {
    "workspace": "PROJ",  // Required - your project key
    "repository": "my-repo",
    "pull_request_id": 123
  }
}

Devuelve información detallada sobre la solicitud de extracción, incluyendo:

• Título y descripción

• Autor y revisores

• Ramas de origen y destino

• Estado de aprobación

• Enlaces a la interfaz web y a las diferencias (diff)

• Detalles del commit de fusión (cuando la PR está fusionada):

  • merge_commit_hash: El hash del commit de fusión

  • merged_by: Quién realizó la fusión

  • merged_at: Cuándo ocurrió la fusión

  • merge_commit_message: El mensaje del commit de fusión

• Comentarios activos con respuestas anidadas (comentarios no resueltos que necesitan atención):

  • active_comments: Matriz de comentarios activos (hasta los 20 comentarios de nivel superior más recientes)

    • Texto del comentario y autor

    • Fecha de creación

    • Si es un comentario en línea (con ruta de archivo y número de línea)

    • Respuestas anidadas (para Bitbucket Server):

      • replies: Matriz de comentarios de respuesta con la misma estructura

      • Las respuestas pueden estar anidadas en múltiples niveles

    • Referencia principal (para Bitbucket Cloud):

      • parent_id: ID del comentario principal para las respuestas

  • active_comment_count: Recuento total de comentarios no resueltos (incluyendo respuestas anidadas)

  • total_comment_count: Recuento total de todos los comentarios (incluyendo resueltos y respuestas)

• Cambios de archivo:

  • file_changes: Matriz de todos los archivos modificados en la PR

    • Ruta del archivo

    • Estado (añadido, modificado, eliminado o renombrado)

    • Ruta antigua (para archivos renombrados)

  • file_changes_summary: Estadísticas de resumen

    • Total de archivos cambiados

• Y más...

Buscar código

Buscar código en los repositorios de Bitbucket (actualmente solo compatible con Bitbucket Server):

// Search in a specific repository
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "search_query": "TODO",
    "limit": 50
  }
}

// Search across all repositories in a workspace
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "search_query": "deprecated",
    "file_pattern": "*.java",  // Optional: filter by file pattern
    "limit": 100
  }
}

// Search with file pattern filtering
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "repository": "frontend-app",
    "search_query": "useState",
    "file_pattern": "*.tsx",  // Only search in .tsx files
    "start": 0,
    "limit": 25
  }
}

Devuelve resultados de búsqueda con:

• Ruta y nombre del archivo

• Información del repositorio y proyecto

• Líneas coincidentes con:

  • Número de línea

  • Contenido completo de la línea

  • Segmentos resaltados que muestran coincidencias exactas

• Información de paginación

Respuesta de ejemplo:

{
  "message": "Code search completed successfully",
  "workspace": "PROJ",
  "repository": "my-repo",
  "search_query": "TODO",
  "results": [
    {
      "file_path": "src/utils/helper.js",
      "file_name": "helper.js",
      "repository": "my-repo",
      "project": "PROJ",
      "matches": [
        {
          "line_number": 42,
          "line_content": "    // TODO: Implement error handling",
          "highlighted_segments": [
            { "text": "    // ", "is_match": false },
            { "text": "TODO", "is_match": true },
            { "text": ": Implement error handling", "is_match": false }
          ]
        }
      ]
    }
  ],
  "total_count": 15,
  "start": 0,
  "limit": 50,
  "has_more": false
}

Nota: Esta herramienta actualmente solo funciona con Bitbucket Server. El soporte para Bitbucket Cloud está planificado para una futura versión.

Listar solicitudes de extracción

{
  "tool": "list_pull_requests",
  "arguments": {
    "workspace": "PROJ",  // Required - your project key
    "repository": "my-repo",
    "state": "OPEN",  // Optional: OPEN, MERGED, DECLINED, ALL (default: OPEN)
    "author": "username",  // Optional: filter by author (see note below)
    "limit": 25,  // Optional: max results per page (default: 25)
    "start": 0  // Optional: pagination start index (default: 0)
  }
}

Devuelve una lista paginada de solicitudes de extracción con:

• Matriz de solicitudes de extracción con los mismos detalles que get_pull_request

• Recuento total de PRs coincidentes

• Información de paginación (has_more, next_start)

Nota sobre el filtro de autor:

• Para Bitbucket Cloud: Use el nombre de usuario (ej., "johndoe")

• Para Bitbucket Server: Use la dirección de correo electrónico completa (ej., "john.doe@company.com")

Crear solicitud de extracción

{
  "tool": "create_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "title": "Add new feature",
    "source_branch": "feature/new-feature",
    "destination_branch": "main",
    "description": "This PR adds a new feature...",  // Optional
    "reviewers": ["john.doe", "jane.smith"],  // Optional
    "close_source_branch": true  // Optional (default: false)
  }
}

Actualizar solicitud de extracción

{
  "tool": "update_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "title": "Updated title",  // Optional
    "description": "Updated description",  // Optional
    "destination_branch": "develop",  // Optional
    "reviewers": ["new.reviewer"]  // Optional - see note below
  }
}

Nota importante sobre los revisores:

• Al actualizar una PR sin especificar el parámetro reviewers, se conservan los revisores existentes y su estado de aprobación

• Al proporcionar el parámetro reviewers:

  • La lista de revisores se reemplaza por la nueva lista

  • Para los revisores que ya existen en la PR, se conserva su estado de aprobación

  • Los nuevos revisores se añaden sin estado de aprobación

• Esto evita eliminar accidentalmente a los revisores cuando solo desea actualizar la descripción o el título de la PR

Añadir comentario

Añada un comentario a una solicitud de extracción, ya sea como comentario general o en línea en código específico:

// General comment
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Great work on this PR!"
  }
}

// Inline comment on specific line
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Consider extracting this into a separate function",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT"  // ADDED, REMOVED, or CONTEXT
  }
}

// Reply to existing comment
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "I agree with this suggestion",
    "parent_comment_id": 456
  }
}

// Add comment with code suggestion (single line)
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This variable name could be more descriptive.",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT",
    "suggestion": "const userAuthenticationToken = token;"
  }
}

// Add comment with multi-line code suggestion
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This function could be simplified using array methods.",
    "file_path": "src/utils/calculations.js",
    "line_number": 50,
    "suggestion_end_line": 55,
    "line_type": "CONTEXT",
    "suggestion": "function calculateTotal(items) {\n  return items.reduce((sum, item) => sum + item.price, 0);\n}"
  }
}

La función de sugerencia formatea los comentarios utilizando bloques de sugerencia de markdown al estilo de GitHub que Bitbucket puede renderizar. Al añadir una sugerencia:

• suggestion es obligatorio y contiene el código de reemplazo

• file_path y line_number son obligatorios al usar sugerencias

• suggestion_end_line es opcional y se usa para sugerencias de varias líneas (por defecto es line_number)

• El comentario se formateará con un bloque de markdown suggestion que puede ser aplicable en la interfaz de usuario de Bitbucket

Uso de fragmentos de código en lugar de números de línea

La herramienta add_comment ahora admite encontrar números de línea automáticamente usando fragmentos de código. Esto es especialmente útil cuando las herramientas de IA analizan diferencias y pueden tener dificultades con los números de línea exactos:

// Add comment using code snippet
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This variable name could be more descriptive",
    "file_path": "src/components/Button.res",
    "code_snippet": "let isDisabled = false",
    "search_context": {
      "before": ["let onClick = () => {"],
      "after": ["setLoading(true)"]
    }
  }
}

// Handle multiple matches with strategy
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Consider extracting this",
    "file_path": "src/utils/helpers.js",
    "code_snippet": "return result;",
    "search_context": {
      "before": ["const result = calculate();"],
      "after": ["}"]
    },
    "match_strategy": "best"  // Auto-select highest confidence match
  }
}

Parámetros de fragmento de código:

• code_snippet: La línea de código exacta a buscar (alternativa a line_number)

• search_context: Contexto opcional para desambiguar múltiples coincidencias

  • before: Matriz de líneas que deberían aparecer antes del objetivo

  • after: Matriz de líneas que deberían aparecer después del objetivo

• match_strategy: Cómo manejar múltiples coincidencias

  • "strict" (predeterminado): Fallar con un error mostrando todas las coincidencias

  • "best": Seleccionar automáticamente la coincidencia de mayor confianza

Respuesta de error para múltiples coincidencias (modo estricto):

{
  "error": {
    "code": "MULTIPLE_MATCHES_FOUND",
    "message": "Code snippet 'return result;' found in 3 locations",
    "occurrences": [
      {
        "line_number": 42,
        "file_path": "src/utils/helpers.js",
        "preview": "  const result = calculate();\n> return result;\n}",
        "confidence": 0.9,
        "line_type": "ADDED"
      },
      // ... more matches
    ],
    "suggestion": "To resolve, either:\n1. Add more context...\n2. Use match_strategy: 'best'...\n3. Use line_number directly"
  }
}

Esta función es particularmente útil para:

• Herramientas de revisión de código impulsadas por IA que analizan diferencias

• Scripts que añaden comentarios automáticamente basados en patrones de código

• Evitar confusiones de números de línea en diferencias grandes

Nota sobre respuestas a comentarios:

• Use parent_comment_id para responder a cualquier comentario (general o en línea)

• En las respuestas de get_pull_request:

  • Bitbucket Server muestra las respuestas anidadas en una matriz replies

  • Bitbucket Cloud muestra un campo parent_id para los comentarios de respuesta

• Puede responder a respuestas, creando conversaciones anidadas

Nota sobre comentarios en línea:

• file_path: La ruta al archivo tal como se muestra en la diferencia

• line_number: El número de línea tal como se muestra en la diferencia

• line_type:

  • ADDED - Para líneas recién añadidas (verde en la diferencia)

  • REMOVED - Para líneas eliminadas (rojo en la diferencia