Skip to main content
Glama
deenesjakoruzh
aashari

Atlassian Bitbucket MCP Server

by aashari
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Сервер Atlassian Bitbucket MCP

Сервер Node.js/TypeScript Model Context Protocol (MCP) для Atlassian Bitbucket Cloud. Позволяет системам ИИ (например, LLM, таким как Claude или Cursor AI) безопасно взаимодействовать с вашими репозиториями, запросами на извлечение, рабочими пространствами и кодом в режиме реального времени.

Версия НПМ Статус сборки

Зачем использовать этот сервер?

  • Минимальный ввод, максимальный вывод : простые идентификаторы предоставляют исчерпывающую информацию без необходимости дополнительных флагов.

  • Расширенная визуализация кода : получите подробную информацию об изменениях кода с помощью статистики файлов, представлений различий и интеллектуального контекста.

  • Безопасная локальная аутентификация : работайте локально с вашими учетными данными, никогда не храня токены на удаленных серверах.

  • Интуитивно понятные ответы Markdown : хорошо структурированное, единообразное форматирование Markdown для всех выходных данных.

  • Полная интеграция с Bitbucket : доступ к рабочим областям, репозиториям, запросам на извлечение, комментариям, поиску кода и многому другому.

Related MCP server: Atlassian Bitbucket MCP Server

Что такое МКП?

Model Context Protocol (MCP) — открытый стандарт для безопасного подключения систем ИИ к внешним инструментам и источникам данных. Этот сервер реализует MCP для Bitbucket Cloud, позволяя помощникам ИИ взаимодействовать с вашими данными Bitbucket программным способом.

Предпосылки

Настраивать

Шаг 1: Аутентификация

Выберите один из следующих методов аутентификации:

Вариант A: Пароль приложения Bitbucket (рекомендуется)

Сгенерируйте один из Bitbucket App Passwords . Минимальные разрешения:

  • Рабочие пространства: Читать

  • Репозитории: Читать

  • Запросы на извлечение: Читать

Вы также можете задать BITBUCKET_DEFAULT_WORKSPACE , чтобы указать рабочее пространство по умолчанию, если оно не указано явно.

Вариант B: токен API Atlassian

Сгенерируйте его с помощью токенов API Atlassian .

Примечание: настоятельно рекомендуется использовать пароли приложений Bitbucket, поскольку они обеспечивают более детальные разрешения, специфичные для Bitbucket.

Шаг 2: Настройте учетные данные

Вариант A: Файл конфигурации MCP (рекомендуется)

Отредактируйте или создайте ~/.mcp/configs.json :

Использование пароля приложения Bitbucket:

{
	"bitbucket": {
		"environments": {
			"ATLASSIAN_BITBUCKET_USERNAME": "<your_username>",
			"ATLASSIAN_BITBUCKET_APP_PASSWORD": "<your_app_password>"
		}
	}
}

Использование токена API Atlassian:

{
	"bitbucket": {
		"environments": {
			"ATLASSIAN_SITE_NAME": "bitbucket",
			"ATLASSIAN_USER_EMAIL": "<your_email>",
			"ATLASSIAN_API_TOKEN": "<your_api_token>"
		}
	}
}

Вариант B: Переменные среды

export ATLASSIAN_BITBUCKET_USERNAME="<your_username>"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="<your_app_password>"

Шаг 3: Установка и запуск

Быстрый старт с npx

npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces

Глобальная установка

npm install -g @aashari/mcp-server-atlassian-bitbucket
mcp-atlassian-bitbucket ls-workspaces

Шаг 4: Подключитесь к AI Assistant

Настройте MCP-совместимый клиент (например, Claude, Cursor AI):

{
	"mcpServers": {
		"bitbucket": {
			"command": "npx",
			"args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"]
		}
	}
}

Инструменты МКП

Инструменты MCP используют имена snake_case , параметры camelCase и возвращают ответы в формате Markdown.

  • bb_ls_workspaces : Список доступных рабочих пространств ( query : str opt). Использование: Просмотр доступных рабочих пространств.

  • bb_get_workspace : Получает сведения о рабочей области ( workspaceSlug : str req). Использование: Просмотр информации о рабочей области.

  • bb_ls_repos : Список репозиториев ( workspaceSlug : str opt, projectKey : str opt, query : str opt, role : str opt). Использование: Поиск репозиториев.

  • bb_get_repo : Получает данные репозитория ( workspaceSlug : str req, repoSlug : str req). Использование: Доступ к информации о репозитории.

  • bb_search : Поиск содержимого Bitbucket ( workspaceSlug : str req, query : str req, scope : str opt, language : str opt, extension : str opt). Использование: Поиск кода или PR.

  • bb_ls_prs : Список запросов на извлечение ( workspaceSlug : str req, repoSlug : str req, state : str opt). Использование: Просмотр открытых или объединенных PR.

  • bb_get_pr : Получает сведения о PR ( workspaceSlug : str req, repoSlug : str req, prId : str req). Использование: Просмотр сведений о PR с различиями.

  • bb_ls_pr_comments : Список комментариев PR ( workspaceSlug : str req, repoSlug : str req, prId : str req). Использование: Просмотр обсуждений PR.

  • bb_add_pr_comment : Добавляет комментарий к PR ( workspaceSlug : str req, repoSlug : str req, prId : str req, content : str req, inline : obj opt). Использование: Добавить отзыв к PR.

  • bb_add_pr : Создает PR ( workspaceSlug : str req, repoSlug : str req, title : str req, sourceBranch : str req, targetBranch : str opt). Использование: Создание новых PR.

  • bb_add_branch : Создает ветку ( workspaceSlug : str req, repoSlug : str req, newBranchName : str req, sourceBranchOrCommit : str opt). Использование: Создать ветку функции.

  • bb_clone_repo : Клонирует репозиторий ( workspaceSlug : str req, repoSlug : str req, targetPath : str req). Использование: Клонировать код локально.

  • bb_get_commit_history : Получает историю коммитов ( workspaceSlug : str req, repoSlug : str req, revision : str opt, path : str opt). Использование: Просмотр истории кода.

  • bb_get_file : Получает содержимое файла ( workspaceSlug : str req, repoSlug : str req, filePath : str req, revision : str opt). Использование: Просмотр определенного файла.

  • bb_diff_branches : Показывает разницу между ветвями ( workspaceSlug : str req, repoSlug : str req, sourceBranch : str req, targetBranch : str req). Использование: Сравнение ветвей.

  • bb_diff_commits : Показывает разницу между коммитами ( workspaceSlug : str req, repoSlug : str req, sourceCommit : str req, targetCommit : str req). Использование: Сравнение коммитов.

  • bb_list_branches : Список ветвей ( workspaceSlug : str req, repoSlug : str req, query : str opt, sort : str opt). Использование: Просмотр всех ветвей.

bb_ls_workspaces

Список всех рабочих пространств:

{}

Поиск рабочих пространств:

{ "query": "devteam" }

bb_get_workspace

Получить сведения о рабочем пространстве:

{ "workspaceSlug": "acme-corp" }

bb_ls_repos

Список репозиториев в рабочей области:

{ "workspaceSlug": "acme-corp", "projectKey": "PROJ" }

Список репозиториев с использованием рабочего пространства по умолчанию:

{ "projectKey": "PROJ" }

bb_get_repo

Получить данные репозитория:

{ "workspaceSlug": "acme-corp", "repoSlug": "backend-api" }

bb_search

Поисковый код:

{
	"workspaceSlug": "acme-corp",
	"query": "Logger",
	"scope": "code",
	"language": "typescript"
}

bb_ls_prs

Список открытых PR:

{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "state": "OPEN" }

bb_get_pr

Получить PR-подробности:

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

bb_ls_pr_comments

Список PR-комментариев:

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

bb_add_pr_comment

Добавить общий комментарий:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"prId": "42",
	"content": "Looks good."
}

Добавить встроенный комментарий:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"prId": "42",
	"content": "Consider refactoring.",
	"inline": { "path": "src/utils.js", "line": 42 }
}

bb_add_pr

Создать запрос на извлечение:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"title": "Add login screen",
	"sourceBranch": "feature/login"
}

bb_add_branch

Создать новую ветку:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"newBranchName": "feature/new-feature",
	"sourceBranchOrCommit": "main"
}

bb_clone_repo

Клонировать репозиторий:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api",
	"targetPath": "/Users/me/projects"
}

bb_get_commit_history

Просмотреть историю коммитов:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api"
}

Отфильтрованная история коммитов:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api",
	"revision": "develop",
	"path": "src/main/java/com/acme/service/UserService.java"
}

bb_get_file

Получить содержимое файла:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api",
	"filePath": "src/main/java/com/acme/service/Application.java",
	"revision": "main"
}

bb_diff_branches

Сравнить ветки:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "web-app",
	"sourceBranch": "develop",
	"targetBranch": "main"
}

bb_diff_commits

Сравнить коммиты:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "web-app",
	"sourceCommit": "a1b2c3d",
	"targetCommit": "e4f5g6h"
}

bb_list_branches

Список всех филиалов:

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

Отфильтрованные ветки:

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"query": "feature/",
	"sort": "name"
}

Команды CLI

Команды CLI используют kebab-case . Запустите --help для получения подробной информации (например, mcp-atlassian-bitbucket ls-workspaces --help ).

  • ls-workspaces : Выводит список рабочих пространств ( --query ). Пример: mcp-atlassian-bitbucket ls-workspaces .

  • get-workspace : Получает сведения о рабочей области ( --workspace-slug ). Пример: mcp-atlassian-bitbucket get-workspace --workspace-slug acme-corp .

  • ls-repos : Выводит список репозиториев ( --workspace-slug , --project-key , --query ). Пример: mcp-atlassian-bitbucket ls-repos --workspace-slug acme-corp .

  • get-repo : Получает сведения о репозитории ( --workspace-slug , --repo-slug ). Пример: mcp-atlassian-bitbucket get-repo --workspace-slug acme-corp --repo-slug backend-api .

  • search : Поиск кода ( --workspace-slug , --query , --scope , --language ). Пример: mcp-atlassian-bitbucket search --workspace-slug acme-corp --query "auth" .

  • ls-prs : выводит список PR ( --workspace-slug , --repo-slug , --state ). Пример: mcp-atlassian-bitbucket ls-prs --workspace-slug acme-corp --repo-slug backend-api .

  • get-pr : Получает сведения о PR ( --workspace-slug , --repo-slug , --pr-id ). Пример: mcp-atlassian-bitbucket get-pr --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 .

  • ls-pr-comments : выводит список комментариев PR ( --workspace-slug , --repo-slug , --pr-id ). Пример: mcp-atlassian-bitbucket ls-pr-comments --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 .

  • add-pr-comment : Добавляет комментарий PR ( --workspace-slug , --repo-slug , --pr-id , --content ). Пример: mcp-atlassian-bitbucket add-pr-comment --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 --content "Looks good" .

  • add-pr : Создает PR ( --workspace-slug , --repo-slug , --title , --source-branch ). Пример: mcp-atlassian-bitbucket add-pr --workspace-slug acme-corp --repo-slug backend-api --title "New feature" --source-branch feature/login .

  • get-file : Получает содержимое файла ( --workspace-slug , --repo-slug , --file-path ). Пример: mcp-atlassian-bitbucket get-file --workspace-slug acme-corp --repo-slug backend-api --file-path src/main.js .

  • add-branch : Создает ветку ( --workspace-slug , --repo-slug , --new-branch-name ). Пример: mcp-atlassian-bitbucket add-branch --workspace-slug acme-corp --repo-slug backend-api --new-branch-name feature/new .

Список и просмотр рабочих пространств/репозиториев

# 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

Работа с запросами на извлечение

# 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

Код и коммиты

# 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

Управление филиалом

# 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

Формат ответа

Все ответы отформатированы в формате Markdown, включая:

  • Заголовок : Выполненная операция или просмотренный объект.

  • Контекст : рабочая область, репозиторий, запрос на извлечение или информация о ветке.

  • Контент : основные данные, такие как содержимое файла, сведения о PR или результаты поиска.

  • Метаданные : временные метки, авторы и статистика.

  • Различия : изменения кода с подсветкой синтаксиса для различий между ветками/коммитами.

Подробности репозитория

# 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*

Обзор запроса на извлечение

# 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*

Разработка

# 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

Внося вклад

Вклады приветствуются! Пожалуйста:

  1. Создайте форк репозитория.

  2. Создайте ветку функций ( git checkout -b feature/xyz ).

  3. Зафиксируйте изменения ( git commit -m "Add xyz feature" ).

  4. Отправьте изменения в ветку ( git push origin feature/xyz ).

  5. Откройте запрос на извлечение.

Подробности смотрите на сайте CONTRIBUTING.md .

Лицензия

Лицензия 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