Skip to main content
Glama
aashari

Atlassian Bitbucket MCP Server

by aashari

Atlassian Bitbucket MCP サーバー

Atlassian Bitbucket Cloud 用の Node.js/TypeScript Model Context Protocol (MCP) サーバー。AI システム (Claude や Cursor AI などの LLM など) がリポジトリ、プルリクエスト、ワークスペース、コードとリアルタイムかつ安全にやり取りできるようにします。

NPMバージョン ビルドステータス

このサーバーを使用する理由

  • 最小限の入力、最大限の出力: シンプルな識別子により、追加のフラグを必要とせずに包括的な詳細が提供されます。

  • 豊富なコードの視覚化: ファイル統計、差分ビュー、スマート コンテキストを使用して、コードの変更に関する詳細な情報を取得します。

  • 安全なローカル認証: 資格情報を使用してローカルで実行し、トークンをリモート サーバーに保存することはありません。

  • 直感的な Markdown 応答: すべての出力に対して、適切に構造化された一貫した Markdown 形式が採用されています。

  • 完全な Bitbucket 統合: ワークスペース、リポジトリ、プル リクエスト、コメント、コード検索などにアクセスできます。

Related MCP server: Atlassian Bitbucket MCP Server

MCPとは何ですか?

モデルコンテキストプロトコル(MCP)は、AIシステムを外部ツールやデータソースに安全に接続するためのオープンスタンダードです。このサーバーはBitbucket Cloud向けにMCPを実装しており、AIアシスタントがBitbucketデータをプログラムで操作できるようにします。

前提条件

設定

ステップ1: 認証

次のいずれかの認証方法を選択します。

オプション A: Bitbucket アプリのパスワード (推奨)

Bitbucket App Passwordsから生成します。最小権限:

  • ワークスペース: 読み取り

  • リポジトリ: 読む

  • プルリクエスト: 読む

明示的に指定されていない場合にデフォルトのワークスペースを指定するには、 BITBUCKET_DEFAULT_WORKSPACEを設定することもできます。

オプションB: Atlassian APIトークン

Atlassian API トークンから生成します。

注: Bitbucket アプリ パスワードは、より詳細な Bitbucket 固有の権限を提供するため、強くお勧めします。

ステップ2: 資格情報を構成する

オプション A: MCP 構成ファイル (推奨)

~/.mcp/configs.jsonを編集または作成します。

Bitbucket アプリパスワードの使用:

{
	"bitbucket": {
		"environments": {
			"ATLASSIAN_BITBUCKET_USERNAME": "<your_username>",
			"ATLASSIAN_BITBUCKET_APP_PASSWORD": "<your_app_password>"
		}
	}
}

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アシスタントに接続する

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 : 文字列が必要です)。用途: ワークスペース情報を表示します。

  • 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 req、 repoSlug : str req、 state : str opt)。用途: オープンまたはマージされたPRを表示します。

  • bb_get_pr : PRの詳細を取得します( workspaceSlug : 文字列必須、 repoSlug : 文字列必須、 prId : 文字列必須)。使用方法: 差分を含む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 : str req、 repoSlug : str req、 title : str req、 sourceBranch : str req、 targetBranch : str opt)。使用方法: 新しい 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 : str req、 repoSlug : str req、 filePath : str req、 revision : str opt)。使用方法: 特定のファイルを表示します。

  • bb_diff_branches : ブランチ間の差分を表示します( workspaceSlug : str req、 repoSlug : str req、 sourceBranch : str req、 targetBranch : str req)。用途: ブランチを比較します。

  • bb_diff_commits : コミット間の差分を表示します( workspaceSlug : str req、 repoSlug : str req、 sourceCommit : str req、 targetCommit : str req)。用途: コミットを比較します。

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

検索コード:

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

  • search : コードを検索します ( --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 の詳細、検索結果などの主要データ。

  • メタデータ: タイムスタンプ、作成者、統計。

  • 差分: ブランチ/コミット間の差分の構文強調表示によるコード変更。

リポジトリの詳細

# 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

貢献

貢献を歓迎します!ご協力をお願いします:

  1. リポジトリをフォークします。

  2. 機能ブランチを作成します ( git checkout -b feature/xyz )。

  3. 変更をコミットします ( git commit -m "Add xyz feature" )。

  4. ブランチにプッシュします ( git push origin feature/xyz )。

  5. プルリクエストを開きます。

詳細については、 CONTRIBUTING.md を参照してください。

ライセンス

ISCライセンス

Available Tools

6 tools
bb_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.

ParametersJSON Schema
NameRequiredDescriptionDefault
workspaceSlugNoBitbucket 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"
repoSlugYesRepository name/slug to clone. This is the short name of the repository. Example: "project-api"
targetPathYesDirectory 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

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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 RequestA
DestructiveIdempotent

Delete Bitbucket resources. Returns TOON format by default.

Output format: TOON (default) or JSON (outputFormat: "json")

Common operations:

  1. Delete branch: /repositories/{workspace}/{repo}/refs/branches/{branch_name}

  2. Delete PR comment: /repositories/{workspace}/{repo}/pullrequests/{pr_id}/comments/{comment_id}

  3. Decline PR: /repositories/{workspace}/{repo}/pullrequests/{id}/decline

  4. Remove PR approval: /repositories/{workspace}/{repo}/pullrequests/{id}/approve

  5. Delete 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/

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}"
queryParamsNoOptional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"}
jqNoJMESPath 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
outputFormatNoOutput format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax.

TDQS

A4.1/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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 RequestA
Read-onlyIdempotent

Read any Bitbucket data. Returns TOON format by default (30-60% fewer tokens than JSON).

IMPORTANT - Cost Optimization:

  • ALWAYS use jq param to filter response fields. Unfiltered responses are very expensive!

  • Use pagelen query 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:

  1. First call: path: "/workspaces", queryParams: {"pagelen": "1"} (no jq) - explore available fields

  2. Then 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/

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}"
queryParamsNoOptional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"}
jqNoJMESPath 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
outputFormatNoOutput format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax.

TDQS

A4.6/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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:

  1. Update PR title/description: /repositories/{workspace}/{repo}/pullrequests/{id} body: {"title": "New title", "description": "Updated description"}

  2. Update PR reviewers: /repositories/{workspace}/{repo}/pullrequests/{id} body: {"reviewers": [{"uuid": "{user-uuid}"}]}

  3. Update repository properties: /repositories/{workspace}/{repo} body: {"description": "New description"}

  4. 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/

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}"
queryParamsNoOptional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"}
jqNoJMESPath 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
outputFormatNoOutput format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax.
bodyYesRequest body as a JSON object. Structure depends on the endpoint. Example for PR: {"title": "My PR", "source": {"branch": {"name": "feature"}}}

TDQS

A4.3/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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 jq param 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:

  1. Create PR: /repositories/{workspace}/{repo}/pullrequests body: {"title": "...", "source": {"branch": {"name": "feature"}}, "destination": {"branch": {"name": "main"}}}

  2. Add PR comment: /repositories/{workspace}/{repo}/pullrequests/{id}/comments body: {"content": {"raw": "Comment text"}}

  3. Approve PR: /repositories/{workspace}/{repo}/pullrequests/{id}/approve body: {}

  4. Request changes: /repositories/{workspace}/{repo}/pullrequests/{id}/request-changes body: {}

  5. Merge PR: /repositories/{workspace}/{repo}/pullrequests/{id}/merge body: {"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/

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}"
queryParamsNoOptional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"}
jqNoJMESPath 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
outputFormatNoOutput format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax.
bodyYesRequest body as a JSON object. Structure depends on the endpoint. Example for PR: {"title": "My PR", "source": {"branch": {"name": "feature"}}}

TDQS

A4.7/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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 RequestA
Idempotent

Replace Bitbucket resources (full update). Returns TOON format by default.

IMPORTANT - Cost Optimization:

  • Use jq param to extract only needed fields from response

  • Example: jq: "{uuid: uuid, name: name}"

Output format: TOON (default) or JSON (outputFormat: "json")

Common operations:

  1. Update repository: /repositories/{workspace}/{repo} body: {"description": "...", "is_private": true, "has_issues": true}

  2. Create/update file: /repositories/{workspace}/{repo}/src Note: Use multipart form data for file uploads (complex - prefer PATCH for metadata)

  3. 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/

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesThe Bitbucket API endpoint path (without base URL). Must start with "/". Examples: "/workspaces", "/repositories/{workspace}/{repo_slug}", "/repositories/{workspace}/{repo_slug}/pullrequests/{id}"
queryParamsNoOptional query parameters as key-value pairs. Examples: {"pagelen": "25", "page": "2", "q": "state=\"OPEN\"", "fields": "values.title,values.state"}
jqNoJMESPath 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
outputFormatNoOutput format: "toon" (default, 30-60% fewer tokens) or "json". TOON is optimized for LLMs with tabular arrays and minimal syntax.
bodyYesRequest body as a JSON object. Structure depends on the endpoint. Example for PR: {"title": "My PR", "source": {"branch": {"name": "feature"}}}

TDQS

A4.8/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

  1. 26 tool updatesv1.43.1
    • Removedbb_add_branch
    • Removedbb_add_pr
    • Removedbb_add_pr_comment
    • Removedbb_approve_pr
    • Addedbb_clone
    • Removedbb_clone_repo
    • Addedbb_delete
    • Removedbb_diff_branches
    • Removedbb_diff_commits
    • Addedbb_get
    • Removedbb_get_commit_history
    • Removedbb_get_file
    • Removedbb_get_pr
    • Removedbb_get_repo
    • Removedbb_get_workspace
    • Removedbb_list_branches
    • Removedbb_ls_pr_comments
    • Removedbb_ls_prs
    • Removedbb_ls_repos
    • Removedbb_ls_workspaces
    • Addedbb_patch
    • Addedbb_post
    • Addedbb_put
    • Removedbb_reject_pr
    • Removedbb_search
    • Removedbb_update_pr

TDQS

A4.4/5.0

Scored across 6 tools

Disambiguation5/5

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.

Naming Consistency5/5

All tools follow a consistent 'bb_<verb>' pattern using HTTP method names (clone, delete, get, patch, post, put). The naming is predictable and uniform.

Tool Count5/5

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.

Completeness4/5

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

ActivityInactive
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI assistants to interact with Bitbucket Cloud repositories, allowing users to manage pull requests, comments, tasks, and branches through natural language commands.
    4,764 npm
    1
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to programmatically manage Bitbucket Cloud resources, including pull requests, repositories, and branches, automating code review workflows.
    11 npm
    MIT
  • A
    license
    A
    quality
    A
    maintenance
    Enables AI assistants to manage Bitbucket Cloud repositories, pull requests, pipelines, and code review tasks through natural language.
    74
    1,017 PyPI
    3
    MIT