Atlassian Bitbucket MCP 서버
Atlassian Bitbucket Cloud용 Node.js/TypeScript 모델 컨텍스트 프로토콜(MCP) 서버입니다. AI 시스템(예: Claude 또는 Cursor AI와 같은 LLM)이 저장소, 풀 리퀘스트, 작업 공간 및 코드와 실시간으로 안전하게 상호 작용할 수 있도록 지원합니다.
왜 이 서버를 사용해야 하나요?
- 최소 입력, 최대 출력 : 간단한 식별자는 추가 플래그가 필요하지 않고 포괄적인 세부 정보를 제공합니다.
- 풍부한 코드 시각화 : 파일 통계, 차이점 보기, 스마트 컨텍스트를 통해 코드 변경 사항에 대한 자세한 통찰력을 얻으세요.
- 안전한 로컬 인증 : 자격 증명을 사용하여 로컬에서 실행하고, 원격 서버에 토큰을 저장하지 않습니다.
- 직관적인 마크다운 응답 : 모든 출력에 대해 잘 구성되고 일관된 마크다운 형식이 적용됩니다.
- Bitbucket 전체 통합 : 작업 공간, 저장소, 풀 리퀘스트, 댓글, 코드 검색 등에 액세스하세요.
MCP란 무엇인가요?
모델 컨텍스트 프로토콜(MCP)은 AI 시스템을 외부 도구 및 데이터 소스에 안전하게 연결하기 위한 개방형 표준입니다. 이 서버는 Bitbucket Cloud용 MCP를 구현하여 AI 어시스턴트가 Bitbucket 데이터와 프로그래밍 방식으로 상호 작용할 수 있도록 지원합니다.
필수 조건
- Node.js (>=18.x): 다운로드
- Bitbucket 클라우드 계정
설정
1단계: 인증
다음 인증 방법 중 하나를 선택하세요.
옵션 A: Bitbucket 앱 비밀번호(권장)
Bitbucket 앱 비밀번호 에서 생성하세요. 최소 권한:
- 작업 공간: 읽기
- 저장소: 읽기
- 풀 리퀘스트: 읽기
명시적으로 제공되지 않은 경우 BITBUCKET_DEFAULT_WORKSPACE 설정하여 기본 작업 공간을 지정할 수도 있습니다.
옵션 B: Atlassian API 토큰
Atlassian API 토큰 에서 하나를 생성합니다.
참고: Bitbucket 앱 비밀번호는 더욱 세부적이고 Bitbucket 전용 권한을 제공하므로 적극 권장됩니다.
2단계: 자격 증명 구성
옵션 A: MCP 구성 파일(권장)
~/.mcp/configs.json 편집하거나 생성합니다.
Bitbucket 앱 비밀번호 사용:
지엑스피1
Atlassian API 토큰 사용:
{
"bitbucket": {
"environments": {
"ATLASSIAN_SITE_NAME": "bitbucket",
"ATLASSIAN_USER_EMAIL": "<your_email>",
"ATLASSIAN_API_TOKEN": "<your_api_token>"
}
}
}
옵션 B: 환경 변수
export ATLASSIAN_BITBUCKET_USERNAME="<your_username>"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="<your_app_password>"
3단계: 설치 및 실행
npx 로 빠르게 시작하기
npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces
글로벌 설치
npm install -g @aashari/mcp-server-atlassian-bitbucket
mcp-atlassian-bitbucket ls-workspaces
4단계: AI Assistant에 연결
MCP 호환 클라이언트(예: Claude, Cursor AI)를 구성하세요.
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"]
}
}
}
MCP 도구
MCP 도구는 snake_case 이름과 camelCase 매개변수를 사용하고 Markdown 형식의 응답을 반환합니다.
- bb_ls_workspaces : 사용 가능한 작업 공간을 나열합니다(
query : str opt). 사용: 접근 가능한 작업 공간을 확인합니다. - bb_get_workspace : 작업 공간 세부 정보를 가져옵니다(
workspaceSlug : str 요청). 사용: 작업 공간 정보 보기. - bb_ls_repos : 저장소를 나열합니다(
workspaceSlug : str opt, projectKey : str opt, query : str opt, role : str opt). 사용: 저장소 찾기. - bb_get_repo : 저장소 세부 정보를 가져옵니다(
workspaceSlug : 문자열 요청, repoSlug : 문자열 요청). 용도: 저장소 정보에 액세스합니다. - bb_search : Bitbucket 콘텐츠를 검색합니다(
workspaceSlug : str req, query : str req, scope : str opt, language : str opt, extension : str opt). 용도: 코드나 PR 찾기. - bb_ls_prs : 풀 리퀘스트를 나열합니다(
workspaceSlug : str 요청, repoSlug : str 요청, state : str 선택). 사용: 열려 있거나 병합된 PR을 확인합니다. - bb_get_pr : PR 세부 정보를 가져옵니다(
workspaceSlug : str 요청, repoSlug : str 요청, prId : str 요청). 사용: diff를 포함한 PR 세부 정보를 확인합니다. - bb_ls_pr_comments : PR 댓글을 나열합니다(
workspaceSlug : 문자열 요청, repoSlug : 문자열 요청, prId : 문자열 요청). 용도: PR 토론 보기. - bb_add_pr_comment : PR에 주석을 추가합니다(
workspaceSlug : str req, repoSlug : str req, prId : str req, content : str req, inline : obj opt). 사용: PR에 피드백을 추가합니다. - bb_add_pr : PR을 생성합니다(
workspaceSlug : 문자열 요청, repoSlug : 문자열 요청, title : 문자열 요청, sourceBranch : 문자열 요청, targetBranch : 문자열 선택). 사용: 새로운 PR을 생성합니다. - bb_add_branch : 브랜치를 생성합니다(
workspaceSlug : str req, repoSlug : str req, newBranchName : str req, sourceBranchOrCommit : str opt). 사용: 기능 브랜치를 생성합니다. - bb_clone_repo : 저장소를 복제합니다(
workspaceSlug : 문자열 요청, repoSlug : 문자열 요청, targetPath : 문자열 요청). 사용: 로컬에서 코드를 복제합니다. - bb_get_commit_history : 커밋 기록을 가져옵니다(
workspaceSlug : str req, repoSlug : str req, revision : str opt, path : str opt). 용도: 코드 기록 보기. - bb_get_file : 파일 내용을 가져옵니다(
workspaceSlug : 문자열 요청, repoSlug : 문자열 요청, filePath : 문자열 요청, revision : 문자열 선택). 사용: 특정 파일 보기. - bb_diff_branches : 브랜치 간 차이점을 표시합니다(
workspaceSlug : 문자열 요청, repoSlug : 문자열 요청, sourceBranch : 문자열 요청, targetBranch : 문자열 요청). 용도: 브랜치를 비교합니다. - bb_diff_commits : 커밋 간의 차이점을 표시합니다(
workspaceSlug : 문자열 요청, repoSlug : 문자열 요청, sourceCommit : 문자열 요청, targetCommit : 문자열 요청). 용도: 커밋을 비교합니다. - bb_list_branches : 브랜치를 나열합니다(
workspaceSlug : str req, repoSlug : str req, query : str opt, sort : str opt). 용도: 모든 브랜치를 봅니다.
bb_ls_workspaces
모든 작업 공간 나열:
검색 작업 공간:
bb_get_workspace
작업 공간 세부 정보 가져오기:
{ "workspaceSlug": "acme-corp" }
bb_ls_repos
작업 공간에 저장소 나열:
{ "workspaceSlug": "acme-corp", "projectKey": "PROJ" }
기본 작업 공간을 사용하여 저장소 나열:
bb_get_repo
저장소 세부 정보 가져오기:
{ "workspaceSlug": "acme-corp", "repoSlug": "backend-api" }
bb_search
검색 코드:
{
"workspaceSlug": "acme-corp",
"query": "Logger",
"scope": "code",
"language": "typescript"
}
bb_ls_prs
공개 PR 목록:
{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "state": "OPEN" }
bb_get_pr
PR 세부 정보 받기:
{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "prId": "42" }
PR 코멘트 목록:
{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "prId": "42" }
일반적인 의견 추가:
{
"workspaceSlug": "acme-corp",
"repoSlug": "frontend-app",
"prId": "42",
"content": "Looks good."
}
인라인 주석 추가:
{
"workspaceSlug": "acme-corp",
"repoSlug": "frontend-app",
"prId": "42",
"content": "Consider refactoring.",
"inline": { "path": "src/utils.js", "line": 42 }
}
bb_add_pr
풀 리퀘스트 생성:
{
"workspaceSlug": "acme-corp",
"repoSlug": "frontend-app",
"title": "Add login screen",
"sourceBranch": "feature/login"
}
bb_add_branch
새로운 지점 만들기:
{
"workspaceSlug": "acme-corp",
"repoSlug": "frontend-app",
"newBranchName": "feature/new-feature",
"sourceBranchOrCommit": "main"
}
bb_clone_repo
복제 저장소:
{
"workspaceSlug": "acme-corp",
"repoSlug": "backend-api",
"targetPath": "/Users/me/projects"
}
bb_get_commit_history
커밋 기록 보기:
{
"workspaceSlug": "acme-corp",
"repoSlug": "backend-api"
}
필터링된 커밋 기록:
{
"workspaceSlug": "acme-corp",
"repoSlug": "backend-api",
"revision": "develop",
"path": "src/main/java/com/acme/service/UserService.java"
}
bb_get_file
파일 내용 가져오기:
{
"workspaceSlug": "acme-corp",
"repoSlug": "backend-api",
"filePath": "src/main/java/com/acme/service/Application.java",
"revision": "main"
}
bb_diff_branches
지점 비교:
{
"workspaceSlug": "acme-corp",
"repoSlug": "web-app",
"sourceBranch": "develop",
"targetBranch": "main"
}
bb_diff_commits
커밋 비교:
{
"workspaceSlug": "acme-corp",
"repoSlug": "web-app",
"sourceCommit": "a1b2c3d",
"targetCommit": "e4f5g6h"
}
bb_list_branches
모든 지점 나열:
{
"workspaceSlug": "acme-corp",
"repoSlug": "frontend-app"
}
필터링된 브랜치:
{
"workspaceSlug": "acme-corp",
"repoSlug": "frontend-app",
"query": "feature/",
"sort": "name"
}
CLI 명령
CLI 명령은 kebab-case 사용합니다. 자세한 내용을 보려면 --help 실행하세요(예: mcp-atlassian-bitbucket ls-workspaces --help ).
- ls-workspaces : 작업 공간을 나열합니다(
--query ). 예: mcp-atlassian-bitbucket ls-workspaces . - get-workspace : 작업 공간 세부 정보를 가져옵니다(
--workspace-slug ). 예: mcp-atlassian-bitbucket get-workspace --workspace-slug acme-corp . - ls-repos : 저장소를 나열합니다(
--workspace-slug , --project-key , --query ). 예: mcp-atlassian-bitbucket ls-repos --workspace-slug acme-corp . - get-repo : 리포 세부 정보를 가져옵니다(
--workspace-slug , --repo-slug ). 예: mcp-atlassian-bitbucket get-repo --workspace-slug acme-corp --repo-slug backend-api . - 검색 : 코드 검색(
--workspace-slug , --query , --scope , --language ). 예: mcp-atlassian-bitbucket search --workspace-slug acme-corp --query "auth" . - ls-prs : PR을 나열합니다(
--workspace-slug , --repo-slug , --state ). 예: mcp-atlassian-bitbucket ls-prs --workspace-slug acme-corp --repo-slug backend-api . - get-pr : PR 세부 정보를 가져옵니다(
--workspace-slug , --repo-slug , --pr-id ). 예: mcp-atlassian-bitbucket get-pr --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 . - ls-pr-comments : PR 주석을 나열합니다(
--workspace-slug , --repo-slug , --pr-id ). 예: mcp-atlassian-bitbucket ls-pr-comments --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 . - add-pr-comment : PR 주석을 추가합니다(
--workspace-slug , --repo-slug , --pr-id , --content ). 예: mcp-atlassian-bitbucket add-pr-comment --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 --content "Looks good" . - add-pr : PR을 생성합니다(
--workspace-slug , --repo-slug , --title , --source-branch ). 예: mcp-atlassian-bitbucket add-pr --workspace-slug acme-corp --repo-slug backend-api --title "New feature" --source-branch feature/login . - get-file : 파일 내용을 가져옵니다(
--workspace-slug , --repo-slug , --file-path ). 예: mcp-atlassian-bitbucket get-file --workspace-slug acme-corp --repo-slug backend-api --file-path src/main.js . - add-branch : 브랜치를 생성합니다(
--workspace-slug , --repo-slug , --new-branch-name ). 예: mcp-atlassian-bitbucket add-branch --workspace-slug acme-corp --repo-slug backend-api --new-branch-name feature/new .
작업 공간/저장소 목록 및 보기
# List all workspaces
mcp-atlassian-bitbucket ls-workspaces
# Get details of a specific workspace
mcp-atlassian-bitbucket get-workspace --workspace-slug acme-corp
# List repositories in a workspace
mcp-atlassian-bitbucket ls-repos --workspace-slug acme-corp --project-key PROJ
# Get details of a specific repository
mcp-atlassian-bitbucket get-repo --workspace-slug acme-corp --repo-slug backend-api
풀 리퀘스트 작업
# List open pull requests in a repository
mcp-atlassian-bitbucket ls-prs --workspace-slug acme-corp --repo-slug frontend-app --state OPEN
# Get details of a specific pull request with code changes
mcp-atlassian-bitbucket get-pr --workspace-slug acme-corp --repo-slug frontend-app --pr-id 42
# List comments on a pull request
mcp-atlassian-bitbucket ls-pr-comments --workspace-slug acme-corp --repo-slug frontend-app --pr-id 42
# Add a comment to a pull request
mcp-atlassian-bitbucket add-pr-comment --workspace-slug acme-corp --repo-slug frontend-app --pr-id 42 --content "Looks good to merge."
# Create a new pull request
mcp-atlassian-bitbucket add-pr --workspace-slug acme-corp --repo-slug frontend-app --title "Add login screen" --source-branch feature/login
코드 및 커밋
# Search for code
mcp-atlassian-bitbucket search --workspace-slug acme-corp --query "Logger" --scope code --language typescript
# View commit history
mcp-atlassian-bitbucket get-commit-history --workspace-slug acme-corp --repo-slug backend-api --revision develop
# Get file content
mcp-atlassian-bitbucket get-file --workspace-slug acme-corp --repo-slug backend-api --file-path "src/Application.java" --revision main
# Compare branches
mcp-atlassian-bitbucket diff-branches --workspace-slug acme-corp --repo-slug web-app --source-branch develop --target-branch main
# Compare commits
mcp-atlassian-bitbucket diff-commits --workspace-slug acme-corp --repo-slug web-app --source-commit a1b2c3d --target-commit e4f5g6h
지점 관리
# List branches
mcp-atlassian-bitbucket list-branches --workspace-slug acme-corp --repo-slug frontend-app --query "feature/" --sort name
# Create a new branch
mcp-atlassian-bitbucket add-branch --workspace-slug acme-corp --repo-slug frontend-app --new-branch-name feature/new-feature --source-branch-or-commit main
# Clone a repository
mcp-atlassian-bitbucket clone --workspace-slug acme-corp --repo-slug backend-api --target-path ./cloned-projects
응답 형식
모든 응답은 다음을 포함하여 Markdown 형식으로 작성됩니다.
- 제목 : 수행된 작업 또는 본 엔터티.
- 컨텍스트 : 작업 공간, 저장소, 풀 리퀘스트 또는 브랜치 정보.
- 콘텐츠 : 파일 콘텐츠, PR 세부 정보 또는 검색 결과와 같은 기본 데이터입니다.
- 메타데이터 : 타임스탬프, 작성자, 통계.
- Diffs : 브랜치/커밋 간 diff에 대한 구문 강조 표시와 함께 코드가 변경됩니다.
저장소 세부 정보
# Repository: backend-api
**Workspace:** acme-corp
**Full Name:** acme-corp/backend-api
**Language:** Java
**Created:** 2024-01-15 by John Smith
**Updated:** 2025-05-10 (2 days ago)
## Overview
Spring Boot backend API for the ACME product suite.
## Statistics
- **Default Branch:** main
- **Size:** 24.5 MB
- **Commits:** 358
- **Open PRs:** 4
- **Forks:** 3
## Recent Activity
- PR #42: "Add OAuth2 support" by Jane Doe (Open)
- PR #41: "Fix pagination bug" by Alex Kim (Merged)
- PR #40: "Update dependencies" by John Smith (Merged)
*Repository URL: https://bitbucket.org/acme-corp/backend-api*
풀 리퀘스트 검토
# Pull Request #42: Add OAuth2 support
**Repository:** acme-corp/backend-api
**Author:** Jane Doe
**State:** OPEN
**Created:** 2025-05-15 (4 days ago)
**Updated:** 2025-05-18 (yesterday)
## Description
Implements OAuth2 authentication flow with support for:
- Authorization code grant
- Refresh tokens
- Token caching
## Changes
- **Files changed:** 7
- **Additions:** 245 lines
- **Deletions:** 32 lines
## Diff for src/auth/OAuthService.java
@@ -10,6 +10,25 @@ public class OAuthService {
private final TokenRepository tokenRepository;
private final HttpClient httpClient;
+ @Autowired
+ public OAuthService(
+ TokenRepository tokenRepository,
+ HttpClient httpClient) {
+ this.tokenRepository = tokenRepository;
+ this.httpClient = httpClient;
+ }
+
+ public TokenResponse refreshToken(String refreshToken) {
+ // Validate refresh token
+ if (StringUtils.isEmpty(refreshToken)) {
+ throw new InvalidTokenException("Refresh token cannot be empty");
+ }
+
+ // Call OAuth server for new access token
+ return httpClient.post("/oauth/token")
+ .body(Map.of("grant_type", "refresh_token", "refresh_token", refreshToken))
+ .execute()
+ .as(TokenResponse.class);
+ }
## Comments (3)
1. **John Smith** (2 days ago):
> Please add unit tests for the refresh token flow
2. **Jane Doe** (yesterday):
> Added tests in the latest commit
3. **Approval by:** Alex Kim (yesterday)
*Pull Request URL: https://bitbucket.org/acme-corp/backend-api/pull-requests/42*
개발
# Clone repository
git clone https://github.com/aashari/mcp-server-atlassian-bitbucket.git
cd mcp-server-atlassian-bitbucket
# Install dependencies
npm install
# Run in development mode
npm run dev:server
# Run tests
npm test
기여하다
기여를 환영합니다! 다음 내용을 알려주세요.
- 저장소를 포크합니다.
- 기능 브랜치를 생성합니다(
git checkout -b feature/xyz ). - 변경 사항 커밋(
git commit -m "Add xyz feature" ) - 브랜치에 푸시합니다(
git push origin feature/xyz ). - 풀 리퀘스트를 엽니다.
자세한 내용은 CONTRIBUTING.md를 참조하세요.
특허
ISC 라이센스