Atlassian Bitbucket MCP Server
Atlassian Bitbucket MCP 서버
Atlassian Bitbucket Cloud용 Node.js/TypeScript 모델 컨텍스트 프로토콜(MCP) 서버입니다. AI 시스템(예: Claude 또는 Cursor AI와 같은 LLM)이 저장소, 풀 리퀘스트, 작업 공간 및 코드와 실시간으로 안전하게 상호 작용할 수 있도록 지원합니다.
왜 이 서버를 사용해야 하나요?
최소 입력, 최대 출력 : 간단한 식별자는 추가 플래그가 필요하지 않고 포괄적인 세부 정보를 제공합니다.
풍부한 코드 시각화 : 파일 통계, 차이점 보기, 스마트 컨텍스트를 통해 코드 변경 사항에 대한 자세한 통찰력을 얻으세요.
안전한 로컬 인증 : 자격 증명을 사용하여 로컬에서 실행하고, 원격 서버에 토큰을 저장하지 않습니다.
직관적인 마크다운 응답 : 모든 출력에 대해 잘 구성되고 일관된 마크다운 형식이 적용됩니다.
Bitbucket 전체 통합 : 작업 공간, 저장소, 풀 리퀘스트, 댓글, 코드 검색 등에 액세스하세요.
Related MCP server: Atlassian Bitbucket MCP Server
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-workspaces4단계: 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
모든 작업 공간 나열:
{}검색 작업 공간:
{ "query": "devteam" }bb_get_workspace
작업 공간 세부 정보 가져오기:
{ "workspaceSlug": "acme-corp" }bb_ls_repos
작업 공간에 저장소 나열:
{ "workspaceSlug": "acme-corp", "projectKey": "PROJ" }기본 작업 공간을 사용하여 저장소 나열:
{ "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" }bb_ls_pr_comments
PR 코멘트 목록:
{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "prId": "42" }bb_add_pr_comment
일반적인 의견 추가:
{
"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를 참조하세요.
특허
Available Tools
6 toolsbb_cloneClone Bitbucket RepositoryA
Clone a Bitbucket repository to your local filesystem using SSH (preferred) or HTTPS.
Provide repoSlug and targetPath (absolute path). Clones into targetPath/repoSlug. SSH keys must be configured; falls back to HTTPS if unavailable.
| Name | Required | Description | Default |
|---|---|---|---|
| workspaceSlug | No | Bitbucket workspace slug containing the repository. If not provided, the tool will use your default workspace (either configured via BITBUCKET_DEFAULT_WORKSPACE or the first workspace in your account). Example: "myteam" | |
| repoSlug | Yes | Repository name/slug to clone. This is the short name of the repository. Example: "project-api" | |
| targetPath | Yes | Directory path where the repository will be cloned. IMPORTANT: Absolute paths are strongly recommended (e.g., "/home/user/projects" or "C:\Users\name\projects"). Relative paths will be resolved relative to the server's working directory, which may not be what you expect. The repository will be cloned into a subdirectory at targetPath/repoSlug. Make sure you have write permissions to this location. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive. Description adds behavioral details like default clone directory and fallback mechanism. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with core purpose, no redundancy. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key points for a simple clone operation. No output schema, but return value is likely a confirmation. Could mention error handling (e.g., if path exists), but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. Description reinforces targetPath behavior (absolute path suggested, subdirectory creation) and optional workspaceSlug usage, adding practical meaning beyond raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action 'Clone a Bitbucket repository' and destination 'local filesystem', distinguishing it from sibling CRUD tools (bb_get, bb_post, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on required parameters (repoSlug, targetPath), path behavior (clones into targetPath/repoSlug), and authentication precedence (SSH preferred, falls back to HTTPS). No explicit when-not-to-use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bb_deleteBitbucket DELETE RequestADestructiveIdempotent
Delete Bitbucket resources. Returns TOON format by default.
Output format: TOON (default) or JSON (outputFormat: "json")
Common operations:
Delete branch:
/repositories/{workspace}/{repo}/refs/branches/{branch_name}Delete PR comment:
/repositories/{workspace}/{repo}/pullrequests/{pr_id}/comments/{comment_id}Decline PR:
/repositories/{workspace}/{repo}/pullrequests/{id}/declineRemove PR approval:
/repositories/{workspace}/{repo}/pullrequests/{id}/approveDelete repository:
/repositories/{workspace}/{repo}(caution: irreversible)
Note: Most DELETE endpoints return 204 No Content on success.
The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}" | |
| queryParams | No | Optional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"} | |
| jq | No | JMESPath expression to filter/transform the response. IMPORTANT: Always use this to extract only needed fields and reduce token costs. Examples: "values[*].{name: name, slug: slug}" (extract specific fields), "values[0]" (first result), "values[*].name" (names only). See https://jmespath.org | |
| outputFormat | No | Output format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by noting the default TOON output format, typical 204 No Content response, and the irreversible nature of deleting a repository. These details help the agent understand behavior without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, front-loaded purpose, and relevant examples. It is concise without being overly terse, though minor repetition ('Returns TOON format by default') could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, no output schema), the description adequately covers output format, common operations, and parameter usage. It references an external API documentation link for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description enriches parameters with practical examples (e.g., queryParams, jq expressions, outputFormat enum values) that go beyond the schema's basic descriptions, aiding correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete Bitbucket resources' and lists specific common operations (delete branch, PR comment, decline PR, etc.), which distinguishes it from sibling tools (bb_get, bb_post, etc.) that have different HTTP methods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description provides a list of common operations and a caution about irreversibility for deleting repositories, it lacks explicit guidance on when to use this tool versus alternatives beyond the implied HTTP method differences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bb_getBitbucket GET RequestARead-onlyIdempotent
Read any Bitbucket data. Returns TOON format by default (30-60% fewer tokens than JSON).
IMPORTANT - Cost Optimization:
ALWAYS use
jqparam to filter response fields. Unfiltered responses are very expensive!Use
pagelenquery param to restrict result count (e.g.,pagelen: "5")If unsure about available fields, first fetch ONE item with
pagelen: "1"and NO jq filter to explore the schema, then use jq in subsequent calls
Schema Discovery Pattern:
First call:
path: "/workspaces", queryParams: {"pagelen": "1"}(no jq) - explore available fieldsThen use:
jq: "values[*].{slug: slug, name: name, uuid: uuid}"- extract only what you need
Output format: TOON (default, token-efficient) or JSON (outputFormat: "json")
Common paths:
/workspaces- list workspaces/repositories/{workspace}- list repos in workspace/repositories/{workspace}/{repo}- get repo details/repositories/{workspace}/{repo}/pullrequests- list PRs/repositories/{workspace}/{repo}/pullrequests/{id}- get PR details/repositories/{workspace}/{repo}/pullrequests/{id}/comments- list PR comments/repositories/{workspace}/{repo}/pullrequests/{id}/diff- get PR diff/repositories/{workspace}/{repo}/refs/branches- list branches/repositories/{workspace}/{repo}/commits- list commits/repositories/{workspace}/{repo}/src/{commit}/{filepath}- get file content/repositories/{workspace}/{repo}/diff/{source}..{destination}- compare branches/commits
Query params: pagelen (page size), page (page number), q (filter), sort (order), fields (sparse response)
Example filters (q param): state="OPEN", source.branch.name="feature", title~"bug"
JQ examples: values[*].slug, values[0], values[*].{name: name, uuid: uuid}
The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}" | |
| queryParams | No | Optional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"} | |
| jq | No | JMESPath expression to filter/transform the response. IMPORTANT: Always use this to extract only needed fields and reduce token costs. Examples: "values[*].{name: name, slug: slug}" (extract specific fields), "values[0]" (first result), "values[*].name" (names only). See https://jmespath.org | |
| outputFormat | No | Output format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true. Description adds value by detailing default TOON format (token-efficient), automatic /2.0 prefix, and schema discovery pattern. No contradictions. Could mention pagination limits or error responses but still robust.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (Important, Schema Discovery, Common paths, etc.) and front-loaded with key guidance. Length is justified by the complexity of the Bitbucket API, but some redundancy in examples could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with no output schema, the description fully compensates by explaining output format, common paths, filters, and a discovery pattern. Covers all practical aspects an agent needs to invoke the tool correctly against Bitbucket API.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. The description adds extensive examples (e.g., query param examples, jq expressions, outputFormat enum), providing meaning beyond the schema. More than baseline 3 due to rich contextualization.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read any Bitbucket data' and emphasizes read-only nature with a list of common paths. It distinguishes from sibling write tools (bb_delete, bb_post, etc.) by specifying reading operations only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit cost optimization guidelines: always use jq filter, use pagelen to limit results, and a schema discovery pattern. Also gives common paths and example filters, leaving no doubt when to use this read tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bb_patchBitbucket PATCH RequestA
Partially update Bitbucket resources. Returns TOON format by default.
IMPORTANT - Cost Optimization: Use jq param to filter response fields.
Output format: TOON (default) or JSON (outputFormat: "json")
Common operations:
Update PR title/description:
/repositories/{workspace}/{repo}/pullrequests/{id}body:{"title": "New title", "description": "Updated description"}Update PR reviewers:
/repositories/{workspace}/{repo}/pullrequests/{id}body:{"reviewers": [{"uuid": "{user-uuid}"}]}Update repository properties:
/repositories/{workspace}/{repo}body:{"description": "New description"}Update comment:
/repositories/{workspace}/{repo}/pullrequests/{pr_id}/comments/{comment_id}body:{"content": {"raw": "Updated comment"}}
The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}" | |
| queryParams | No | Optional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"} | |
| jq | No | JMESPath expression to filter/transform the response. IMPORTANT: Always use this to extract only needed fields and reduce token costs. Examples: "values[*].{name: name, slug: slug}" (extract specific fields), "values[0]" (first result), "values[*].name" (names only). See https://jmespath.org | |
| outputFormat | No | Output format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax. | |
| body | Yes | Request body as a JSON object. Structure depends on the endpoint. Example for PR: {"title": "My PR", "source": {"branch": {"name": "feature"}}} |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true. The description adds valuable context: default TOON output format, cost optimization via jq param, and examples of common operations. It does not disclose error behavior or permission requirements, but the added details are useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, cost optimization note, output format info, and bulleted examples. It is moderately concise but could be trimmed slightly without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters with 100% schema coverage and no output schema, the description covers essential usage patterns and output format. It lacks details on error handling or rate limits, but provides sufficient context for typical PATCH operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description enhances understanding by providing concrete examples for each parameter (e.g., path examples, queryParams usage, jq expressions, body structures for PR updates). This goes beyond schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Partially update Bitbucket resources' and provides specific examples of common operations (e.g., updating PR title, reviewers, repository properties). The verb 'patch' and examples distinguish it effectively from siblings (clone, delete, get, post, put).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for partial updates via examples and contrasts with full updates (PUT) implicitly. However, it lacks explicit guidance on when to use this tool versus alternatives like bb_put, and does not mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bb_postBitbucket POST RequestA
Create Bitbucket resources. Returns TOON format by default (token-efficient).
IMPORTANT - Cost Optimization:
Use
jqparam to extract only needed fields from response (e.g.,jq: "{id: id, title: title}")Unfiltered responses include all metadata and are expensive!
Output format: TOON (default) or JSON (outputFormat: "json")
Common operations:
Create PR:
/repositories/{workspace}/{repo}/pullrequestsbody:{"title": "...", "source": {"branch": {"name": "feature"}}, "destination": {"branch": {"name": "main"}}}Add PR comment:
/repositories/{workspace}/{repo}/pullrequests/{id}/commentsbody:{"content": {"raw": "Comment text"}}Approve PR:
/repositories/{workspace}/{repo}/pullrequests/{id}/approvebody:{}Request changes:
/repositories/{workspace}/{repo}/pullrequests/{id}/request-changesbody:{}Merge PR:
/repositories/{workspace}/{repo}/pullrequests/{id}/mergebody:{"merge_strategy": "squash"}(strategies: merge_commit, squash, fast_forward)
The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}" | |
| queryParams | No | Optional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"} | |
| jq | No | JMESPath expression to filter/transform the response. IMPORTANT: Always use this to extract only needed fields and reduce token costs. Examples: "values[*].{name: name, slug: slug}" (extract specific fields), "values[0]" (first result), "values[*].name" (names only). See https://jmespath.org | |
| outputFormat | No | Output format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax. | |
| body | Yes | Request body as a JSON object. Structure depends on the endpoint. Example for PR: {"title": "My PR", "source": {"branch": {"name": "feature"}}} |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses behavioral traits: default TOON format, cost optimization via jq, auto-added /2.0 prefix, and output format options. It aligns with annotations (not read-only, not destructive, not idempotent, open-world hint) and adds significant context beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, important cost optimization note, and a list of common operations. It is slightly verbose but front-loaded with key information, making it efficient for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 5 parameters, nested objects, and no output schema, the description is remarkably complete: it covers output formats, cost optimization, common endpoint patterns, and links to the full API reference. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema description coverage, the description adds substantial meaning: detailed path examples, jq usage with examples, outputFormat benefits, body structure examples for common endpoints. This greatly aids parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create Bitbucket resources' and provides multiple specific endpoint examples (create PR, add comment, approve, etc.), distinguishing it from sibling tools that handle other HTTP methods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (creating resources) and provides common operations with endpoint and body examples. It lacks explicit when-not-to-use or alternative tool references, but the context signals and sibling tool list imply the usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
bb_putBitbucket PUT RequestAIdempotent
Replace Bitbucket resources (full update). Returns TOON format by default.
IMPORTANT - Cost Optimization:
Use
jqparam to extract only needed fields from responseExample:
jq: "{uuid: uuid, name: name}"
Output format: TOON (default) or JSON (outputFormat: "json")
Common operations:
Update repository:
/repositories/{workspace}/{repo}body:{"description": "...", "is_private": true, "has_issues": true}Create/update file:
/repositories/{workspace}/{repo}/srcNote: Use multipart form data for file uploads (complex - prefer PATCH for metadata)Update branch restriction:
/repositories/{workspace}/{repo}/branch-restrictions/{id}body:{"kind": "push", "pattern": "main", "users": [{"uuid": "..."}]}
The /2.0 prefix is added automatically. API reference: https://developer.atlassian.com/cloud/bitbucket/rest/
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}" | |
| queryParams | No | Optional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"} | |
| jq | No | JMESPath expression to filter/transform the response. IMPORTANT: Always use this to extract only needed fields and reduce token costs. Examples: "values[*].{name: name, slug: slug}" (extract specific fields), "values[0]" (first result), "values[*].name" (names only). See https://jmespath.org | |
| outputFormat | No | Output format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax. | |
| body | Yes | Request body as a JSON object. Structure depends on the endpoint. Example for PR: {"title": "My PR", "source": {"branch": {"name": "feature"}}} |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, describes default TOON output format, automatic /2.0 prefix, and cost optimization behavior. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, but slightly verbose. Front-loaded with purpose and important notes. Could trim some redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main usage patterns and cost optimization. Lacks explicit error handling or response structure details, but examples and reference link partially compensate. Good for a mutation tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have schema descriptions, and the tool description adds context: path format, jq usage examples, outputFormat enum explanation, and body structure examples. Significantly enhances schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it is for 'Replace Bitbucket resources (full update).' Distinguishes from sibling tools (bb_patch for partial updates) and provides common operation examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends using PATCH for metadata when updating files, provides cost optimization tips (jq param), and lists specific common operations with endpoints and request bodies. Clearly guides when and how to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
26 tool updates
v1.43.1- Removed
bb_add_branch - Removed
bb_add_pr - Removed
bb_add_pr_comment - Removed
bb_approve_pr - Added
bb_clone - Removed
bb_clone_repo - Added
bb_delete - Removed
bb_diff_branches - Removed
bb_diff_commits - Added
bb_get - Removed
bb_get_commit_history - Removed
bb_get_file - Removed
bb_get_pr - Removed
bb_get_repo - Removed
bb_get_workspace - Removed
bb_list_branches - Removed
bb_ls_pr_comments - Removed
bb_ls_prs - Removed
bb_ls_repos - Removed
bb_ls_workspaces - Added
bb_patch - Added
bb_post - Added
bb_put - Removed
bb_reject_pr - Removed
bb_search - Removed
bb_update_pr
TDQS
Scored across 6 tools
Each tool corresponds to a distinct HTTP method (or clone operation) with clear purposes: clone for local cloning, delete for deletions, get for reads, patch for partial updates, post for creations, and put for full replacements. There is no overlap.
All tools follow a consistent 'bb_<verb>' pattern using HTTP method names (clone, delete, get, patch, post, put). The naming is predictable and uniform.
With 6 tools, the server provides a concise CRUD+L (clone) interface for Bitbucket. This is well-scoped for a MCP server; each tool has a clear role without unnecessary bloat.
The tools cover all standard CRUD operations plus cloning. However, specific workflows like merging or approving PRs are handled via generic post/put, which may require agents to construct endpoint paths. A dedicated tool for common composite operations could improve completeness slightly.
Maintenance
Related MCP Connectors
Connect your team's living knowledge base — docs, data, issues, CRM — to Claude and ChatGPT.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
One workspace of tools for Claude and ChatGPT: connect 600+ apps, generate media, build tools.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to interact with Bitbucket Cloud repositories, allowing users to manage pull requests, comments, tasks, and branches through natural language commands.3,208 npm1MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to interact with Bitbucket Cloud and self-hosted instances for pull request reviews, code search, repository operations, and managing PR comments and approvals.19GPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to programmatically manage Bitbucket Cloud resources, including pull requests, repositories, and branches, automating code review workflows.11 npmMIT
- AlicenseBqualityAmaintenanceEnables AI assistants to manage Bitbucket Cloud repositories, pull requests, pipelines, and code review tasks through natural language.743MIT
Appeared in Searches
- A server for finding information about Bitbucket, the Git repository hosting service
- Guide to connecting to Bitbucket Data Center
- Bitbucket pull request reviewer information
- Bitbucket integration for CursorAI to manage repositories and pull requests
- Bitbucket integration for repository and pull request management