Skip to main content
Glama
deenesjakoruzh
aashari

Atlassian Bitbucket MCP Server

by aashari
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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: Atlassian Bitbucket MCP Server

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

  1. Bifurcar el repositorio.

  2. Crea una rama de características ( git checkout -b feature/xyz ).

  3. Confirmar cambios ( git commit -m "Add xyz feature" ).

  4. Empujar a la rama ( git push origin feature/xyz ).

  5. Abrir una solicitud de extracción.

Consulte CONTRIBUTING.md para obtener más detalles.

Licencia

Licencia ISC

Available Tools

6 tools
bb_cloneClone Bitbucket RepositoryA

Clone a Bitbucket repository to your local filesystem using SSH (preferred) or HTTPS.

Provide repoSlug and targetPath (absolute path). Clones into targetPath/repoSlug. SSH keys must be configured; falls back to HTTPS if unavailable.

ParametersJSON Schema
NameRequiredDescriptionDefault
workspaceSlugNoBitbucket workspace slug containing the repository. If not provided, the tool will use your default workspace (either configured via BITBUCKET_DEFAULT_WORKSPACE or the first workspace in your account). Example: "myteam"
repoSlugYesRepository name/slug to clone. This is the short name of the repository. Example: "project-api"
targetPathYesDirectory path where the repository will be cloned. IMPORTANT: Absolute paths are strongly recommended (e.g., "/home/user/projects" or "C:\Users\name\projects"). Relative paths will be resolved relative to the server's working directory, which may not be what you expect. The repository will be cloned into a subdirectory at targetPath/repoSlug. Make sure you have write permissions to this location.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate non-read-only and non-destructive. Description adds behavioral details like default clone directory and fallback mechanism. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with core purpose, no redundancy. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers key points for a simple clone operation. No output schema, but return value is likely a confirmation. Could mention error handling (e.g., if path exists), but overall adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%. Description reinforces targetPath behavior (absolute path suggested, subdirectory creation) and optional workspaceSlug usage, adding practical meaning beyond raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the action 'Clone a Bitbucket repository' and destination 'local filesystem', distinguishing it from sibling CRUD tools (bb_get, bb_post, etc.).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear guidance on required parameters (repoSlug, targetPath), path behavior (clones into targetPath/repoSlug), and authentication precedence (SSH preferred, falls back to HTTPS). No explicit when-not-to-use, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bb_deleteBitbucket DELETE RequestA
DestructiveIdempotent

Delete Bitbucket resources. Returns TOON format by default.

Output format: TOON (default) or JSON (outputFormat: "json")

Common operations:

  1. Delete branch: /repositories/{workspace}/{repo}/refs/branches/{branch_name}

  2. Delete PR comment: /repositories/{workspace}/{repo}/pullrequests/{pr_id}/comments/{comment_id}

  3. Decline PR: /repositories/{workspace}/{repo}/pullrequests/{id}/decline

  4. Remove PR approval: /repositories/{workspace}/{repo}/pullrequests/{id}/approve

  5. Delete repository: /repositories/{workspace}/{repo} (caution: irreversible)

Note: Most DELETE endpoints return 204 No Content on success.

The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}"
queryParamsNoOptional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"}
jqNoJMESPath expression to filter/transform the response. IMPORTANT: Always use this to extract only needed fields and reduce token costs. Examples: "values[*].{name: name, slug: slug}" (extract specific fields), "values[0]" (first result), "values[*].name" (names only). See https://jmespath.org
outputFormatNoOutput format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax.

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds value beyond annotations by noting the default TOON output format, typical 204 No Content response, and the irreversible nature of deleting a repository. These details help the agent understand behavior without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections, front-loaded purpose, and relevant examples. It is concise without being overly terse, though minor repetition ('Returns TOON format by default') could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (4 parameters, no output schema), the description adequately covers output format, common operations, and parameter usage. It references an external API documentation link for completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the description enriches parameters with practical examples (e.g., queryParams, jq expressions, outputFormat enum values) that go beyond the schema's basic descriptions, aiding correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Delete Bitbucket resources' and lists specific common operations (delete branch, PR comment, decline PR, etc.), which distinguishes it from sibling tools (bb_get, bb_post, etc.) that have different HTTP methods.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While the description provides a list of common operations and a caution about irreversibility for deleting repositories, it lacks explicit guidance on when to use this tool versus alternatives beyond the implied HTTP method differences.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bb_getBitbucket GET RequestA
Read-onlyIdempotent

Read any Bitbucket data. Returns TOON format by default (30-60% fewer tokens than JSON).

IMPORTANT - Cost Optimization:

  • ALWAYS use jq param to filter response fields. Unfiltered responses are very expensive!

  • Use pagelen query param to restrict result count (e.g., pagelen: "5")

  • If unsure about available fields, first fetch ONE item with pagelen: "1" and NO jq filter to explore the schema, then use jq in subsequent calls

Schema Discovery Pattern:

  1. First call: path: "/workspaces", queryParams: {"pagelen": "1"} (no jq) - explore available fields

  2. Then use: jq: "values[*].{slug: slug, name: name, uuid: uuid}" - extract only what you need

Output format: TOON (default, token-efficient) or JSON (outputFormat: "json")

Common paths:

  • /workspaces - list workspaces

  • /repositories/{workspace} - list repos in workspace

  • /repositories/{workspace}/{repo} - get repo details

  • /repositories/{workspace}/{repo}/pullrequests - list PRs

  • /repositories/{workspace}/{repo}/pullrequests/{id} - get PR details

  • /repositories/{workspace}/{repo}/pullrequests/{id}/comments - list PR comments

  • /repositories/{workspace}/{repo}/pullrequests/{id}/diff - get PR diff

  • /repositories/{workspace}/{repo}/refs/branches - list branches

  • /repositories/{workspace}/{repo}/commits - list commits

  • /repositories/{workspace}/{repo}/src/{commit}/{filepath} - get file content

  • /repositories/{workspace}/{repo}/diff/{source}..{destination} - compare branches/commits

Query params: pagelen (page size), page (page number), q (filter), sort (order), fields (sparse response)

Example filters (q param): state="OPEN", source.branch.name="feature", title~"bug"

JQ examples: values[*].slug, values[0], values[*].{name: name, uuid: uuid}

The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}"
queryParamsNoOptional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"}
jqNoJMESPath expression to filter/transform the response. IMPORTANT: Always use this to extract only needed fields and reduce token costs. Examples: "values[*].{name: name, slug: slug}" (extract specific fields), "values[0]" (first result), "values[*].name" (names only). See https://jmespath.org
outputFormatNoOutput format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax.

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true. Description adds value by detailing default TOON format (token-efficient), automatic /2.0 prefix, and schema discovery pattern. No contradictions. Could mention pagination limits or error responses but still robust.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections (Important, Schema Discovery, Common paths, etc.) and front-loaded with key guidance. Length is justified by the complexity of the Bitbucket API, but some redundancy in examples could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read tool with no output schema, the description fully compensates by explaining output format, common paths, filters, and a discovery pattern. Covers all practical aspects an agent needs to invoke the tool correctly against Bitbucket API.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all 4 parameters. The description adds extensive examples (e.g., query param examples, jq expressions, outputFormat enum), providing meaning beyond the schema. More than baseline 3 due to rich contextualization.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Read any Bitbucket data' and emphasizes read-only nature with a list of common paths. It distinguishes from sibling write tools (bb_delete, bb_post, etc.) by specifying reading operations only.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit cost optimization guidelines: always use jq filter, use pagelen to limit results, and a schema discovery pattern. Also gives common paths and example filters, leaving no doubt when to use this read tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bb_patchBitbucket PATCH RequestA

Partially update Bitbucket resources. Returns TOON format by default.

IMPORTANT - Cost Optimization: Use jq param to filter response fields.

Output format: TOON (default) or JSON (outputFormat: "json")

Common operations:

  1. Update PR title/description: /repositories/{workspace}/{repo}/pullrequests/{id} body: {"title": "New title", "description": "Updated description"}

  2. Update PR reviewers: /repositories/{workspace}/{repo}/pullrequests/{id} body: {"reviewers": [{"uuid": "{user-uuid}"}]}

  3. Update repository properties: /repositories/{workspace}/{repo} body: {"description": "New description"}

  4. Update comment: /repositories/{workspace}/{repo}/pullrequests/{pr_id}/comments/{comment_id} body: {"content": {"raw": "Updated comment"}}

The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}"
queryParamsNoOptional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"}
jqNoJMESPath expression to filter/transform the response. IMPORTANT: Always use this to extract only needed fields and reduce token costs. Examples: "values[*].{name: name, slug: slug}" (extract specific fields), "values[0]" (first result), "values[*].name" (names only). See https://jmespath.org
outputFormatNoOutput format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax.
bodyYesRequest body as a JSON object. Structure depends on the endpoint. Example for PR: {"title": "My PR", "source": {"branch": {"name": "feature"}}}

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds valuable context: default TOON output format, cost optimization via jq param, and examples of common operations. It does not disclose error behavior or permission requirements, but the added details are useful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose statement, cost optimization note, output format info, and bulleted examples. It is moderately concise but could be trimmed slightly without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters with 100% schema coverage and no output schema, the description covers essential usage patterns and output format. It lacks details on error handling or rate limits, but provides sufficient context for typical PATCH operations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description enhances understanding by providing concrete examples for each parameter (e.g., path examples, queryParams usage, jq expressions, body structures for PR updates). This goes beyond schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Partially update Bitbucket resources' and provides specific examples of common operations (e.g., updating PR title, reviewers, repository properties). The verb 'patch' and examples distinguish it effectively from siblings (clone, delete, get, post, put).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for partial updates via examples and contrasts with full updates (PUT) implicitly. However, it lacks explicit guidance on when to use this tool versus alternatives like bb_put, and does not mention when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bb_postBitbucket POST RequestA

Create Bitbucket resources. Returns TOON format by default (token-efficient).

IMPORTANT - Cost Optimization:

  • Use jq param to extract only needed fields from response (e.g., jq: "{id: id, title: title}")

  • Unfiltered responses include all metadata and are expensive!

Output format: TOON (default) or JSON (outputFormat: "json")

Common operations:

  1. Create PR: /repositories/{workspace}/{repo}/pullrequests body: {"title": "...", "source": {"branch": {"name": "feature"}}, "destination": {"branch": {"name": "main"}}}

  2. Add PR comment: /repositories/{workspace}/{repo}/pullrequests/{id}/comments body: {"content": {"raw": "Comment text"}}

  3. Approve PR: /repositories/{workspace}/{repo}/pullrequests/{id}/approve body: {}

  4. Request changes: /repositories/{workspace}/{repo}/pullrequests/{id}/request-changes body: {}

  5. Merge PR: /repositories/{workspace}/{repo}/pullrequests/{id}/merge body: {"merge_strategy": "squash"} (strategies: merge_commit, squash, fast_forward)

The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}"
queryParamsNoOptional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"}
jqNoJMESPath expression to filter/transform the response. IMPORTANT: Always use this to extract only needed fields and reduce token costs. Examples: "values[*].{name: name, slug: slug}" (extract specific fields), "values[0]" (first result), "values[*].name" (names only). See https://jmespath.org
outputFormatNoOutput format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax.
bodyYesRequest body as a JSON object. Structure depends on the endpoint. Example for PR: {"title": "My PR", "source": {"branch": {"name": "feature"}}}

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description fully discloses behavioral traits: default TOON format, cost optimization via jq, auto-added /2.0 prefix, and output format options. It aligns with annotations (not read-only, not destructive, not idempotent, open-world hint) and adds significant context beyond structured data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose statement, important cost optimization note, and a list of common operations. It is slightly verbose but front-loaded with key information, making it efficient for an AI agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 5 parameters, nested objects, and no output schema, the description is remarkably complete: it covers output formats, cost optimization, common endpoint patterns, and links to the full API reference. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema description coverage, the description adds substantial meaning: detailed path examples, jq usage with examples, outputFormat benefits, body structure examples for common endpoints. This greatly aids parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create Bitbucket resources' and provides multiple specific endpoint examples (create PR, add comment, approve, etc.), distinguishing it from sibling tools that handle other HTTP methods.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool (creating resources) and provides common operations with endpoint and body examples. It lacks explicit when-not-to-use or alternative tool references, but the context signals and sibling tool list imply the usage boundaries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

bb_putBitbucket PUT RequestA
Idempotent

Replace Bitbucket resources (full update). Returns TOON format by default.

IMPORTANT - Cost Optimization:

  • Use jq param to extract only needed fields from response

  • Example: jq: "{uuid: uuid, name: name}"

Output format: TOON (default) or JSON (outputFormat: "json")

Common operations:

  1. Update repository: /repositories/{workspace}/{repo} body: {"description": "...", "is_private": true, "has_issues": true}

  2. Create/update file: /repositories/{workspace}/{repo}/src Note: Use multipart form data for file uploads (complex - prefer PATCH for metadata)

  3. Update branch restriction: /repositories/{workspace}/{repo}/branch-restrictions/{id} body: {"kind": "push", "pattern": "main", "users": [{"uuid": "..."}]}

The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}"
queryParamsNoOptional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"}
jqNoJMESPath expression to filter/transform the response. IMPORTANT: Always use this to extract only needed fields and reduce token costs. Examples: "values[*].{name: name, slug: slug}" (extract specific fields), "values[0]" (first result), "values[*].name" (names only). See https://jmespath.org
outputFormatNoOutput format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax.
bodyYesRequest body as a JSON object. Structure depends on the endpoint. Example for PR: {"title": "My PR", "source": {"branch": {"name": "feature"}}}

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations, describes default TOON output format, automatic /2.0 prefix, and cost optimization behavior. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear sections, but slightly verbose. Front-loaded with purpose and important notes. Could trim some redundant phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers main usage patterns and cost optimization. Lacks explicit error handling or response structure details, but examples and reference link partially compensate. Good for a mutation tool with no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All parameters have schema descriptions, and the tool description adds context: path format, jq usage examples, outputFormat enum explanation, and body structure examples. Significantly enhances schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it is for 'Replace Bitbucket resources (full update).' Distinguishes from sibling tools (bb_patch for partial updates) and provides common operation examples.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly recommends using PATCH for metadata when updating files, provides cost optimization tips (jq param), and lists specific common operations with endpoints and request bodies. Clearly guides when and how to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 26 tool updatesv1.43.1
    • Removedbb_add_branch
    • Removedbb_add_pr
    • Removedbb_add_pr_comment
    • Removedbb_approve_pr
    • Addedbb_clone
    • Removedbb_clone_repo
    • Addedbb_delete
    • Removedbb_diff_branches
    • Removedbb_diff_commits
    • Addedbb_get
    • Removedbb_get_commit_history
    • Removedbb_get_file
    • Removedbb_get_pr
    • Removedbb_get_repo
    • Removedbb_get_workspace
    • Removedbb_list_branches
    • Removedbb_ls_pr_comments
    • Removedbb_ls_prs
    • Removedbb_ls_repos
    • Removedbb_ls_workspaces
    • Addedbb_patch
    • Addedbb_post
    • Addedbb_put
    • Removedbb_reject_pr
    • Removedbb_search
    • Removedbb_update_pr
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.4/5.0

Scored across 6 tools

Disambiguation5/5

Each tool corresponds to a distinct HTTP method (or clone operation) with clear purposes: clone for local cloning, delete for deletions, get for reads, patch for partial updates, post for creations, and put for full replacements. There is no overlap.

Naming Consistency5/5

All tools follow a consistent 'bb_<verb>' pattern using HTTP method names (clone, delete, get, patch, post, put). The naming is predictable and uniform.

Tool Count5/5

With 6 tools, the server provides a concise CRUD+L (clone) interface for Bitbucket. This is well-scoped for a MCP server; each tool has a clear role without unnecessary bloat.

Completeness4/5

The tools cover all standard CRUD operations plus cloning. However, specific workflows like merging or approving PRs are handled via generic post/put, which may require agents to construct endpoint paths. A dedicated tool for common composite operations could improve completeness slightly.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Bitbucket MCP Server

    bobmaertz
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI assistants to interact with Bitbucket Cloud repositories, allowing users to manage pull requests, comments, tasks, and branches through natural language commands.
    4,764 npm
    1
    MIT

  • bitbucket-mcp

    yunusemregul
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to programmatically manage Bitbucket Cloud resources, including pull requests, repositories, and branches, automating code review workflows.
    11 npm
    MIT

  • bitbucket-mcp

    lawp09
    A
    license
    A
    quality
    A
    maintenance
    Enables AI assistants to manage Bitbucket Cloud repositories, pull requests, pipelines, and code review tasks through natural language.
    74
    1,017 PyPI
    3
    MIT

Appeared in Searches