Bitbucket MCP Server

Сервер Model Context Protocol, ориентированный на продакшн, для получения метаданных и диффов пул-реквестов из Bitbucket Cloud и Bitbucket Server/Data Center, с опциональными комментариями к пул-реквестам.

Возможности

• Поддерживает Bitbucket Cloud и самостоятельный Bitbucket Server/Data Center.

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

• Поддерживает bearer-токены и базовую аутентификацию.

• Возвращает сырые диффы и структурированные данные об изменённых файлах, когда Bitbucket их предоставляет.

• Исключает сгенерированные файлы, папки или типы файлов с помощью настраиваемых glob-шаблонов.

• Ограничивает большие диффы, не нарушая UTF-8 символы.

• Использует stdio, не записывая в stdout логи, нарушающие протокол.

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

Related MCP server: Atlassian Bitbucket MCP Server

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

Требуется поддерживаемый LTS-релиз Node.js (Node.js 22 или новее).

git clone https://github.com/inceon/bitbucket-mcp.git
cd bitbucket-mcp
npm install
npm run build
cp .env.example .env

Установите BITBUCKET_URL и BITBUCKET_TOKEN в конфигурации вашего MCP-клиента, затем запустите скомпилированный сервер с помощью node dist/index.js. Сервер намеренно не загружает файлы .env самостоятельно; MCP-клиенты должны передавать переменные окружения напрямую.

Аутентификация

Bearer-аутентификация используется по умолчанию и рекомендуется для персональных токенов доступа Bitbucket Server/Data Center:

BITBUCKET_URL=https://bitbucket.example.com/bitbucket
BITBUCKET_TOKEN=your-personal-access-token
BITBUCKET_AUTH_TYPE=bearer

Для API-токенов Bitbucket Cloud или паролей приложений, требующих базовой аутентификации:

BITBUCKET_URL=https://api.bitbucket.org
BITBUCKET_TOKEN=your-api-token-or-app-password
BITBUCKET_AUTH_TYPE=basic
BITBUCKET_USERNAME=your-bitbucket-username

Предоставьте учётным данным только те разрешения, которые нужны для включённых вами инструментов. Создание комментариев требует разрешения на создание комментариев к пул-реквестам. Никогда не коммитьте учётные данные и не указывайте реальные токены в отчётах об ошибках.

Переменные окружения

Сервер записывает ошибки запуска только в stderr и скрывает настроенные учётные данные из фрагментов ошибок HTTP Bitbucket.

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

Конфигурация Claude Desktop:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/my-bitbucket-mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "https://api.bitbucket.org",
        "BITBUCKET_TOKEN": "your-token"
      }
    }
  }
}

Конфигурация Codex config.toml:

[mcp_servers.bitbucket]
command = "node"
args = ["/absolute/path/to/my-bitbucket-mcp/dist/index.js"]

[mcp_servers.bitbucket.env]
BITBUCKET_URL = "https://api.bitbucket.org"
BITBUCKET_TOKEN = "your-token"

Доступные инструменты

get_pull_request

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

{
  "name": "get_pull_request",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123
  }
}

get_pull_request_comments

Возвращает существующие общие и инлайновые обсуждения в виде нативных для провайдера объектов комментариев. Используйте его перед публикацией замечания ревью, чтобы учесть существующие отзывы. commentsStatus.complete равен false с причиной max_comments или max_pages, когда достигнуты настроенные пределы получения.

get_pull_request_commits

Возвращает нативные для провайдера коммиты, находящиеся в настоящее время в пул-реквесте. Используйте его, чтобы проследить замечание до исходного коммита или проверить, устраняется ли оно последующей работой. commitsStatus.complete равен false с причиной max_commits или max_pages, когда достигнуты настроенные пределы получения.

get_pull_request_diff

Возвращает дифф ревью в стиле git и структурированные изменённые файлы, когда они доступны.

{
  "name": "get_pull_request_diff",
  "arguments": {
    "workspace": "PROJECT_KEY",
    "repository": "my-repository",
    "pull_request_id": 123,
    "ignore_patterns": ["dist/**", "**/*.generated.ts", "package-lock.json"],
    "path": "src/service.ts",
    "context": 5,
    "ignore_whitespace": true,
    "renames": true
  }
}

Вывод диффа доступен как в виде обратно совместимого JSON-текста, так и в виде MCP structuredContent, с объявленной схемой вывода. Он включает:

• provider, pull_request_id, rawDiff, rawDiffBytes и rawDiffSource. rawDiffSource равен provider_raw для Cloud или server_structured для локально нормализованного ответа Server/Data Center.

• truncated и truncationReason: input_limit, когда достигнут предел чтения вышестоящего Cloud, output_limit, когда отфильтрованный результат превысил BITBUCKET_MAX_DIFF_BYTES, или provider_limit, когда Server/Data Center пометил свой структурированный дифф как усечённый.

• Необязательные компактные записи files содержат только path, нормализованный status и oldPath для переименований или копий. Обязательный filesStatus сообщает о полноте; complete равен false с причиной max_files, max_pages или unsupported, а returned отражает фактически возвращённые отфильтрованные записи.

• Необязательные метаданные ignored, когда активны исключения.

Полный результат:

{
  "provider": "cloud",
  "pull_request_id": 123,
  "rawDiff": "diff --git ...",
  "rawDiffBytes": 128,
  "rawDiffSource": "provider_raw",
  "files": [],
  "filesStatus": { "available": true, "complete": true, "returned": 0 },
  "truncated": false
}

Ограниченный частичный результат:

{
  "provider": "cloud",
  "pull_request_id": 123,
  "rawDiff": "diff --git ...",
  "rawDiffBytes": 200000,
  "rawDiffSource": "provider_raw",
  "files": [{ "path": "src/service.ts", "status": "modified" }],
  "filesStatus": {
    "available": true,
    "complete": false,
    "returned": 1,
    "reason": "max_pages"
  },
  "truncated": true,
  "truncationReason": "output_limit"
}

Усечённый rawDiff — это безопасный для UTF-8 префикс ревью, не обязательно полная строка, хунк или применимый патч.

Страницы структурированных файлов обрабатываются до завершения или до достижения настроенного предела файлов/страниц, затем нормализуются в компактные метаданные ревью, а не возвращают хэши, ссылки и дублирующиеся структуры путей провайдера. Недоступная конечная точка diffstat или changes сообщается только после HTTP 404. Ошибки авторизации, ограничения скорости, сервера, некорректного ответа, тайм-аута и транспорта приводят к сбою вызова инструмента, а не к молчаливому пропуску метаданных.

Cloud rawDiff сохраняет исходный ответ провайдера. Server/Data Center использует структурированный ответ /diff и нормализует его файлы, хунки, сегменты и строки в текст ревью в стиле git; это позволяет избежать ошибок, зависящих от версии, при использовании отдельного маршрута экспорта .diff. rawDiffSource делает это различие явным.

path поддерживается обоими провайдерами и является предпочтительным способом просмотра больших пул-реквестов пофайлово; возвращаемые метаданные files ограничены тем же путём. renames доступен только в Cloud. context соответствует context в Cloud и contextLines в Server/Data Center. ignore_whitespace соответствует ignore_whitespace в Cloud и whitespace=ignore-all в Server/Data Center. При отсутствии эти параметры не изменяют значения по умолчанию провайдера.

Шаблоны используют пути относительно репозитория и поддерживают *, ** и ?. Шаблон без /, например package-lock.json или *.png, соответствует этому имени файла в любом месте. Завершающий слэш исключает каталог рекурсивно. Когда активны исключения, ответ включает ignored.patterns, ignored.files и ignored.rawDiffFiltered. Значение false в rawDiffFiltered означает, что провайдер Cloud вернул не-git формат диффа, который нельзя безопасно отфильтровать; ответ сохраняется, а не молча отбрасывается содержимое.

add_pull_request_comment

Создаёт общий, файловый или инлайновый комментарий к строке в пул-реквесте. Эта операция записи доступна только когда в окружении MCP-сервера установлено BITBUCKET_ENABLE_WRITE_TOOLS=true.

Общий комментарий:

{
  "name": "add_pull_request_comment",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123,
    "comment": "The implementation looks good. Please add a regression test for the empty input case."
  }
}

Инлайновый комментарий к добавленной строке:

{
  "name": "add_pull_request_comment",
  "arguments": {
    "workspace": "my-workspace",
    "repository": "my-repository",
    "pull_request_id": 123,
    "comment": "Please handle an empty value here.",
    "file_path": "src/service.ts",
    "line": 42,
    "line_type": "added"
  }
}

Используйте значения line_type: added, removed или context. Добавленные строки по умолчанию относятся к стороне new, удалённые — к стороне old, а контекстные — к new; установите line_side явно, чтобы разместить контекстный комментарий на old. Укажите file_path без полей строк для файлового комментария. Для переименованных файлов в Server/Data Center source_file_path может идентифицировать предыдущий путь.

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

Поведение провайдера

Хост URL определяет провайдера. bitbucket.org и api.bitbucket.org используют Bitbucket Cloud; все остальные хосты используют Server/Data Center.

URL Cloud нормализуются до одного префикса API /2.0 и используют:

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

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

• /repositories/{workspace}/{repository}/pullrequests/{id}/diffstat

• /repositories/{workspace}/{repository}/pullrequests/{id}/comments (GET; POST when enabled)

• /repositories/{workspace}/{repository}/pullrequests/{id}/commits (GET)

URL Server/Data Center сохраняют контекстный путь, например /bitbucket, нормализуются до одного префикса /rest/api/1.0 и используют:

• /projects/{project}/repos/{repository}/pull-requests/{id}

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff (структурированный дифф, нормализованный в текст ревью в стиле git)

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff/{path} (структурированный дифф, ограниченный путём)

• /projects/{project}/repos/{repository}/pull-requests/{id}/changes

• /projects/{project}/repos/{repository}/pull-requests/{id}/comments (GET; POST when enabled)

• /projects/{project}/repos/{repository}/pull-requests/{id}/commits (GET)

Необязательный запрос diffstat или changes сообщает filesStatus.reason: "unsupported" после HTTP 404. Другие ошибки HTTP, тайм-аута, транспорта и разбора приводят к сбою вызова инструмента, чтобы неполные метаданные не были приняты за полный ответ.

Atlassian Rovo MCP

Atlassian документирует действие bitbucketPullRequest.diff, доступное только в Cloud, но не публикует его схему аргументов, форму вывода, контракт пагинации, фильтрации или усечения. Поэтому этот сервер считает прямые Bitbucket API авторитетным источником. Адаптер Rovo следует добавлять только после проверки живой схемы tools/list и контролируемого ответа diff; он должен оставаться явно настроенным и не может заменить поддержку Server/Data Center. См. страницу Atlassian о поддерживаемых инструментах.

Дорожная карта

Запланированные направления для будущих релизов включают:

• Добавить обработку повторных попыток и более понятную диагностику ограничений частоты запросов.

• Предоставлять нормализованный вывод pull request, сохраняя доступ к полям, специфичным для провайдера.

• Добавить инструменты только для чтения для вывода списка pull request и получения статуса сборки.

• Предложить опциональный транспорт Streamable HTTP, оставив stdio по умолчанию.

• Публиковать версионированные релизы с более простыми путями установки и обновления.

Операции записи останутся отключенными по умолчанию. Одобрение, слияние и другие значимые операции Bitbucket не запланированы. Идеи и предложения по реализации приветствуются через GitHub issues.

Разработка

npm run dev        # Run directly from TypeScript
npm run build      # Compile to dist/
npm test           # Run the test suite once
npm run test:watch # Run tests in watch mode
npm run check      # Build and test, matching CI

Реестр команд хранит каждый MCP-инструмент изолированно в src/tools. Перед открытием pull request ознакомьтесь с CONTRIBUTING.md.

Безопасность

Этот сервер обрабатывает учетные данные в памяти и отправляет их только на настроенный BITBUCKET_URL. Внимательно проверьте этот URL перед запуском сервера. Включение инструментов записи позволяет подключенным MCP-клиентам публиковать комментарии к PR от имени аутентифицированного пользователя Bitbucket. Чтобы сообщить об уязвимости конфиденциально, следуйте SECURITY.md.

Лицензия

Выпущено под лицензией MIT.