bitbucket-mcp

Bitbucket Cloud용 MCP 서버. 풀 리퀘스트, 코드 리뷰, 브랜치, 소스, 파이프라인, 웹훅, 변수를 원시 REST 호출 대신 제어된 도구 표면으로 노출합니다.

존재 이유

공식 Atlassian MCP는 Jira와 Confluence만 지원합니다. Bitbucket은 빠져 있어서 모든 저장소 작업이 수기로 작성한 REST 호출에 의존하게 됩니다. 장황한 페이로드, 안전장치 없음, 그리고 스코프가 허용하는 모든 것에 접근할 수 있는 토큰이라는 문제가 있습니다.

이 서버는 세 가지 측면에서 그 격차를 메웁니다:

• 정리된 페이로드. 응답을 실제로 사용하는 필드만으로 정규화하므로 PR 리뷰에 드는 컨텍스트가 원시 REST 응답의 일부에 불과합니다.

• 프롬프트가 아닌 서버에 있는 안전장치. 보호된 브랜치, 파괴적 작업에 대한 confirm, 읽기 전용 모드가 HTTP 호출이 나가기 전에 적용됩니다.

• 의도당 하나의 도구. 하나의 범용 HTTP 탈출구 대신 리뷰, 브랜치, 파이프라인, 웹훅 워크플로를 다루는 55개 도구를 제공합니다.

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

• 스코프가 지정된 Atlassian API 토큰 (인증 참조)

• SSH를 통한 git_* 도구용 Bitbucket에 등록된 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 신원을 반환합니다.

인증

인증은 email:api_token을 사용하는 HTTP Basic입니다. 스코프가 지정된 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). 모든 푸시 및 브랜치 도구는 보호된 브랜치를 거부합니다.

파이프라인: 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)

git용 SSH 또는 HTTPS

clone_repo, git_commit, git_rebase, git_push는 토큰이 아닌 SSH 키를 사용합니다. SSH를 사용할 수 없을 때는 clone_repo_https와 git_push_https가 username:token으로 인증하며 BITBUCKET_USERNAME이 필요합니다. 보호된 브랜치 가드는 두 전송 방식 모두에 적용됩니다.

알려진 제한 사항

• react_pr_comment는 실험적입니다. PR 댓글의 이모지 반응은 Cloud가 아닌 Bitbucket Data Center에 대해 문서화되어 있습니다. 이 도구는 최선 노력 엔드포인트를 대상으로 하며 워크스페이스가 이를 지원하지 않으면 오류를 반환할 수 있습니다.

• **resolve_comment**는 저장소에서 댓글 스레드 해결을 사용할 수 있어야 합니다.

• 사용자 지정 파이프라인이 기대하는 변수를 나열하는 엔드포인트는 없습니다. 해당 정보는 bitbucket-pipelines.yml에서 얻을 수 있으며 get_file_source로 읽으세요.

• 저장된 변수 값을 다시 읽으려면 관리자 스코프가 필요합니다.

개발

프로젝트 규칙과 관례는 CLAUDE.md에 있습니다. 기여는 이슈 우선 워크플로를 따릅니다. 모든 커밋은 헤더에 type(scope): subject [#N] 형식으로 이슈를 연결합니다.

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

사용

MIT 라이선스이며, 말 그대로입니다. 직장에서 사용하고, 상업적으로 사용하고, 포크하고, 자체 도구에 포함시키고, 이름을 바꿔도 됩니다. 허락을 구할 필요도 없고 라이선스 고지를 유지하는 것 외에 어떤 저작자 표시 의례도 없습니다. REST 호출을 수기로 작성하는 오후를 아껴준다면 그걸로 충분히 값어치를 한 것입니다.

필요한 도구가 없거나 이 서버가 다루지 않는 Bitbucket 엔드포인트를 만났나요? 이슈 열기. 풀 리퀘스트는 환영합니다. 유일한 규칙은 모든 커밋이 헤더에 type(scope): subject [#N] 형식으로 이슈를 연결해야 한다는 것입니다.

LICENSE를 참조하세요.