de en es ja ko ru zh

Atlassian Bitbucket MCP Server

Name: Atlassian Bitbucket MCP Server
Author: aashari

by aashari

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

Atlassian Bitbucket MCP 服务器

适用于 Atlassian Bitbucket Cloud 的 Node.js/TypeScript 模型上下文协议 (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 数据进行交互。

先决条件

Node.js （>=18.x）：下载
Bitbucket 云帐户

设置

步骤 1：验证

选择以下身份验证方法之一：

选项 A：Bitbucket 应用程序密码（推荐）

从Bitbucket App Passwords生成一个。最低权限：

工作区：阅读
存储库：阅读
拉取请求：阅读

您还可以设置BITBUCKET_DEFAULT_WORKSPACE来指定未明确提供时的默认工作区。

选项 B：Atlassian API 令牌

从Atlassian API Tokens生成一个。

**注意：**强烈建议使用 Bitbucket App Passwords，因为它们提供更细粒度的、特定于 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 ：str req）。用途：查看工作区信息。
bb_ls_repos ：列出存储库（ workspaceSlug ：str opt， projectKey ：str opt， query ：str opt， role ：str opt）。用途：查找存储库。
bb_get_repo ：获取存储库详细信息（ workspaceSlug ：str req， repoSlug ：str req）。用途：访问存储库信息。
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 ：str req、 repoSlug ：str req、 prId ：str req）。用途：查看带有差异的 PR 详细信息。
bb_ls_pr_comments ：列出 PR 评论（ workspaceSlug ：str req、 repoSlug ：str req、 prId ：str req）。用途：查看 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 ：str req， repoSlug ：str req， targetPath ：str req）。用途：本地克隆代码。
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" }

`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 。
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

贡献

欢迎投稿！请：

分叉存储库。
创建功能分支（ git checkout -b feature/xyz ）。
提交更改（ git commit -m "Add xyz feature" ）。
推送到分支（ git push origin feature/xyz ）。
打开拉取请求。

有关详细信息，请参阅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

Name	Required	Description
`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

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:

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}/decline
Remove PR approval: /repositories/{workspace}/{repo}/pullrequests/{id}/approve
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

Name	Required	Description
`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

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:

First call: path: "/workspaces", queryParams: {"pagelen": "1"} (no jq) - explore available fields
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

Name	Required	Description
`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

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:

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/

ParametersJSON Schema

Name	Required	Description
`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

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:

Create PR: /repositories/{workspace}/{repo}/pullrequests body: {"title": "...", "source": {"branch": {"name": "feature"}}, "destination": {"branch": {"name": "main"}}}
Add PR comment: /repositories/{workspace}/{repo}/pullrequests/{id}/comments body: {"content": {"raw": "Comment text"}}
Approve PR: /repositories/{workspace}/{repo}/pullrequests/{id}/approve body: {}
Request changes: /repositories/{workspace}/{repo}/pullrequests/{id}/request-changes body: {}
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

Name	Required	Description
`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

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:

Update repository: /repositories/{workspace}/{repo} body: {"description": "...", "is_private": true, "has_issues": true}
Create/update file: /repositories/{workspace}/{repo}/src Note: 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/

ParametersJSON Schema

Name	Required	Description
`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

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.

26 tool updatesv1.43.1Apr 30, 2026
- 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

Deploy Server

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.4/5.0

Scored 2026-04-30 19:05 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

Resources

Need Help?

Related Servers

Related MCP Connectors

RootrOAuth
io.github.inspirio-co
Connect your team's living knowledge base — docs, data, issues, CRM — to Claude and ChatGPT.
RAG Systems Knowledge & Memory CRM
2
Hint-Services-obsidian-github-mcp
ai.smithery
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Note Taking Version Control File Systems
29
GitHubOAuth
io.github.github
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Version Control Developer Tools CI/CD & DevOps
1233,476
constantsOAuth
io.github.constants-ai
One workspace of tools for Claude and ChatGPT: connect 600+ apps, generate media, build tools.
App Automation Developer Tools Multimedia Processing
1

Related MCP Servers

Bitbucket MCP Server
Version Control Developer Tools
bobmaertz
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.
Updated 2 months ago (2026-08-01 15:49 UTC)
4,764 npm
1
MIT
Atlassian Bitbucket MCP Server
Version Control Developer Tools
RajuSudhar
A
license
B
quality
B
maintenance
Enables 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.
Updated a month ago (2026-09-01 10:55 UTC)
19
GPL 3.0
bitbucket-mcp
Version Control Developer Tools
yunusemregul
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.
Updated 2 months ago (2026-08-21 07:58 UTC)
11 npm
MIT
bitbucket-mcp
Version Control CI/CD & DevOps
lawp09
A
license
A
quality
A
maintenance
Enables AI assistants to manage Bitbucket Cloud repositories, pull requests, pipelines, and code review tasks through natural language.
Updated 3 days ago (2026-10-09 04:33 UTC)
74
1,017 PyPI
3
MIT

Atlassian Bitbucket MCP 服务器

为什么要使用此服务器？

什么是 MCP？

先决条件

设置

步骤 1：验证

选项 A：Bitbucket 应用程序密码（推荐）

选项 B：Atlassian API 令牌

第 2 步：配置凭证

选项 A：MCP 配置文件（推荐）

选项 B：环境变量

步骤3：安装并运行

npx快速入门

全局安装

步骤4：连接到AI助手

MCP 工具

bb_ls_workspaces

bb_get_workspace

bb_ls_repos

bb_get_repo

bb_search

bb_ls_prs

bb_get_pr

bb_ls_pr_comments

bb_add_pr_comment

bb_add_pr

bb_add_branch

bb_clone_repo

bb_get_commit_history

bb_get_file

bb_diff_branches

bb_diff_commits

bb_list_branches

CLI 命令

列出并查看工作区/存储库

使用拉取请求

代码和提交

分支机构管理

响应格式

存储库详细信息

拉取请求审查

发展

贡献

执照

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches

`npx`快速入门

`bb_ls_workspaces`

`bb_get_workspace`

`bb_ls_repos`

`bb_get_repo`

`bb_search`

`bb_ls_prs`

`bb_get_pr`

`bb_ls_pr_comments`

`bb_add_pr_comment`

`bb_add_pr`

`bb_add_branch`

`bb_clone_repo`

`bb_get_commit_history`

`bb_get_file`

`bb_diff_branches`

`bb_diff_commits`

`bb_list_branches`