hongjunland/bitbucket-mcp-server

markdown# Bitbucket MCP Server

빗버킷 API와 연동하는 Model Context Protocol (MCP) 서버입니다.

요구사항

• Node.js 18 이상
• npm 또는 yarn
• Bitbucket 계정 및 워크스페이스 접근 권한

상세 설정 가이드

1단계: Bitbucket 앱 패스워드 생성

1. Bitbucket에 로그인
2. 우측 상단 프로필 아이콘 클릭 → 개인 설정 (Personal settings)
3. 좌측 메뉴에서 앱 패스워드 (App passwords) 선택
4. 앱 패스워드 생성 (Create app password) 클릭
5. 레이블 입력 (예: "MCP Server")
6. 다음 권한 선택:
   • ✅ Repositories: Read, Write
   • ✅ Pull requests: Read, Write
7. 생성 클릭 후 패스워드 복사 (⚠️ 한 번만 표시됩니다!)

2단계: 워크스페이스 이름 확인

1. Bitbucket 대시보드에서 워크스페이스 선택
2. URL에서 워크스페이스 이름 확인: https://bitbucket.org/{워크스페이스명}/
3. 또는 좌측 하단에서 워크스페이스 이름 확인

3단계: 환경 변수 설정

cp .env.example .env

.env 파일에 실제 값 입력:

BITBUCKET_USERNAME=your_email@example.com
BITBUCKET_APP_PASSWORD=your_app_password_here
BITBUCKET_WORKSPACE=your_workspace_name

주의사항:

• BITBUCKET_USERNAME은 이메일 주소를 입력하세요
• BITBUCKET_APP_PASSWORD는 생성한 앱 패스워드를 입력하세요
• BITBUCKET_WORKSPACE는 워크스페이스의 정확한 이름을 입력하세요

설치 및 실행

# 의존성 설치
npm install

# 빌드
npm run build

# 실행
npm start

# 개발 모드 (파일 변경 시 자동 재시작)
npm run dev

사용 가능한 도구

MCP 클라이언트 연결

Claude Desktop 설정

1. Claude Desktop의 설정 파일 열기:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 다음 설정 추가:

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/bitbucket-server.js"],
      "env": {
        "BITBUCKET_USERNAME": "your_email@example.com",
        "BITBUCKET_APP_PASSWORD": "your_app_password",
        "BITBUCKET_WORKSPACE": "your_workspace"
      }
    }
  }
}

3. Claude Desktop 재시작

경로 설정 팁:

• macOS/Linux: /Users/username/projects/mcp-server/dist/bitbucket-server.js
• Windows: C:\\Users\\username\\projects\\mcp-server\\dist\\bitbucket-server.js

사용 예시

Claude Desktop에서 다음과 같이 요청할 수 있습니다:

- "내 저장소 목록을 보여줘"
- "project-name 저장소의 브랜치 목록을 보여줘"
- "main 브랜치의 최근 커밋 10개를 보여줘"
- "develop 브랜치에서 feature/new-feature 브랜치를 만들어줘"
- "feature 브랜치에서 main으로 풀 리퀘스트를 만들어줘"

문제 해결

인증 오류 (401 Unauthorized)

• ✅ 이메일 주소가 정확한지 확인
• ✅ 앱 패스워드가 올바르게 입력되었는지 확인
• ✅ 앱 패스워드에 필요한 권한이 부여되었는지 확인

워크스페이스를 찾을 수 없음 (404 Not Found)

• ✅ 워크스페이스 이름의 대소문자 확인
• ✅ 워크스페이스에 대한 접근 권한 확인
• ✅ URL에서 정확한 워크스페이스 이름 복사

MCP 서버 연결 오류

• ✅ npm run build 실행하여 최신 빌드 확인
• ✅ dist/bitbucket-server.js 파일 존재 여부 확인
• ✅ Node.js 버전 확인 (18 이상)
• ✅ Claude Desktop 재시작

네트워크 오류

• ✅ 인터넷 연결 상태 확인
• ✅ Bitbucket Status 페이지 확인
• ✅ 방화벽 설정 확인

프로젝트 구조

mcp-server/
├── src/
│   └── bitbucket-server.ts    # 메인 서버 코드
├── dist/                        # 빌드된 파일
│   └── bitbucket-server.js
├── .env.example                 # 환경 변수 템플릿
├── .env                         # 실제 환경 변수 (git 제외)
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

보안 주의사항

⚠️ 중요:

• .env 파일을 절대 Git에 커밋하지 마세요
• 앱 패스워드를 다른 사람과 공유하지 마세요
• 사용하지 않는 앱 패스워드는 삭제하세요
• 정기적으로 앱 패스워드를 갱신하세요

라이선스

MIT

기여

이슈나 풀 리퀘스트는 언제든지 환영합니다!