bitbucket-mcp

MCP-сервер для Bitbucket Cloud. Пул-реквесты, ревью кода, ветки, исходники, пайплайны, вебхуки и переменные, представленные в виде контролируемого набора инструментов вместо сырых REST-вызовов.

Зачем это нужно

Официальный MCP от Atlassian покрывает только Jira и Confluence. Bitbucket остаётся без внимания, поэтому каждая операция с репозиторием сводится к написанным вручную REST-вызовам: громоздкие полезные нагрузки, отсутствие защитных механизмов и токен, который может получить доступ ко всему, что разрешает область действия.

Этот сервер закрывает этот пробел по трём направлениям:

• Урезанные полезные нагрузки. Ответы нормализуются до полей, которые вы действительно используете, поэтому ревью PR обходится в долю контекста по сравнению с сырым REST-ответом.

• Защитные механизмы на сервере, а не в промпте. Защищённые ветки, confirm для разрушительных действий и режим только для чтения применяются до отправки HTTP-запроса.

• Один инструмент на одно намерение. 55 инструментов, покрывающих рабочие процессы ревью, веток, пайплайнов и вебхуков, вместо одного универсального HTTP-запасного выхода.

flowchart LR
  A["MCP client<br/>(Claude Code, Inspector)"] -->|stdio| B["bitbucket-mcp"]
  B --> C{"Guards"}
  C -->|"read only, confirm,<br/>protected branch,<br/>workspace lock"| D["Bitbucket Cloud<br/>REST API"]
  C -.->|refused before<br/>the HTTP call| A
  B --> E["git over SSH<br/>or HTTPS"]
  E --> F["Repository"]
  D -->|normalized,<br/>trimmed response| A

Related MCP server: Bitbucket MCP

Установка

Пакет опубликован на npm как @marcusyoda/bitbucket-mcp.

Требования

• Node >= 20

• API-токен Atlassian с ограниченными правами (см. Аутентификация)

• SSH-ключ, зарегистрированный в Bitbucket, для инструментов git_* по SSH. Необязательно, если вы используете варианты HTTPS.

Вариант 1: npx, ничего устанавливать не нужно

Самый быстрый путь. Укажите вашему MCP-клиенту на пакет и позвольте npx разрешить его:

npx -y @marcusyoda/bitbucket-mcp

Вариант 2: глобальная установка

npm install -g @marcusyoda/bitbucket-mcp
# or: pnpm add -g @marcusyoda/bitbucket-mcp
bitbucket-mcp

Вариант 3: из исходников

git clone https://github.com/marcusyoda/bitbucket-mcp.git
cd bitbucket-mcp
pnpm install
pnpm build          # dist/index.js

Регистрация в вашем MCP-клиенте

Claude Code, через CLI

claude mcp add bitbucket \
  --env BITBUCKET_EMAIL=you@example.com \
  --env BITBUCKET_API_TOKEN=your-token \
  --env BITBUCKET_WORKSPACE=your-workspace \
  -- npx -y @marcusyoda/bitbucket-mcp

Любой клиент, через .mcp.json

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@marcusyoda/bitbucket-mcp"],
      "env": {
        "BITBUCKET_EMAIL": "you@example.com",
        "BITBUCKET_API_TOKEN": "your-token",
        "BITBUCKET_WORKSPACE": "your-workspace",
        "BITBUCKET_DEFAULT_REPO": "your-repo-optional"
      }
    }
  }
}

Запускаете из исходников? Замените команду на собранную точку входа:

{ "command": "node", "args": ["/abs/path/to/bitbucket-mcp/dist/index.js"] }

Проверьте подключение, вызвав get_current_user: он прогоняет токен по кругу и возвращает вашу учётную запись Bitbucket.

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

Аутентификация выполняется через HTTP Basic с email:api_token. Создайте API-токен с ограниченными правами на id.atlassian.com > Manage account > Security > API tokens.

Области действия токена (детальный выбор, создавайте только то, что используете):

Инструменты для работы с переменными (*_variable*, list_deployment_*) требуют admin:repository:bitbucket. Пропустить эту область можно: эти инструменты вернут 403, а всё остальное продолжит работать.

Обоснование и полный реестр решений по правам доступа находятся в PERMISSIONS.md.

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

Скопируйте .env.example в .env для локальных запусков. Никогда не коммитьте его.

.env пакета загружается только когда BITBUCKET_API_TOKEN отсутствует в окружении. Так лаунчер, внедряющий учётные данные для каждого проекта, всегда побеждает, а случайный .env из другого рабочего пространства никогда не сможет переопределить внедрённый токен.

Модель безопасности

• BITBUCKET_READ_ONLY=true блокирует все записывающие и разрушительные инструменты до обращения к API.

• Разрушительные инструменты (merge, decline, delete_*, stop_pipeline, git_commit, git_push, инлайновые комментарии к PR) требуют confirm: true.

• Создание переменной secured также требует confirm: true.

• Значения защищённых переменных доступны в API только на запись и никогда не возвращаются и не логируются.

• Защищённые ветки (BITBUCKET_PROTECTED_BRANCHES, по умолчанию main,dev) жёстко заблокированы от прямого изменения: git_push, git_rebase (когда ветка извлечена), delete_branch и create_branch отказываются работать с ними, даже с confirm. Вносите изменения туда через PR: merge_pull_request в защищённую ветку разрешён с confirm: true.

• Блокировка рабочего пространства. С BITBUCKET_LOCK_WORKSPACE=true любой вызов, указывающий другое рабочее пространство, отклоняется. Создано для машин, обслуживающих несколько клиентов из одной установки.

Инструменты

Каждый инструмент принимает необязательные workspace и repo для переопределения значений по умолчанию из окружения.

Репозиторий и мета: get_current_user, list_repositories, get_repository, create_repository

Пул-реквесты: list_pull_requests, get_pull_request, get_pull_request_diff, get_pull_request_activity, create_pull_request, update_pull_request, approve_pull_request, unapprove_pull_request, request_changes_pull_request, decline_pull_request (confirm), merge_pull_request (confirm), list_pr_commits, get_diff

Комментарии: list_pr_comments, add_pr_comment (инлайн требует confirm), reply_pr_comment, update_pr_comment, delete_pr_comment (confirm), resolve_comment, react_pr_comment (экспериментально)

Ветки, исходники и git: list_branches, get_branch, create_branch, delete_branch (confirm), get_file_source, list_directory, clone_repo, clone_repo_https, git_commit (confirm), git_rebase, git_push (confirm), git_push_https (confirm). Все инструменты push и работы с ветками отклоняют защищённые ветки.

Пайплайны: list_pipelines, get_pipeline, get_pipeline_steps, get_pipeline_step_log, trigger_pipeline, stop_pipeline (confirm)

Переменные: list_repo_pipeline_variables, upsert_repo_pipeline_variable, delete_repo_pipeline_variable (confirm), list_workspace_variables, list_deployment_environments, list_deployment_variables, upsert_deployment_variable, delete_deployment_variable (confirm)

Вебхуки: list_webhooks, get_webhook, create_webhook, update_webhook, delete_webhook (confirm)

SSH или HTTPS для git

clone_repo, git_commit, git_rebase и git_push используют ваш SSH-ключ, а не токен. Если SSH недоступен, clone_repo_https и git_push_https аутентифицируются с помощью username:token и требуют BITBUCKET_USERNAME. Ограничение для защищённых веток применяется к обоим транспортам.

Известные ограничения

• react_pr_comment экспериментален. Эмодзи-реакции на комментарии к PR документированы для Bitbucket Data Center, а не Cloud. Инструмент нацелен на endpoint best effort и может вернуть ошибку, если ваше рабочее пространство его не поддерживает.

• resolve_comment зависит от того, доступно ли разрешение веток обсуждения для репозитория.

• Не существует endpoint, который перечисляет, какие переменные ожидает пользовательский пайплайн. Эта информация берётся из bitbucket-pipelines.yml; прочитайте его с помощью get_file_source.

• Для чтения сохранённых значений переменных требуется область администратора.

Разработка

pnpm install
pnpm dev         # tsx watch
pnpm typecheck
pnpm build       # tsup, ESM
pnpm inspect     # build and open the MCP Inspector

Правила проекта и соглашения находятся в CLAUDE.md. Вклад следует рабочему процессу «сначала issue»: каждый коммит ссылается на issue в заголовке в формате type(scope): subject [#N].

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

Лицензия MIT, и это буквально так: используйте его на работе, используйте в коммерческих целях, форкайте, встраивайте в свои инструменты, переименовывайте. Не нужно спрашивать разрешения и выполнять ритуалы с указанием авторства, кроме сохранения уведомления о лицензии. Если он сэкономит вам полдня ручного написания REST-вызовов, он уже окупился.

Не хватает инструмента или наткнулись на endpoint Bitbucket, который не покрыт? Откройте issue. Пул-реквесты приветствуются: единственное внутреннее правило — каждый коммит ссылается на issue в заголовке в формате type(scope): subject [#N].

См. LICENSE.