mcp-bitbucket

AI 에이전트와 그 옆에 있는 인간을 위한 Bitbucket Server. 클론 없이 풀 리퀘스트와 그 diff를 읽고, 리뷰를 초안으로 작성해 평결과 함께 게시하고, 차단 작업을 게시하고, 코드와 커밋을 탐색하고, 풀 리퀘스트를 열거나 병합하거나 거절할 수 있습니다 — MCP 클라이언트에서, 셸에서, 또는 직접 작성한 TypeScript에서.

Bitbucket Server / Data Center 전용입니다. Bitbucket Cloud는 지원하지 않습니다.

패키지

Claude Code / Claude Desktop 도구 사용 → mcp. 터미널, 스크립트, CI, 명령을 실행하는 에이전트 → cli. 그 외 다른 것을 만든다면 → core. 모두 동일한 자격 증명을 읽고 나란히 설치됩니다.

Related MCP server: Atlassian Bitbucket MCP Server

사전 요구 사항

• Node.js 18+, pnpm 10+ (corepack enable)

• Bitbucket Server 개인 액세스 토큰 — 프로필 → Manage Account → HTTP Access Tokens, 저장소 읽기 + 풀 리퀘스트 쓰기 권한 필요

• bb login(OS 키링) 전용: sudo apt install -y libsecret-1-0 gnome-keyring. 모든 명령은 BITBUCKET_TOKEN으로도 동작합니다.

설치

pnpm install
pnpm build        # core first, then mcp and cli

진입점: packages/mcp/dist/index.js, packages/cli/dist/index.js.

빠른 시작

MCP 서버

claude mcp add mcp-bitbucket \
  -e BITBUCKET_URL=https://bitbucket.example.com \
  -e BITBUCKET_TOKEN=your-personal-access-token \
  -- node /absolute/path/to/mcp-bitbucket/packages/mcp/dist/index.js

또는 .mcp.json에서 (${VAR}는 Claude Code가 확장하므로 비밀번호가 커밋되지 않습니다):

{
  "mcpServers": {
    "mcp-bitbucket": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-bitbucket/packages/mcp/dist/index.js"],
      "env": {
        "BITBUCKET_URL": "${BITBUCKET_URL}",
        "BITBUCKET_TOKEN": "${BITBUCKET_TOKEN}"
      }
    }
  }
}

stdio 대신 HTTP 전송: node packages/mcp/dist/index.js --http (포트 3000) 또는 MCP_HTTP_PORT=8080 node …. 라우트: POST /mcp, GET /mcp (SSE), DELETE /mcp.

bb CLI

pnpm --filter @mcp-bitbucket/cli link --global
bb login          # or export BITBUCKET_URL / BITBUCKET_TOKEN
bb whoami         # proves authentication — `bb ping` only proves reachability
bb pr get 42      # repository comes from the git origin remote

명령 목록: packages/cli/README.md 또는 bb --help.

Claude Code 스킬

bash packages/skill/scripts/install.sh            # ~/.claude/skills/bitbucket-review
bash packages/skill/scripts/install.sh ./.claude  # project scope

PATH에 bb가 있고 해석 가능한 자격 증명이 필요합니다.

구성

환경 변수, 저장소 루트의 .env는 자동으로 로드됩니다 (cp .env.example .env). MCP 서버는 시작 시 이를 검증합니다. CLI는 --url / --token도 허용하며, 이는 모든 것보다 우선합니다.

제한

모든 숫자 상한은 packages/core/src/operations/caps.ts에 있으며 환경 변수로 재정의할 수 있습니다: BITBUCKET_DIFF_MAX_CHARS (60000), BITBUCKET_DIFF_HEAD_RATIO (0.6), BITBUCKET_DIFF_CONTEXT_LINES (3), BITBUCKET_DIFF_FETCH_MAX_CHARS (12000000), BITBUCKET_DIFF_CACHE_ENTRIES (4), BITBUCKET_CHANGED_FILES_MAX_ITEMS (1000), BITBUCKET_CHANGED_FILES_STATS_MAX_FILES (500). 잘림은 결코 조용히 일어나지 않습니다 — 메모에는 상한을 올리는 매개변수와 변수 이름이 명시되고, 생략된 모든 헝크 헤더가 나열됩니다.

권한

두 개의 독립적인 가드가 있습니다.

MCP_PERMISSION_MODE — MCP 서버 전용. 모든 도구는 packages/mcp/src/permissions.ts에서 read, write 또는 destructive로 분류됩니다. 금지된 도구는 ListTools에서 숨겨질 뿐만 아니라 이름으로 호출해도 거부됩니다.

CLI는 이를 읽지 않습니다. readonly 배포는 bb review merge를 막지 않습니다.

저장소 허용 목록 — 두 진입점 모두. BITBUCKET_ALLOWED_PROJECTS / BITBUCKET_ALLOWED_REPOS는 쉼표, 세미콜론 또는 공백으로 구분된 패턴을 받습니다: PROJ, PROJ/*, PROJ/repo-a. 검사는 소켓이 열리기 전에 공유 클라이언트 내부에서 실행되므로 모든 도구와 모든 bb 명령이 이를 상속합니다. 설정하지 않으면 모든 저장소가 허용됩니다. 대소문자를 구분하지 않습니다. 개인 저장소는 프로젝트 ~username입니다. 잘못된 형식의 패턴은 버려지며, 절대 범위가 넓어지지 않습니다 — 잘못된 형식의 패턴만으로 구성된 값은 아무것도 허용하지 않습니다.

도구

29개 MCP 도구: 읽기 17개, 쓰기 9개, 파괴적 3개. 전체 매개변수는 docs/tools.md에 있습니다.

주목할 만한 기본 동작

• 해결된 토론은 숨겨집니다. get_pull_request_comments / bb comment ls는 해결된 스레드와 작업을 표시하려면 includeResolved (--include-resolved)가 필요합니다. 응답은 숨긴 개수를 알려줍니다. 명시적인 state 필터는 기본 동작을 재정의합니다.

• 리뷰는 게시되지 않고 초안으로 작성됩니다. add_pr_draft_comment / bb review draft는 보이지 않는 댓글을 저장합니다. submit_pr_review는 보류 중인 모든 댓글을 평결과 함께 하나의 알림으로 게시합니다. pending: false (--no-pending)는 즉시 게시합니다. discard_pr_draft_review는 초안을 버립니다.

• bb ping ≠ 인증. /application-properties는 많은 인스턴스에서 익명으로 200을 응답합니다. bb whoami가 인증 확인입니다.

개발

pnpm build | typecheck | test | lint | format | clean
pnpm dev:mcp                 # MCP server from source (tsx)
pnpm cli pr ls               # bb from source
pnpm --filter @mcp-bitbucket/core test

어댑터가 서로 어긋나지 않게 하는 계층 규칙:

• core는 MCP나 CLI에 대해 아무것도 모릅니다 — MCP SDK도, yargs도, stdout도 없습니다. 작업은 클라이언트와 매개변수를 받아 구조화된 데이터를 반환하거나 예외를 던집니다.

• 어댑터는 입력 검증과 출력 형태를 담당합니다 — mcp에서는 zod와 MCP 결과 형태, cli에서는 yargs와 텍스트/--json. 어느 것도 core로 새어 나가지 않습니다.

• 오류 메시지는 core에 한 번만 작성됩니다. 각 어댑터가 자신의 어휘로 렌더링하는 {projects} / {login} 스타일 자리 표시자를 사용합니다 — 동일한 실패가 모델에게는 "list_projects를 사용하세요"라고, 사용자에게는 "bb project ls를 사용하세요"라고 말합니다.

• 새 기능은 core의 작업과 포맷터, 그리고 mcp와 cli 각각의 얇은 어댑터로 구성됩니다.

Docker

이미지에는 MCP 서버만 포함됩니다.

docker build -t mcp-bitbucket .
docker run -i --rm -e BITBUCKET_URL=… -e BITBUCKET_TOKEN=… mcp-bitbucket
docker run --rm -p 3000:3000 -e BITBUCKET_URL=… -e BITBUCKET_TOKEN=… -e MCP_HTTP_PORT=3000 mcp-bitbucket

문제 해결

docs/troubleshooting.md. 가장 흔한 세 가지: 클라이언트 목록에서 도구가 누락된 경우 MCP_PERMISSION_MODE가 숨긴 것입니다 (인식할 수 없는 값은 29개 모두를 숨깁니다). Refused: … outside the configured repository allowlist는 허용 목록이 해당 저장소를 포함하지 않는다는 뜻입니다. 웹 UI보다 댓글이 적다면 해결된 스레드가 숨겨져 있는 것입니다.

제한 사항

• Bitbucket Server 전용. Bitbucket Cloud, OAuth/SSO/앱 비밀번호는 지원하지 않습니다.

• bb login은 OS 키링에만 자격 증명을 저장합니다 — 평문 저장소도, --password도 없습니다.

• 웹훅이나 이벤트 기반 모드는 없습니다. 서버는 도구 호출에 응답합니다.

• Diff는 서버에서 렌더링된 통합 diff 텍스트입니다. diff에 고정된 인라인 댓글은 노출되지 않습니다.

• search_code는 인스턴스 코드 인덱스가 필요합니다: 기본 브랜치, 전체 단어, 정규식 없음.

• MCP_PERMISSION_MODE는 MCP 서버만 제한합니다. 허용 목록은 둘 다 제한합니다.