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.

Versión NPM Estado de compilación

¿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.

Related MCP server: GitHub MCP Tools

¿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:

{ "query": "devteam" }

`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:

{ "projectKey": "PROJ" }

`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" }

`bb_ls_pr_comments`

Lista de comentarios de relaciones públicas:

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

`bb_add_pr_comment`

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

Trabajar con solicitudes de extracción

# 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

Formato de respuesta

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*

Revisión de solicitud de extracción

# 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

Servidor MCP de Atlassian Bitbucket

¿Por qué utilizar este servidor?

¿Qué es MCP?

Prerrequisitos

Configuración

Paso 1: Autenticar

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

Opción B: Token de API de Atlassian

Paso 2: Configurar credenciales

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

Opción B: Variables de entorno

Paso 3: Instalar y ejecutar

Inicio rápido con npx

Instalación global

Paso 4: Conéctese al Asistente de IA

Herramientas MCP

bb_ls_workspaces

bb_get_workspace

bb_ls_repos

bb_get_repo

bb_search

bb_ls_prs

bb_get_pr

bb_ls_pr_comments

bb_add_pr_comment

bb_add_pr

bb_add_branch

bb_clone_repo

bb_get_commit_history

bb_get_file

bb_diff_branches

bb_diff_commits

bb_list_branches