Bitbucket MCP

Cursor IDE와 Bitbucket Cloud를 통합하는 Model Context Protocol (MCP) 서버로, Bitbucket 워크스페이스에서 직접 저장소 정보와 커밋 데이터를 가져올 수 있습니다.

기능

• 저장소 목록: Bitbucket 워크스페이스의 모든 저장소를 가져옵니다.

• 저장소 세부 정보: 특정 저장소에 대한 상세 정보를 가져옵니다.

• 커밋 정보: 커밋 기록 및 최신 커밋 세부 정보를 검색합니다.

• 커밋 수: 저장소별 총 커밋 수를 가져옵니다.

• 최신 커밋 데이터: 각 저장소의 가장 최근 커밋 날짜, 작성자 및 메시지를 가져옵니다.

• 워크스페이스: 사용 가능한 모든 워크스페이스를 나열합니다.

• 풀 리퀘스트: 풀 리퀘스트 생성, 보기, 나열, 업데이트 및 댓글 읽기/추가를 수행합니다.

• 프로젝트: 프로젝트 세부 정보를 보고 기본 검토자 목록을 확인합니다.

• 브랜치 제한: 프로젝트 및 저장소에 대한 브랜치 제한을 관리합니다.

• 커밋: 개별 커밋 및 커밋 목록을 검색합니다.

Related MCP server: JIRA MCP Server

사전 요구 사항

• Node.js 18 이상

• npm 또는 yarn

• Bitbucket Cloud 계정

• Bitbucket 앱 비밀번호 (인증용)

설정

1. 의존성 설치

npm install

2. 프로젝트 빌드

npm run build

3. Atlassian API 토큰 생성*

• Jira 또는 Confluence용 토큰이 이미 있는 경우 재사용할 수 있습니다 *

1. Bitbucket 계정 설정으로 이동합니다.

2. "액세스 관리" 아래의 "앱 비밀번호"로 이동합니다.

3. "앱 비밀번호 생성"(구식)을 클릭하는 대신 "API 토큰으로 이동"을 클릭합니다.

4. API 토큰을 생성합니다.

5. 설명이 포함된 이름을 지정합니다 (예: "Cursor MCP Integration").

6. 만료 날짜를 선택합니다.

7. 생성된 토큰을 복사합니다.

4. 환경 변수 구성

프로젝트 루트에 .env 파일을 생성합니다:

BITBUCKET_USERNAME=your_bitbucket_email_address
BITBUCKET_APP_PASSWORD=your_api_token
BITBUCKET_WORKSPACE=your_workspace_name

참고: 워크스페이스 이름은 일반적으로 사용자 이름 또는 조직 이름입니다. Bitbucket URL에서 확인할 수 있습니다 (예: https://bitbucket.org/workspace_name/).

5. Cursor MCP 구성에 추가

Cursor MCP 설정에 다음 구성을 추가합니다:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["@korfu/bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your_bitbucket_email_address",
        "BITBUCKET_APP_PASSWORD": "your_api_token",
        "BITBUCKET_WORKSPACE": "your_workspace_name"
      }
    }
  }
}

6. Cursor 재시작

구성을 추가한 후, Cursor IDE를 재시작하여 MCP 서버를 로드합니다.

사용법

구성 완료 후, Cursor에서 다음 도구를 사용할 수 있습니다:

워크스페이스

• bitbucket_list_workspaces

저장소

• bitbucket_list_repositories

• bitbucket_get_repository_details

커밋

• bitbucket_list_commits

• bitbucket_get_commit

풀 리퀘스트

• bitbucket_list_pull_requests

• bitbucket_get_pull_request

• bitbucket_create_pull_request

• bitbucket_update_pull_request

• bitbucket_list_pull_request_comments

• bitbucket_get_pull_request_comment

• bitbucket_add_pull_request_comment

프로젝트

• bitbucket_get_project

• bitbucket_list_default_reviewers

브랜치 제한

• bitbucket_list_branch_restrictions

• bitbucket_get_branch_restriction

• bitbucket_update_repository_branching_model_settings

• bitbucket_update_project_branching_model_settings

사용 가능한 도구

워크스페이스

• list_workspaces: 현재 사용자가 액세스할 수 있는 모든 워크스페이스를 나열합니다.

저장소

• list_repositories: 구성된 Bitbucket 워크스페이스의 모든 저장소를 나열합니다.

• get_repository_details: 최신 커밋 정보를 포함하여 특정 저장소에 대한 상세 정보를 가져옵니다.

커밋

• list_commits: 특정 저장소의 커밋 정보를 가져옵니다.

• get_commit: 해시를 사용하여 단일 커밋을 가져옵니다.

풀 리퀘스트

• list_pull_requests: 저장소의 모든 풀 리퀘스트를 나열합니다.

• get_pull_request: ID를 사용하여 단일 풀 리퀘스트를 가져옵니다.

• create_pull_request: 새 풀 리퀘스트를 생성합니다. //베타 버전 - 테스트되지 않음

• update_pull_request: 기존 풀 리퀘스트를 업데이트합니다. //베타 버전 - 테스트되지 않음

• list_pull_request_comments: 페이지네이션을 지원하여 풀 리퀘스트의 모든 댓글(전체, 인라인 및 답글)을 나열합니다.

• get_pull_request_comment: 인라인 파일/라인 컨텍스트를 포함하여 ID로 풀 리퀘스트의 단일 댓글을 가져옵니다.

• add_pull_request_comment: 풀 리퀘스트에 댓글을 추가합니다. 일반 댓글, 특정 파일/라인에 대한 인라인 댓글 및 스레드 답글을 지원합니다.

프로젝트

• get_project: 키를 사용하여 단일 프로젝트를 가져옵니다.

• list_default_reviewers: 프로젝트의 기본 검토자 목록을 가져옵니다.

브랜치 제한

• list_branch_restrictions: 저장소의 모든 브랜치 제한을 나열합니다.

• get_branch_restriction: ID를 사용하여 단일 브랜치 제한을 가져옵니다.

• update_repository_branching_model_settings: 저장소의 브랜치 모델 구성을 업데이트합니다. //베타 버전 - 테스트되지 않음

• update_project_branching_model_settings: 프로젝트의 브랜치 모델 구성을 업데이트합니다. //베타 버전 - 테스트되지 않음

개발

개발 모드에서 실행

npm run dev

빌드

npm run build

프로젝트 구조

BitbucketMCP/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript output
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .gitignore           # Git ignore rules
└── README.md            # This file

문제 해결

인증 문제

• Bitbucket 사용자 이름과 앱 비밀번호가 올바른지 확인하세요.

• 앱 비밀번호에 올바른 권한(Repositories: Read)이 있는지 확인하세요.

• 워크스페이스 이름이 올바른지 확인하세요.

연결 문제

• 인터넷 연결을 확인하세요.

• 네트워크에서 Bitbucket API에 액세스할 수 있는지 확인하세요.

• MCP 서버가 실행 중인지 확인하세요 (Cursor의 MCP 로그 확인).

저장소를 찾을 수 없음

• 저장소 이름이 올바른지 확인하세요 (표시 이름이 아닌 저장소 슬러그 사용).

• 저장소에 대한 액세스 권한이 있는지 확인하세요.

• 지정된 워크스페이스에 저장소가 존재하는지 확인하세요.

MCP 서버가 로드되지 않음

• Cursor 구성에서 dist/index.js 경로가 올바른지 확인하세요.

• Node.js가 설치되어 있고 명령줄에서 액세스할 수 있는지 확인하세요.

• Cursor의 MCP 서버 로그에서 오류 메시지를 확인하세요.

보안 참고 사항

• Bitbucket 앱 비밀번호를 안전하게 보관하고 버전 제어 시스템에 커밋하지 마세요.

• 자격 증명에는 환경 변수나 안전한 구성 관리를 사용하세요.

• 앱 비밀번호에는 최소한의 필수 권한만 부여해야 합니다.

• 앱 비밀번호를 정기적으로 교체하는 것을 고려하세요.

기여

1. 저장소를 포크합니다.

2. 기능 브랜치를 생성합니다.

3. 변경 사항을 적용합니다.

4. 해당되는 경우 테스트를 추가합니다.

5. 풀 리퀘스트를 제출합니다.

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.