Bitbucket

Accede a la API de Bitbucket Cloud para automatización, pipelines de CI/CD e integraciones.

Documentación

Servidor Bitbucket Model Context Protocol (MCP)

Un servidor Model Context Protocol (MCP) de alto rendimiento y sin estado, escrito en Rust, que lleva todo el poder de la API REST de Bitbucket Cloud a tus agentes de IA y herramientas de automatización con LLM.

Al conectar Bitbucket Cloud con el estándar MCP, bitbucket-mcp permite que agentes inteligentes (como Claude, Cursor, Copilot o Antigravity) inspeccionen, gestionen y automaticen de forma segura repositorios, pull requests, incidencias y pipelines de CI/CD de manera autónoma.

🚀 Características

Soporte completo de Bitbucket Cloud: Interactúa con Repositorios, Espacios de trabajo, Ramas, Commits, Pull Requests, Incidencias, Pipelines, Despliegues y Webhooks.
Cumplimiento del protocolo MCP: Construido estrictamente según las especificaciones estándar del protocolo MCP 2024-11-05.
Rápido y ligero: Escrito en Rust, utiliza operaciones asíncronas altamente optimizadas y el stack rustls para un rendimiento máximo y una huella mínima.
Seguro por diseño: Arquitectura completamente sin estado. La autenticación se realiza mediante tokens oficiales de la API de Bitbucket que se pasan de forma segura a través del entorno.
Listo para Docker: Hay imágenes oficiales disponibles en el GitHub Container Registry (GHCR) para integraciones instantáneas de tipo plug-and-play.

🏗️ Arquitectura y cómo funciona

bitbucket-mcp utiliza el crate de Rust rmcp para exponer una interfaz JSON-RPC estándar a los clientes de IA. Cuando un agente de IA solicita una acción (como recuperar el diff de un pull request), el servidor traduce esta solicitud a una llamada a la API REST estrictamente tipada hacia api.bitbucket.org.

Validación estricta de esquemas

A diferencia de los servidores más simples basados en Node.js, esta implementación en Rust utiliza schemars para generar esquemas JSON rigurosos y fuertemente tipados para sus herramientas. Esto garantiza compatibilidad con los LLM de IA más estrictos y de nivel empresarial (como los Outputs Estructurados de OpenAI), evitando errores de esquema débilmente tipados durante el descubrimiento de herramientas.

🛠️ Requisitos previos

Credenciales de Bitbucket: Necesitas una cuenta de Bitbucket Cloud y una Contraseña de aplicación / Token de API.
- Crear una contraseña de aplicación con ámbitos como repository:read, pullrequest:read, pullrequest:write, issue:write, etc.
Docker (recomendado) o el toolchain de Rust (si compilas desde el código fuente).

📦 Instalación e inicio rápido

Opción A: Usando Docker (recomendado)

Puedes ejecutar la imagen Docker precompilada directamente. Acepta JSON-RPC a través de stdio.

docker run -i --rm \
  -e BITBUCKET_API_USERNAME="your-atlassian-email@example.com" \
  -e BITBUCKET_API_TOKEN="your-app-password" \
  ghcr.io/ibrahimogod/bitbucket-mcp:latest

Opción B: Compilación local (Cargo)

Si prefieres ejecutarlo de forma nativa sin Docker:

# 1. Clone the repository
git clone https://github.com/Ibrahimogod/bitbucket-mcp.git
cd bitbucket-mcp

# 2. Build the optimized release binary
cargo build --release

# 3. Export credentials and run
export BITBUCKET_API_USERNAME="your-atlassian-email@example.com"
export BITBUCKET_API_TOKEN="your-app-password"
./target/release/bitbucket_stdio

🔌 Integración con clientes de IA

Integración con Cursor

Para configurar Cursor y que inicie automáticamente el servidor MCP de Bitbucket, añade lo siguiente a tu ~/.cursor/mcp.json global o al .cursor/mcp.json a nivel de proyecto:

{
  "mcpServers": {
    "bitbucket-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BITBUCKET_API_USERNAME",
        "-e", "BITBUCKET_API_TOKEN",
        "ghcr.io/ibrahimogod/bitbucket-mcp:latest"
      ],
      "env": {
        "BITBUCKET_API_USERNAME": "<your-email>",
        "BITBUCKET_API_TOKEN": "<your-app-password>"
      }
    }
  }
}

Integración con Claude Desktop

Para la aplicación Claude Desktop, edita tu archivo de configuración (normalmente ubicado en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BITBUCKET_API_USERNAME",
        "-e", "BITBUCKET_API_TOKEN",
        "ghcr.io/ibrahimogod/bitbucket-mcp:latest"
      ],
      "env": {
        "BITBUCKET_API_USERNAME": "<your-email>",
        "BITBUCKET_API_TOKEN": "<your-app-password>"
      }
    }
  }
}

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Asegúrate de que tu código cumpla con el formato estándar de Rust (cargo fmt) y pase todas las pruebas (cargo test).

Si deseas añadir soporte para un nuevo endpoint de Bitbucket Cloud:

Define la estructura de entrada en src/common/bitbucket.rs usando #[derive(JsonSchema, Deserialize)].
Añade la lógica del manejador de la herramienta anotada con #[rmcp::tool(description = "...")].
Asegúrate de añadir pruebas que mapeen el nuevo endpoint.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.