Atlassian Bitbucket MCP Server

将AI连接到您的Bitbucket存储库

通过将Claude、Cursor AI和其他AI助手直接连接到您的存储库、拉取请求和代码，改变您使用Bitbucket的方式。获得即时洞察，自动化代码审查，并简化您的开发工作流程。

](https://www.npmjs.com/package/@aashari/mcp-server-atlassian-bitbucket) 

你能做什么

• 向AI询问你的代码：“我的主存储库中的最新提交是什么？”
• 获取公关见解：“显示所有需要审核的打开拉取请求”
• 搜索您的代码库：“查找所有使用身份验证功能的JavaScript文件”
• 审查代码更改：“比较我的功能分支和主分支之间的差异”
• 管理拉取请求：“为我的新功能分支创建PR”
• 自动化工作流程：“在PR#123中添加测试结果注释”

非常适合

• 开发者 谁希望AI在代码审查和存储库管理方面提供帮助
• 团队领导 需要快速了解项目状态和拉取请求活动
• DevOps工程师 自动化存储库工作流和分支管理
• 任何人 谁想用自然语言与Bitbucket交互

需求

• Node.js 18.0.0或更高
• 比特桶云 帐户（不是Bitbucket服务器/数据中心）
• 认证凭证：范围界定的API令牌（推荐）或应用程序密码（传统）

快速开始

2分钟后起床跑步：

1.获取您的Bitbucket凭据

重要：Bitbucket应用程序密码正在被弃用，并将被删除 2026年6月。我们建议使用 范围界定的API令牌 对于新的设置。

选项A：范围界定的API代币（推荐-未来证明）

Bitbucket正在弃用应用程序密码。请改用新作用域的API令牌：

1. 首选 大西洋API代币
2. 点击 “创建具有作用域的API令牌”
3. 选择 “比特桶” 作为产品
4. 选择合适的范围：

- 用于只读访问: repository, workspace - 实现完整功能: repository, workspace, pullrequest

1. 复制生成的令牌（以开头 ATATT)
2. 使用Atlassian电子邮件作为用户名

选项B：应用程序密码（旧版-将被弃用）

生成Bitbucket应用程序密码（传统方法）：

1. 首选 Bitbucket应用程序密码
2. 点击“创建应用密码”
3. 给它起个名字，比如“人工智能助手”
4. 选择这些权限：

- 工作区：阅读 - 仓库：阅读（如果你想让AI创建PR/评论，可以写作） - 拉取请求：为公关管理阅读（和写作）

2.立即尝试

# Set your credentials (choose one method)

# Method 1: Scoped API Token (recommended - future-proof)
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_scoped_api_token"  # Token starting with ATATT

# OR Method 2: Legacy App Password (will be deprecated June 2026)
export ATLASSIAN_BITBUCKET_USERNAME="your_username"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="your_app_password"

# List your workspaces
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"

# List repositories in a workspace
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace"

# Get pull requests for a repository
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace/your-repo/pullrequests"

# Get repository details with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/repositories/your-workspace/your-repo" --jq "{name: name, language: language}"

连接到AI助手

适用于Claude桌面用户

将其添加到您的Claude配置文件中(~/.claude/claude_desktop_config.json):

选项1：限定范围的API代币（推荐-未来防止）

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_scoped_api_token"
      }
    }
  }
}

选项2：旧版应用程序密码（将于2026年6月弃用）

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
      "env": {
        "ATLASSIAN_BITBUCKET_USERNAME": "your_username",
        "ATLASSIAN_BITBUCKET_APP_PASSWORD": "your_app_password"
      }
    }
  }
}

重新启动Claude Desktop，您将在状态栏中看到bitbucket服务器。

其他AI助理

大多数AI助手都支持MCP。您可以：

选项1：使用npx（推荐-始终为最新版本）： 配置您的AI助手以运行： npx -y @aashari/mcp-server-atlassian-bitbucket

选项2：全局安装：

npm install -g @aashari/mcp-server-atlassian-bitbucket

然后配置您的AI助手，使其使用带有STDIO传输的MCP服务器。

支持的AI助手：

• Claude Desktop（官方支持）
• 光标AI
• Continue.dev
• 克莱恩
• 任何兼容MCP的客户端

替代方案：配置文件

创建 ~/.mcp/configs.json 对于全系统配置：

选项1：限定范围的API代币（推荐-未来防止）

{
  "bitbucket": {
    "environments": {
      "ATLASSIAN_USER_EMAIL": "your.email@company.com",
      "ATLASSIAN_API_TOKEN": "your_scoped_api_token",
      "BITBUCKET_DEFAULT_WORKSPACE": "your_main_workspace"
    }
  }
}

选项2：旧版应用程序密码（将于2026年6月弃用）

{
  "bitbucket": {
    "environments": {
      "ATLASSIAN_BITBUCKET_USERNAME": "your_username",
      "ATLASSIAN_BITBUCKET_APP_PASSWORD": "your_app_password",
      "BITBUCKET_DEFAULT_WORKSPACE": "your_main_workspace"
    }
  }
}

替代配置键： 系统还接受 "atlassian-bitbucket", "@aashari/mcp-server-atlassian-bitbucket"，或 "mcp-server-atlassian-bitbucket" 而不是 "bitbucket".

可用工具

此MCP服务器提供6个通用工具，可以访问任何Bitbucket API端点：

工具参数

所有API工具都支持这些常用参数：

• path （必需）：API终结点路径以开头 / （the /2.0 前缀是自动添加的）
• queryParams （可选）：查询参数的键值对（例如。， {"pagelen": "25", "page": "2"})
• jq （可选）：用于过滤/转换响应的JMESPath表达式- 强烈推荐 降低代币成本
• outputFormat （可选）： "toon" （默认情况下，令牌减少30-60%）或 "json"
• body （POST/PUT/PATCH需要）：请求正文为JSON对象

常见的API路径

所有路径自动具有 /2.0 预先准备。完整的Bitbucket云REST API 2.0参考：https://developer.atlassian.com/cloud/bitbucket/rest/

工作区和存储库：

• /workspaces -列出所有工作区
• /repositories/{workspace} -列出工作区中的存储库
• /repositories/{workspace}/{repo} -获取回购详细信息
• /repositories/{workspace}/{repo}/refs/branches -列出分支
• /repositories/{workspace}/{repo}/refs/branches/{branch_name} -获取/删除分支
• /repositories/{workspace}/{repo}/commits -列表提交
• /repositories/{workspace}/{repo}/commits/{commit} -获取提交详细信息
• /repositories/{workspace}/{repo}/src/{commit}/{filepath} -获取文件内容

拉取请求：

• /repositories/{workspace}/{repo}/pullrequests -列出PR（GET）或创建PR（POST）
• /repositories/{workspace}/{repo}/pullrequests/{id} -获取/更新/删除PR
• /repositories/{workspace}/{repo}/pullrequests/{id}/diff -获取公关差异
• /repositories/{workspace}/{repo}/pullrequests/{id}/comments -列出/添加公关评论
• /repositories/{workspace}/{repo}/pullrequests/{id}/approve -批准PR（POST）或删除批准（DELETE）
• /repositories/{workspace}/{repo}/pullrequests/{id}/request-changes -请求更改（POST）
• /repositories/{workspace}/{repo}/pullrequests/{id}/merge -合并PR（POST）
• /repositories/{workspace}/{repo}/pullrequests/{id}/decline -拒绝PR（POST）

比较：

• /repositories/{workspace}/{repo}/diff/{source}..{destination} -比较分支/提交

其他资源：

• /repositories/{workspace}/{repo}/issues -列出/管理问题
• /repositories/{workspace}/{repo}/downloads -列出/管理下载
• /repositories/{workspace}/{repo}/pipelines -访问Bitbucket管道
• /repositories/{workspace}/{repo}/deployments -查看部署

TOON输出格式

什么是TOON？ 面向令牌的对象表示法是一种针对LLM优化的格式，与JSON相比，它将令牌消耗减少了30-60%。它使用表格数组和最小语法，同时保留所有数据。

默认行为： 默认情况下，所有工具都返回TOON格式。你可以用以下命令覆盖它 outputFormat: "json" 如果需要的话。

示例比较：

JSON (verbose):
{
  "values": [
    {"name": "repo1", "slug": "repo-1"},
    {"name": "repo2", "slug": "repo-2"}
  ]
}

TOON (efficient):
values:
  name  | slug
  repo1 | repo-1
  repo2 | repo-2

了解更多：https://github.com/toon-format/toon

JMESPath过滤

所有工具都支持可选的JMESPath(jq)过滤以提取特定数据并进一步降低令牌成本：

重要提示： 总是使用 jq 过滤响应！未过滤的API响应在令牌方面可能非常大且昂贵。

# Get just repository names
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/myworkspace" \
  --jq "values[].name"

# Get PR titles and states (custom object shape)
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/myworkspace/myrepo/pullrequests" \
  --jq "values[].{title: title, state: state, author: author.display_name}"

# Get first result only
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/myworkspace" \
  --jq "values[0]"

# Explore schema with one item first, then filter
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/workspaces" \
  --query-params '{"pagelen": "1"}'

常见的JMESPath模式：

• values[*].fieldName -从所有项目中提取单个字段
• values[*].{key1: field1, key2: field2} -创建自定义对象形状
• values[0] -仅获取第一个项目
• values[:5] -获取前5个项目
• values[?state=='OPEN'] -按条件筛选

完整的JMESPath参考：https://jmespath.org

真实世界的例子

探索您的存储库

问你的AI助手：

• *“列出我主工作区中的所有存储库”*
• *“显示后端api存储库的详细信息”*
• *“功能认证分支的提交历史是什么？”*
• *“从main分支获取src/config.js的内容”*

管理拉取请求

问你的AI助手：

• *“显示所有需要审核的打开拉取请求”*
• *“获取有关拉取请求#42的详细信息，包括代码更改”*
• *“创建从功能登录到主分支的拉取请求”*
• *“在PR#15中添加一条评论，说明测试通过”*
• *“批准拉取请求#33”*

与分支机构和代码合作

问你的AI助手：

• *“将我的功能分支与主分支进行比较”*
• *“列出用户服务存储库中的所有分支”*
• *“显示提交abc123和def456之间的区别”*

高级用法

成本优化技巧

1. 始终使用JMESPath过滤 -仅提取所需字段以尽量减少令牌使用
2. 明智地使用分页 -设置 pagelen 查询参数以限制结果（例如。， {"pagelen": "10"})
3. 先探索模式 -获取一个没有过滤器的项目以查看可用字段，然后过滤后续调用
4. 利用TOON格式 -默认TOON格式与JSON相比可节省30-60%的令牌
5. 查询筛选参数 -使用Bitbucket的 q 返回结果前服务器端筛选的参数

查询参数示例

# Filter PRs by state
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/workspace/repo/pullrequests" \
  --query-params '{"state": "OPEN", "pagelen": "5"}' \
  --jq "values[*].{id: id, title: title}"

# Search PRs by title
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/workspace/repo/pullrequests" \
  --query-params '{"q": "title~\"bug\""}' \
  --jq "values[*].{id: id, title: title}"

# Filter repositories by role
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/workspace" \
  --query-params '{"role": "owner", "pagelen": "10"}'

# Sort by updated date
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/workspace/repo/pullrequests" \
  --query-params '{"sort": "-updated_on"}' \
  --jq "values[*].{id: id, title: title, updated: updated_on}"

处理大量响应

在处理返回大负载的API时：

1. 使用稀疏字段集 -添加 fields 查询参数： {"fields": "values.name,values.slug"}
2. 分页结果 -使用 pagelen 和 page 参数
3. 源头过滤 -使用Bitbucket的 q 服务器端筛选参数
4. 与JQ进行后处理 -使用JMESPath进一步过滤响应

结合所有技术的示例：

npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/workspace/repo/pullrequests" \
  --query-params '{"state": "OPEN", "pagelen": "10", "fields": "values.id,values.title,values.state"}' \
  --jq "values[*].{id: id, title: title}"

人工智能交互的最佳实践

1. 明确路径 -使用精确的工作区/仓库slug（区分大小写）
2. 首先使用CLI进行测试 -在AI环境中使用之前验证路径和身份验证
3. 使用描述性JQ过滤器 -提取有意义的字段名称，以便更好地理解人工智能
4. 启用DEBUG进行故障排除 -查看发送到Bitbucket API的内容
5. 检查API限值 -Bitbucket Cloud有速率限制；使用过滤来减少通话

CLI命令

CLI镜像MCP工具，用于直接终端访问。所有命令都返回JSON输出（不是TOON-TOON仅适用于MCP模式）。

可用命令

# Get help
npx -y @aashari/mcp-server-atlassian-bitbucket --help

# GET request
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/workspaces" \
  --jq "values[*].{name: name, slug: slug}"

# GET with query parameters
npx -y @aashari/mcp-server-atlassian-bitbucket get \
  --path "/repositories/myworkspace/myrepo/pullrequests" \
  --query-params '{"state": "OPEN", "pagelen": "10"}' \
  --jq "values[*].{id: id, title: title}"

# POST request (create a PR)
npx -y @aashari/mcp-server-atlassian-bitbucket post \
  --path "/repositories/myworkspace/myrepo/pullrequests" \
  --body '{"title": "My PR", "source": {"branch": {"name": "feature"}}, "destination": {"branch": {"name": "main"}}}' \
  --jq "{id: id, title: title}"

# POST with query parameters
npx -y @aashari/mcp-server-atlassian-bitbucket post \
  --path "/repositories/myworkspace/myrepo/pullrequests/42/comments" \
  --body '{"content": {"raw": "Looks good!"}}' \
  --query-params '{"fields": "id,content"}' \
  --jq "{id: id, content: content.raw}"

# PUT request (replace resource)
npx -y @aashari/mcp-server-atlassian-bitbucket put \
  --path "/repositories/myworkspace/myrepo" \
  --body '{"description": "Updated description", "is_private": true}'

# PATCH request (partial update)
npx -y @aashari/mcp-server-atlassian-bitbucket patch \
  --path "/repositories/myworkspace/myrepo/pullrequests/123" \
  --body '{"title": "Updated PR title"}'

# DELETE request
npx -y @aashari/mcp-server-atlassian-bitbucket delete \
  --path "/repositories/myworkspace/myrepo/refs/branches/old-branch"

# Clone repository
npx -y @aashari/mcp-server-atlassian-bitbucket clone \
  --workspace-slug myworkspace \
  --repo-slug myrepo \
  --target-path /absolute/path/to/parent/directory

CLI选项

对于 get 和 delete 命令：

• `-p, --path

` （必需）-API终结点路径

• -q, --query-params （可选）-以JSON字符串形式查询参数
• --jq （可选）-JMESPath筛选器表达式

对于 post, put，以及 patch 命令：

• `-p, --path

` （必需）-API终结点路径

• -b, --body （必填）-请求正文为JSON字符串
• -q, --query-params （可选）-以JSON字符串形式查询参数
• --jq （可选）-JMESPath筛选器表达式

对于 clone 命令：

• --workspace-slug （可选）-工作区段塞（如果未提供，则使用默认值）
• --repo-slug （必填）-存储库段塞
• `--target-path

` （必填）-将克隆存储库的父目录的绝对路径

调试

启用调试模式

设置 DEBUG 查看详细日志记录的环境变量：

# For CLI testing
DEBUG=true npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"

# For Claude Desktop - add to config
{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
      "env": {
        "DEBUG": "true",
        "ATLASSIAN_USER_EMAIL": "...",
        "ATLASSIAN_API_TOKEN": "..."
      }
    }
  }
}

日志文件： 在MCP模式下运行时，日志将写入 ~/.mcp/data/@aashari-mcp-server-atlassian-bitbucket.[session-id].log

使用HTTP模式进行测试

对于交互式调试，请在HTTP模式下运行服务器并使用MCP检查器：

# Set credentials first
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_token"
export DEBUG=true

# Start HTTP server with MCP Inspector
npx -y @aashari/mcp-server-atlassian-bitbucket
# Then in another terminal:
PORT=3000 npm run mcp:inspect

这将打开一个可视化界面来测试工具并查看请求/响应数据。

常见问题

服务器未出现在Claude Desktop中：

1. 检查配置文件语法（有效的JSON）
2. 完全重新启动克劳德桌面
3. 检查克劳德桌面日志： ~/Library/Logs/Claude/mcp*.log （macOS）

工具不工作：

1. 启用DEBUG模式查看详细错误
2. 首先使用CLI进行测试，以隔离MCP与凭据问题
3. 验证API路径是否正确（区分大小写）

故障排除

“身份验证失败”或“403禁止”

1. 选择正确的身份验证方法:

- 标准Atlassian方法 （推荐）：使用您的Atlassian帐户电子邮件+API令牌（适用于任何Atlassian服务） - Bitbucket特定方法 （传统）：使用您的Bitbucket用户名+应用程序密码（仅限Bitbucket）

1. 适用于范围界定的API令牌 （推荐）：

- 首选 大西洋API代币 - 确保您的令牌仍然处于活动状态，并且具有正确的作用域 - 所需范围： repository, workspace （添加 pullrequest 公关管理） - 令牌应以开头 ATATT

1. Bitbucket应用程序密码 （遗留）：

- 首选 Bitbucket应用程序密码 - 确保您的应用程序密码具有正确的权限 - 记住：应用程序密码将于2026年6月弃用

1. 验证您的凭据:

   # Test credentials with CLI
   export ATLASSIAN_USER_EMAIL="your.email@company.com"
   export ATLASSIAN_API_TOKEN="your_token"
   npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"

1. 环境变量命名:

- 使用 ATLASSIAN_USER_EMAIL + ATLASSIAN_API_TOKEN 对于范围内的令牌 - 使用 ATLASSIAN_BITBUCKET_USERNAME + ATLASSIAN_BITBUCKET_APP_PASSWORD 用于应用程序密码 - 不使用 ATLASSIAN_SITE_NAME -Bitbucket Cloud不需要它

“找不到资源”或“404”

1. 检查API路径:

- 路径区分大小写 - 使用工作区slug（来自URL），而不是显示名称 - 示例：如果您的仓库URL为 https://bitbucket.org/myteam/my-repo，使用 myteam 和 my-repo

1. 验证资源是否存在:

   # List workspaces to find the correct slug
   npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"

Claude桌面集成问题

1. 重新启动克劳德桌面 更新配置文件后
2. 验证配置文件位置:

- macOS： ~/.claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json

获取帮助

如果你仍然有问题：

1. 运行一个简单的测试命令来验证一切正常
2. 检查 对于类似的问题
3. 使用错误消息和设置详细信息创建新问题

常见问题

我需要什么权限？

适用于范围界定的API令牌 （推荐）：

• 所需范围： repository, workspace
• 添加 pullrequest 公关管理

Bitbucket应用程序密码 （遗留）：

• 对于 只读访问：工作区：读取，存储库：读取，拉取请求：读取
• 对于 全部功能：为存储库和拉取请求添加“写入”权限

我可以将其用于私有存储库吗？

对！这适用于公共和私有存储库。您只需要通过凭据获得适当的权限。

这与哪些AI助手一起工作？

任何支持模型上下文协议（MCP）的AI助手：

• 克劳德桌面
• 光标AI
• Continue.dev
• 许多其他

我的数据安全吗？

对！此工具：

• 完全在本地计算机上运行
• 使用您自己的Bitbucket凭据
• 切勿将您的数据发送给第三方
• 仅访问您授予其访问权限的内容

从v1.x迁移

2.0版本代表了一个重大的架构变化。如果你从v1.x升级：

之前（v1.x）-20+特定工具：

bb_ls_workspaces, bb_get_workspace, bb_ls_repos, bb_get_repo,
bb_list_branches, bb_add_branch, bb_get_commit_history, bb_get_file,
bb_ls_prs, bb_get_pr, bb_add_pr, bb_update_pr, bb_approve_pr, bb_reject_pr,
bb_ls_pr_comments, bb_add_pr_comment, bb_diff_branches, bb_diff_commits, bb_search

在（v2.0+）-6通用工具之后：

bb_get, bb_post, bb_put, bb_patch, bb_delete, bb_clone

迁移示例

关键变化

1. 现在所有工具都需要显式路径 -更冗长但更灵活
2. 使用JMESPath过滤 -仅提取减少令牌所需的内容
3. 默认情况下为TOON格式 -令牌减少30-60%（可以用覆盖 outputFormat: "json")
4. 直接访问Bitbucket API -任何API端点都有效，新功能不需要更改代码

支持

需要帮助？以下是如何获得帮助：

1. 检查上面的故障排除部分 -其中涵盖了最常见的问题
2. 访问我们的GitHub仓库 有关文档和示例：
3. 报告问题 在
4. 开始讨论 用于功能请求或一般问题

______________________________________________________________________

*专为希望将人工智能引入Bitbucket工作流程的开发人员打造。*