mcp-bitbucket

Servidor MCP (stdio) para Bitbucket Cloud REST API 2.0. Funciona con Cursor: pull requests, pipelines, logs, clone.

Las herramientas siguen el conjunto típico bb_get / bb_post / bb_put / bb_patch / bb_delete / bb_clone.

Requisitos

• Node.js 18+

• Scoped API Token de Atlassian (App Passwords no funcionan)

Token: id.atlassian.com → API tokens.
Ámbitos útiles: lectura de repositorios, pull requests, pipelines y usuario (read:repository:bitbucket, read:pullrequest:bitbucket, read:pipeline:bitbucket, read:user:bitbucket). Para escritura, añade los write:* correspondientes.

Related MCP server: bitbucket-mcp

Instalación

git clone https://github.com/genkis/mcp-bitbucket.git
cd mcp-bitbucket
npm install

Copia .env.example a .env y completa los valores localmente. No hagas commit del archivo .env.

Cursor (~/.cursor/mcp.json)

Guarda el token y el correo solo en la configuración local de Cursor, no en este repositorio.

{
  "mcpServers": {
    "bitbucket": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-bitbucket/index.js"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "you@example.com",
        "ATLASSIAN_API_TOKEN": "your-scoped-api-token",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}

Después del cambio, recarga los servidores MCP en Cursor.

Variables:

Alias: BITBUCKET_USERNAME, BITBUCKET_API_TOKEN.

Herramientas

El prefijo /2.0 se añade automáticamente. La ruta comienza con /, p. ej. /workspaces.

Parámetros comunes: path, opcionalmente queryParams, jq (JMESPath), outputFormat (toon o json). bb_post / bb_put / bb_patch requieren body.

Ejemplos de rutas:

• /workspaces

• /repositories/{workspace}/{repo}/pullrequests/{id}

• /repositories/{workspace}/{repo}/pullrequests/{id}/diff

• /repositories/{workspace}/{repo}/pipelines/?pagelen=50&sort=-created_on

• /repositories/{workspace}/{repo}/pipelines/{uuid}/steps/{stepUuid}/log

El filtro jq conviene aplicarlo siempre en las listas, para no arrastrar todo el JSON al modelo.

Seguridad

• No hagas commit de tokens, .env ni mcp.json con secretos.

• Este servidor solo reenvía solicitudes a api.bitbucket.org con Basic Auth (correo + token).

• Los logs y errores no muestran el token.