Bitbucket MCP Server

Bitbucket Cloud 및 Bitbucket Server/Data Center에서 풀 리퀘스트 메타데이터와 diff를 검색하고, 선택적으로 풀 리퀘스트 댓글을 지원하는 프로덕션 중심 Model Context Protocol 서버입니다.

기능

• Bitbucket Cloud 및 자체 호스팅 Bitbucket Server/Data Center를 지원합니다.

• 풀 리퀘스트 메타데이터, diff, 리뷰 토론, 일반 또는 인라인 댓글을 위한 전용 도구를 제공합니다.

• bearer 토큰 및 기본 인증을 지원합니다.

• Bitbucket이 제공하는 경우 원시 diff와 구조화된 변경 파일 데이터를 반환합니다.

• 구성 가능한 glob 패턴을 통해 생성된 파일, 폴더 또는 파일 형식을 제외합니다.

• UTF-8 문자를 깨지 않으면서 대용량 diff를 제한합니다.

• 프로토콜을 깨뜨리는 로그를 stdout에 기록하지 않고 stdio를 사용합니다.

• 댓글 생성은 기본적으로 비활성화되어 있으며 풀 리퀘스트를 승인, 병합 또는 다른 방식으로 수정하지 않습니다.

Related MCP server: Atlassian Bitbucket MCP Server

빠른 시작

지원되는 Node.js LTS 릴리스(Node.js 22 이상)가 필요합니다.

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

MCP 클라이언트 구성에서 BITBUCKET_URL 및 BITBUCKET_TOKEN을 설정한 다음 컴파일된 서버를 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

기본 인증이 필요한 Bitbucket Cloud API 토큰 또는 앱 비밀번호의 경우:

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

사용하도록 설정한 도구에 필요한 권한만 자격 증명에 부여하세요. 댓글 생성에는 풀 리퀘스트 댓글을 만들 수 있는 권한이 필요합니다. 자격 증명을 커밋하거나 이슈 보고서에 실제 토큰을 넣지 마세요.

환경 변수

서버는 시작 오류만 stderr에 기록하며 Bitbucket HTTP 오류 조각에서 구성된 자격 증명을 삭제합니다.

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는 max_comments 또는 max_pages 이유로 false가 됩니다.

get_pull_request_commits

현재 풀 리퀘스트에 포함된 제공자 고유 커밋을 반환합니다. 발견 사항을 시작 커밋으로 추적하거나 이후 작업이 이를 해결하는지 확인하는 데 사용하세요. 구성된 검색 상한에 도달하면 commitsStatus.complete는 max_commits 또는 max_pages 이유로 false가 됩니다.

get_pull_request_diff

가능한 경우 git 스타일 리뷰 diff와 구조화된 변경 파일을 반환합니다.

{
  "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
  }
}

Diff 출력은 하위 호환 가능한 JSON 텍스트와 MCP structuredContent로 모두 제공되며 선언된 출력 스키마가 함께 제공됩니다. 여기에는 다음이 포함됩니다:

• provider, pull_request_id, rawDiff, rawDiffBytes 및 rawDiffSource. rawDiffSource는 Cloud의 경우 provider_raw, 로컬에서 정규화된 Server/Data Center 응답의 경우 server_structured입니다.

• truncated 및 truncationReason: 업스트림 Cloud 읽기 제한에 도달하면 input_limit, 필터링된 결과가 BITBUCKET_MAX_DIFF_BYTES를 초과하면 output_limit, Server/Data Center가 구조화된 diff를 잘림으로 표시하면 provider_limit입니다.

• 선택적 간결 files 항목에는 path, 정규화된 status, 이름 변경 또는 복사의 경우 oldPath만 포함됩니다. 필수 filesStatus는 완전성을 보고합니다. complete는 max_files, max_pages 또는 unsupported 이유로 false가 되며, 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 안전 리뷰 접두사이며 완전한 줄, 헝크(hunk) 또는 적용 가능한 패치가 아닐 수 있습니다.

구조화된 파일 페이지는 완료되거나 구성된 파일/페이지 상한에 도달할 때까지 추적된 다음, 제공자 해시, 링크 및 중복 경로 구조를 반환하는 대신 간결한 리뷰 메타데이터로 정규화됩니다. 사용할 수 없는 diffstat 또는 changes 엔드포인트는 HTTP 404 이후에만 보고됩니다. 인증, 속도 제한, 서버, 잘못된 응답, 시간 초과 및 전송 실패는 메타데이터를 조용히 생략하지 않고 도구 호출을 실패시킵니다.

Cloud rawDiff는 제공자의 원시 응답을 보존합니다. Server/Data Center는 구조화된 /diff 응답을 사용하여 해당 파일, 헝크, 세그먼트 및 줄을 git 스타일 리뷰 텍스트로 정규화합니다. 이를 통해 별도의 .diff 내보내기 경로에서 발생하는 버전별 실패를 피할 수 있습니다. rawDiffSource는 그 차이를 명시적으로 나타냅니다.

path는 두 제공자 모두에서 지원되며 큰 풀 리퀘스트를 파일별로 검토하는 데 선호되는 방법입니다. 반환된 files 메타데이터는 동일한 경로로 범위가 제한됩니다. renames는 Cloud 전용입니다. context는 Cloud의 context 및 Server/Data Center의 contextLines에 매핑됩니다. ignore_whitespace는 Cloud의 ignore_whitespace 및 Server/Data Center의 whitespace=ignore-all에 매핑됩니다. 이 컨트롤이 없으면 제공자 기본값을 변경하지 않습니다.

패턴은 저장소 기준 경로를 사용하며 *, ** 및 ?을 지원합니다. package-lock.json 또는 *.png처럼 /가 없는 패턴은 해당 파일 이름을 어디서나 일치시킵니다. 후행 슬래시는 디렉터리를 재귀적으로 제외합니다. 제외가 활성화되면 응답에 ignored.patterns, ignored.files 및 ignored.rawDiffFiltered가 포함됩니다. rawDiffFiltered 값이 false이면 Cloud 제공자가 안전하게 필터링할 수 없는 git이 아닌 diff 형식을 반환했음을 의미하며, 콘텐츠를 조용히 삭제하는 대신 응답이 보존됩니다.

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 쪽입니다. old 쪽에 컨텍스트 댓글을 배치하려면 line_side를 명시적으로 설정하세요. 파일 수준 댓글의 경우 줄 필드 없이 file_path를 제공하세요. Server/Data Center에서 이름이 변경된 파일의 경우 source_file_path로 이전 경로를 식별할 수 있습니다.

인증된 Bitbucket 사용자가 댓글 작성자가 됩니다. MCP 클라이언트에서 도구 호출을 승인하기 전에 대상 워크스페이스, 저장소, 풀 리퀘스트 ID 및 댓글 텍스트를 검토하세요.

제공자 동작

URL 호스트가 제공자를 결정합니다. bitbucket.org 및 api.bitbucket.org는 Bitbucket Cloud를 사용하고 그 외 모든 호스트는 Server/Data Center를 사용합니다.

Cloud URL은 하나의 /2.0 API 접두사로 정규화되며 다음을 사용합니다:

• /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)

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

Server/Data Center URL은 /bitbucket과 같은 컨텍스트 경로를 유지하고 하나의 /rest/api/1.0 접두사로 정규화되며 다음을 사용합니다:

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

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff (git 스타일 리뷰 텍스트로 정규화된 구조화된 diff)

• /projects/{project}/repos/{repository}/pull-requests/{id}/diff/{path} (경로 범위의 구조화된 diff)

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

• /projects/{project}/repos/{repository}/pull-requests/{id}/comments (GET; 활성화된 경우 POST)

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

선택적 diffstat 또는 changes 요청은 HTTP 404 이후 filesStatus.reason: "unsupported"를 보고합니다. 다른 HTTP, 시간 초과, 전송 및 구문 분석 실패는 도구 호출을 실패시켜 불완전한 메타데이터가 완전한 응답으로 오인되지 않도록 합니다.

Atlassian Rovo MCP

Atlassian은 Cloud 전용 bitbucketPullRequest.diff 액션을 문서화하지만, 해당 액션의 인자 스키마, 출력 형태, 페이지네이션, 필터링, 또는 잘림(truncation) 계약은 공개하지 않습니다. 따라서 이 서버는 Bitbucket 공식 API를 권위 있는 소스로 유지합니다. Rovo 어댑터는 라이브 tools/list 스키마와 통제된 diff 응답을 검증한 후에만 추가해야 하며, 명시적으로 구성된 상태를 유지해야 하고 Server/Data Center 지원을 대체할 수 없습니다. Atlassian의 지원 도구 페이지를 참조하세요.

로드맵

향후 릴리스에서 계획된 영역은 다음과 같습니다:

• 재시도 처리 및 더 명확한 속도 제한 진단 추가.

• 공급자별 필드에 대한 접근을 유지하면서 정규화된 풀 리퀘스트 출력 제공.

• 풀 리퀘스트 목록 조회 및 빌드 상태 검색을 위한 읽기 전용 도구 추가.

• stdio를 기본값으로 유지하면서 선택적 Streamable HTTP 전송 제공.

• 더 간단한 설치 및 업그레이드 경로를 갖춘 버전별 릴리스 게시.

쓰기 작업은 기본적으로 비활성화된 상태로 유지됩니다. 승인, 병합 및 기타 영향력이 큰 Bitbucket 작업은 계획에 없습니다. 아이디어와 구현 제안은 GitHub 이슈를 통해 환영합니다.

개발

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 아래에 격리하여 유지합니다. 풀 리퀘스트를 열기 전에 CONTRIBUTING.md를 참조하세요.

보안

이 서버는 자격 증명을 메모리에서 처리하며 구성된 BITBUCKET_URL로만 전송합니다. 서버를 시작하기 전에 해당 URL을 주의 깊게 검토하세요. 쓰기 도구를 활성화하면 연결된 MCP 클라이언트가 인증된 Bitbucket 사용자로 PR 댓글을 게시할 수 있습니다. 취약점을 비공개로 신고하려면 SECURITY.md를 따르세요.

라이선스

MIT 라이선스에 따라 배포됩니다.