Bitbucket MCP Server

Сервер MCP (Model Context Protocol), предоставляющий инструменты для взаимодействия с API Bitbucket, поддерживающий как Bitbucket Cloud, так и Bitbucket Server.

Возможности

Доступные инструменты (всего 29)

Основные функции PR (pr_core)

• get_pull_request - Полная информация о PR, включая комментарии, изменения файлов и информацию о слиянии

• list_pull_requests - Список PR с фильтрами (состояние, автор, пагинация)

• create_pull_request - Создание новых pull-запросов

• update_pull_request - Обновление деталей PR (заголовок, описание, рецензенты, целевая ветка)

• merge_pull_request - Слияние pull-запросов с использованием различных стратегий

• decline_pull_request - Отклонение pull-запроса

Комментарии к PR (pr_comments)

• add_comment - Добавление общих, встроенных (inline), потоковых комментариев или предложений к PR

• delete_comment - Удаление комментария из pull-запроса

Проверка кода (pr_review)

• get_pull_request_diff - Структурированный построчный diff с типами ADDED/REMOVED/CONTEXT

• set_pr_approval - Одобрить (approved: true) или отозвать одобрение (approved: false) PR

• set_review_status - Запросить изменения (request_changes: true) или удалить запрос (false)

Задачи PR — только для Bitbucket Server (pr_tasks)

• list_pr_tasks - Список всех задач в pull-запросе

• create_pr_task - Создание новой задачи в pull-запросе

• update_pr_task - Обновление текста существующей задачи

• set_pr_task_status - Отметить задачу как выполненную (done: true) или открыть её снова (done: false)

• delete_pr_task - Удаление задачи из pull-запроса

• convert_pr_item - Преобразование комментария в задачу (direction: "to_task") или обратно ("to_comment")

Коммиты (commits)

• list_pr_commits - Список всех коммитов в pull-запросе

• list_branch_commits - Список коммитов в ветке с фильтрами по дате/автору/сообщению

• get_commit_detail - Получение структурированного diff для конкретного коммита по SHA

Ветки (branches)

• list_branches - Список веток с фильтрацией и пагинацией

• get_branch - Подробная информация о ветке, включая связанные PR и статистику

• delete_branch - Удаление ветки

Файлы (files)

• list_directory_content - Список файлов и директорий по пути в репозитории

• get_file_content - Получение содержимого файла с умным усечением для больших файлов

• search_files - Поиск файлов по glob-шаблону (регистронезависимый, как Ctrl+P в VS Code)

Поиск — только для Bitbucket Server (search)

• search_code - Поиск кода по репозиториям

• search_repositories - Поиск репозиториев по имени или описанию

Обнаружение (discovery)

• list_projects - Список всех доступных проектов/рабочих областей Bitbucket

• list_repositories - Список репозиториев в проекте или во всех доступных проектах

Оптимизация токенов

v2.0.0 представляет значительную экономию токенов при каждом запросе к LLM:

Bitbucket Cloud автоматически скрывает 10 инструментов, доступных только на сервере, без необходимости настройки.

BITBUCKET_TOOL_GROUPS позволяет открыть только те группы, которые актуальны для вашего рабочего процесса — см. Фильтрация групп инструментов ниже.

Related MCP server: MCP Server

Установка

Использование npx (рекомендуется)

Самый простой способ использовать этот MCP-сервер — напрямую через npx:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Для Bitbucket Server:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

Из исходного кода

1. Клонируйте или скачайте этот репозиторий

2. Установите зависимости:

   npm install

3. Соберите TypeScript-код:

   npm run build

Настройка аутентификации

Этот сервер использует пароли приложений (App Passwords) Bitbucket для аутентификации.

Создание пароля приложения

1. Войдите в свою учетную запись Bitbucket

2. Перейдите по адресу: https://bitbucket.org/account/settings/app-passwords/

3. Нажмите "Create app password"

4. Дайте ему описательное имя (например, "MCP Server")

5. Выберите следующие разрешения:

   • Account: Read

   • Repositories: Read, Write

   • Pull requests: Read, Write

6. Нажмите "Create"

7. Важно: Скопируйте сгенерированный пароль сразу (вы не сможете увидеть его снова!)

Запуск скрипта настройки

node scripts/setup-auth.js

Это поможет вам пройти процесс настройки аутентификации.

Конфигурация

Добавьте сервер в ваш файл настроек MCP (обычно находится по адресу ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Замените:

• /absolute/path/to/bitbucket-mcp-server на фактический путь к этой директории

• your-username на ваше имя пользователя Bitbucket (не email)

• your-app-password на пароль приложения, который вы создали

Для Bitbucket Server используйте:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

Важно для пользователей Bitbucket Server:

• Используйте ваш полный адрес электронной почты в качестве имени пользователя (например, "john.doe@company.com")

• Это необходимо для корректной работы действий одобрения/проверки

Фильтрация групп инструментов

Уменьшите количество инструментов, отправляемых в LLM при каждом запросе, установив BITBUCKET_TOOL_GROUPS в виде списка имен групп, разделенных запятыми. Будут доступны только инструменты из указанных групп.

Доступные группы

Примеры пресетов

Рабочий процесс проверки PR (~2,100 токенов):

"env": {
  "BITBUCKET_TOOL_GROUPS": "pr_core,pr_review,files"
}

Полное управление PR (~3,500 токенов):

"env": {
  "BITBUCKET_TOOL_GROUPS": "pr_core,pr_comments,pr_review,pr_tasks"
}

Только исследование кода (~1,400 токенов):

"env": {
  "BITBUCKET_TOOL_GROUPS": "files,search,discovery"
}

Если BITBUCKET_TOOL_GROUPS не задан, доступны все применимые инструменты (поведение по умолчанию). У пользователей Bitbucket Cloud инструменты, доступные только на сервере, всегда скрыты автоматически, независимо от этой настройки.

Использование

После настройки вы можете использовать доступные инструменты:

Получение Pull Request

{
  "tool": "get_pull_request",
  "arguments": {
    "workspace": "PROJ",  // Required - your project key
    "repository": "my-repo",
    "pull_request_id": 123
  }
}

Возвращает подробную информацию о pull-запросе, включая:

• Заголовок и описание

• Автора и рецензентов

• Исходную и целевую ветки

• Статус одобрения

• Ссылки на веб-интерфейс и diff

• Детали коммита слияния (когда PR слит):

  • merge_commit_hash: Хэш коммита слияния

  • merged_by: Кто выполнил слияние

  • merged_at: Когда произошло слияние

  • merge_commit_message: Сообщение коммита слияния

• Активные комментарии с вложенными ответами (нерешенные комментарии, требующие внимания):

  • active_comments: Массив активных комментариев (до 20 самых последних комментариев верхнего уровня)

    • Текст комментария и автор

    • Дата создания

    • Является ли это встроенным комментарием (с путем к файлу и номером строки)

    • Вложенные ответы (для Bitbucket Server):

      • replies: Массив ответов с той же структурой

      • Ответы могут быть вложены на несколько уровней

    • Ссылка на родителя (для Bitbucket Cloud):

      • parent_id: ID родительского комментария для ответов

  • active_comment_count: Общее количество нерешенных комментариев (включая вложенные ответы)

  • total_comment_count: Общее количество всех комментариев (включая решенные и ответы)

• Изменения файлов:

  • file_changes: Массив всех файлов, измененных в PR

    • Путь к файлу

    • Статус (добавлен, изменен, удален или переименован)

    • Старый путь (для переименованных файлов)

  • file_changes_summary: Сводная статистика

    • Общее количество измененных файлов

• И многое другое...

Поиск кода

Поиск кода в репозиториях Bitbucket (в настоящее время поддерживается только для Bitbucket Server):

// Search in a specific repository
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "search_query": "TODO",
    "limit": 50
  }
}

// Search across all repositories in a workspace
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "search_query": "deprecated",
    "file_pattern": "*.java",  // Optional: filter by file pattern
    "limit": 100
  }
}

// Search with file pattern filtering
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "repository": "frontend-app",
    "search_query": "useState",
    "file_pattern": "*.tsx",  // Only search in .tsx files
    "start": 0,
    "limit": 25
  }
}

Возвращает результаты поиска с:

• Путем к файлу и именем

• Информацией о репозитории и проекте

• Совпадающими строками с:

  • Номером строки

  • Полным содержимым строки

  • Выделенными сегментами, показывающими точные совпадения

• Информацией о пагинации

Пример ответа:

{
  "message": "Code search completed successfully",
  "workspace": "PROJ",
  "repository": "my-repo",
  "search_query": "TODO",
  "results": [
    {
      "file_path": "src/utils/helper.js",
      "file_name": "helper.js",
      "repository": "my-repo",
      "project": "PROJ",
      "matches": [
        {
          "line_number": 42,
          "line_content": "    // TODO: Implement error handling",
          "highlighted_segments": [
            { "text": "    // ", "is_match": false },
            { "text": "TODO", "is_match": true },
            { "text": ": Implement error handling", "is_match": false }
          ]
        }
      ]
    }
  ],
  "total_count": 15,
  "start": 0,
  "limit": 50,
  "has_more": false
}

Примечание: Этот инструмент в настоящее время работает только с Bitbucket Server. Поддержка Bitbucket Cloud запланирована в будущем релизе.

Список Pull Requests

{
  "tool": "list_pull_requests",
  "arguments": {
    "workspace": "PROJ",  // Required - your project key
    "repository": "my-repo",
    "state": "OPEN",  // Optional: OPEN, MERGED, DECLINED, ALL (default: OPEN)
    "author": "username",  // Optional: filter by author (see note below)
    "limit": 25,  // Optional: max results per page (default: 25)
    "start": 0  // Optional: pagination start index (default: 0)
  }
}

Возвращает список pull-запросов с пагинацией, включая:

• Массив pull-запросов с теми же деталями, что и в get_pull_request

• Общее количество соответствующих PR

• Информацию о пагинации (has_more, next_start)

Примечание по фильтру автора:

• Для Bitbucket Cloud: Используйте имя пользователя (например, "johndoe")

• Для Bitbucket Server: Используйте полный адрес электронной почты (например, "john.doe@company.com")

Создание Pull Request

{
  "tool": "create_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "title": "Add new feature",
    "source_branch": "feature/new-feature",
    "destination_branch": "main",
    "description": "This PR adds a new feature...",  // Optional
    "reviewers": ["john.doe", "jane.smith"],  // Optional
    "close_source_branch": true  // Optional (default: false)
  }
}

Обновление Pull Request

{
  "tool": "update_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "title": "Updated title",  // Optional
    "description": "Updated description",  // Optional
    "destination_branch": "develop",  // Optional
    "reviewers": ["new.reviewer"]  // Optional - see note below
  }
}

Важное примечание по рецензентам:

• При обновлении PR без указания параметра reviewers, существующие рецензенты и их статус одобрения сохраняются

• При предоставлении параметра reviewers:

  • Список рецензентов заменяется новым списком

  • Для рецензентов, которые уже есть в PR, их статус одобрения сохраняется

  • Новые рецензенты добавляются без статуса одобрения

• Это предотвращает случайное удаление рецензентов, когда вы хотите обновить только описание или заголовок PR

Добавление комментария

Добавьте комментарий к pull-запросу, либо как общий комментарий, либо встроенный в конкретный код:

// General comment
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Great work on this PR!"
  }
}

// Inline comment on specific line
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Consider extracting this into a separate function",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT"  // ADDED, REMOVED, or CONTEXT
  }
}

// Reply to existing comment
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "I agree with this suggestion",
    "parent_comment_id": 456
  }
}

// Add comment with code suggestion (single line)
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This variable name could be more descriptive.",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT",
    "suggestion": "const userAuthenticationToken = token;"
  }
}

// Add comment with multi-line code suggestion
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This function could be simplified using array methods.",
    "file_path": "src/utils/calculations.js",
    "line_number": 50,
    "suggestion_end_line": 55,
    "line_type": "CONTEXT",
    "suggestion": "function calculateTotal(items) {\n  return items.reduce((sum, item) => sum + item.price, 0);\n}"
  }
}

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

• suggestion является обязательным и содержит код для замены

• file_path и line_number обязательны при использовании предложений

• suggestion_end_line является необязательным и используется для многострочных предложений (по умолчанию line_number)

• Комментарий будет отформатирован с помощью блока markdown suggestion, который может быть применен в интерфейсе Bitbucket

Использование фрагментов кода вместо номеров строк

Инструмент add_comment теперь поддерживает автоматический поиск номеров строк с использованием фрагментов кода. Это особенно полезно, когда ИИ-инструменты анализируют diff и могут испытывать трудности с точными номерами строк:

// Add comment using code snippet
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "This variable name could be more descriptive",
    "file_path": "src/components/Button.res",
    "code_snippet": "let isDisabled = false",
    "search_context": {
      "before": ["let onClick = () => {"],
      "after": ["setLoading(true)"]
    }
  }
}

// Handle multiple matches with strategy
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "Consider extracting this",
    "file_path": "src/utils/helpers.js",
    "code_snippet": "return result;",
    "search_context": {
      "before": ["const result = calculate();"],
      "after": ["}"]
    },
    "match_strategy": "best"  // Auto-select highest confidence match
  }
}

Параметры фрагмента кода:

• code_snippet: Точная строка кода для поиска (альтернатива line_number)

• search_context: Необязательный контекст для уточнения нескольких совпадений

  • before: Массив строк, которые должны появиться перед целевой

  • after: Массив строк, которые должны появиться после целевой

• match_strategy: Как обрабатывать несколько совпадений

  • "strict" (по умолчанию): Завершить с ошибкой, показывая все совпадения

  • "best": Автоматически выбрать совпадение с наибольшей уверенностью

Ответ об ошибке при нескольких совпадениях (строгий режим):

{
  "error": {
    "code": "MULTIPLE_MATCHES_FOUND",
    "message": "Code snippet 'return result;' found in 3 locations",
    "occurrences": [
      {
        "line_number": 42,
        "file_path": "src/utils/helpers.js",
        "preview": "  const result = calculate();\n> return result;\n}",
        "confidence": 0.9,
        "line_type": "ADDED"
      },
      // ... more matches
    ],
    "suggestion": "To resolve, either:\n1. Add more context...\n2. Use match_strategy: 'best'...\n3. Use line_number directly"
  }
}

Эта функция особенно полезна для:

• ИИ-инструментов проверки кода, которые анализируют diff

• Скриптов, которые автоматически добавляют комментарии на основе шаблонов кода

• Избежания путаницы с номерами строк в больших diff

Примечание по ответам на комментарии:

• Используйте parent_comment_id, чтобы ответить на любой комментарий (общий или встроенный)

• В ответах get_pull_request:

  • Bitbucket Server показывает ответы, вложенные в массив replies

  • Bitbucket Cloud показывает поле parent_id для комментариев-