连接 AI 到您的 Bitbucket 仓库

通过将克洛德,Cursor AI,以及其他AI助手直接连接到你的寄存器,拉出请求和代码来转变你与Bitbucket的工作方式. 获得即时的洞察力,实现代码审查自动化,并精简你的开发工作流程.

你能做什么吗

• 问你的密码:"我主库中的最新承诺是什么?"
• 获取公关的见解:"给我看所有需要审查的拉开请求"
• 搜索您的密码库:"找到所有使用认证函数的JavaScript文件"
• 审查代码更改:"比较我的特点分支和主的区别"
• 管理拉动请求:"为我的新地貌分支创建公关"
• 自动工作流程:"用测试结果加入对PR #123的评论"

完美为

• 开发者 要求AI协助代码审查和存储管理
• 团队领导 需要快速了解项目状况和吸引请求活动
• DevOps 工程师 自动化寄存器工作流程和分支管理
• 谁都行 使用自然语言与 Bitbucket 互动

所需资源

• 节点.js 18.0.0 或更高
• 键盘云 (不是 Bitbucket 服务器/数据中心)
• 认证证书: 范围为 API Token( 建议) 或 App 密码( 遗留)

快速启动

两分钟后起床跑道:

1. 获取您的 Bitbucket 证书

重要性: Bitbucket App 密码正在贬值,将被删除 2026年6月 (中文(简体) )我们建议使用 范围化 API 键 用于新设置.

备选案文A:范围化的API Token(建议----未来方案)

Bitbucket 正在对应用密码进行贬值。使用新范围 API 符号代替 :

1. 转到 地图集API 键
2. 点击 "创造API 有瞄准镜"
3. 选择 "鸟" 作为产品
4. 选择合适的范围 :
   • 仅读访问数字 : repository, (中文(简体) ), workspace
   • 用于全功能数字 : repository, (中文(简体) ), workspace, (中文(简体) ), pullrequest
5. 复制生成的符号( 启动于 ATATT(中文(简体) )
6. 用您的 Atlassian 电子邮件作为用户名

选项B: App 密码(Legacy - 将贬值)

生成 Bitbucket app 密码( 遗留方法) :

1. 转到 Bitbucket 应用密码
2. 点击“ 创建应用程序密码”
3. 给它取个"AI助理"的名字
4. 选择这些权限 :
   • 工作空间: 读取
   • 仓库: 读取(如果想要AI创建PR/评论)
   • 调取请求: 读取(并为公关管理写出)

2. 立即尝试

# Set your credentials (choose one method)

# Method 1: Scoped API Token (recommended - future-proof)
export ATLASSIAN_USER_EMAIL="[email protected]"
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 配置文件( E)~/.claude/claude_desktop_config.json:

备选案文1:范围化的API Token( 建议的- 防止未来)

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "[email protected]",
        "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"
      }
    }
  }
}

重新启动克洛德桌面,你会看到状态栏中的比特巴克特服务器.

其他助理助理

大多数AI助手支持MCP. 你们也可以:

备选案文1: 使用npx(建议-总是最新版本): 配置要运行的 AI 助手 : npx -y @aashari/mcp-server-atlassian-bitbucket

备选方案2:在全球安装:

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

然后配置您的 AI 助手使用 STIO 传输的 MCP 服务器 .

支持的AI助手:

• Claude 桌面( 官方支持)
• 光标AI
• 继续. dev
• 线
• 任何 MCP 兼容客户端

选项: 配置文件

创建 ~/.mcp/configs.json 全系统配置:

备选案文1:范围化的API Token( 建议的- 防止未来)

{
  "bitbucket": {
    "environments": {
      "ATLASSIAN_USER_EMAIL": "[email protected]",
      "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 端点路径从 / (单位:千美元) /2.0 前缀自动添加)
• queryParams (可选):用于查询参数的密钥值对(如, {"pagelen": "25", "page": "2"}(中文(简体) )
• jq (可选):用于过滤/转换响应的 JMESPath 表达式 - 高度建议 减少象征性费用
• outputFormat (可选) : "toon" (默认,减少30-60%的令牌)或 "json"
• body (POST/PUT/PATCH需要):请求机构为JSON对象

常见 API 路径

所有路径自动有 /2.0 准备。 完整 Bitbucket Cloud 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 - 列出公关或创建公关
• /repositories/{workspace}/{repo}/pullrequests/{id} - 获得/更新/删除PR
• /repositories/{workspace}/{repo}/pullrequests/{id}/diff - 去找公关
• /repositories/{workspace}/{repo}/pullrequests/{id}/comments - 列表/添加 PR 注释
• /repositories/{workspace}/{repo}/pullrequests/{id}/approve - 批准PR(POST)或取消批准(DEELETE)
• /repositories/{workspace}/{repo}/pullrequests/{id}/request-changes - 请求更改(POST)
• /repositories/{workspace}/{repo}/pullrequests/{id}/merge - 合并公关
• /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 - 查看部署

TON 输出格式

什么是东? Token-Oriented Object Notation是一种对LLMS进行优化的格式,与JSON相比将象征性消费减少30-60%. 它在保存所有数据的同时使用表格式数组和最小语法.

默认行为 : 所有工具默认返回 TON 格式 。 您可以用 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://jmessat.org 互联网档案馆的存檔,存档日期2013-12-02

现实世界实例

探索您的仓库

问你的人工智能助手:

• "把所有仓库都放在我的主要工作空间"
• "告诉我关于后端-api仓库的细节"
• "特奥支部的执业史是什么"
• 从主分支获取 src/config.js 的内容

管理拉动请求

问你的人工智能助手:

• "给我看看所有需要审查的拉拉请求"
• "获取拉动请求的细节#42 包括代码更改"
• 创建从功能日志到主分支的牵引请求
• 加上一篇评论
• "证明拉动请求#33"

与分支机构和守则合作

问你的人工智能助手:

• "把我的特色分支与主分支相匹配"
• "在用户服务库中列出所有分支"
• "给我看下abc123和def456的区别"

高级使用

成本优化提示

1. 总是使用 JMESPath 过滤 - 只提取需要的字段,以尽量减少符号使用
2. 明智地使用相片 - 准备 pagelen 查询参数以限制结果(例如, {"pagelen": "10"}(中文(简体) )
3. 先探索计划 - 获取一个没有过滤器的项目以查看可用的字段, 然后过滤后续的呼叫
4. 调用 TON 格式 - 默认 TON 格式将保存 30- 60% 的令牌对 JSON
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. 粘贴结果 - 使用( I) 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}"

AI互动的最佳做法

1. 指定路径 - 使用精确的工作空间/回弹(对大小写敏感)
2. 先用CLI进行测试 - 在AI上下文使用前验证路径和认证
3. 使用描述性 JQ 过滤器 - 提取有意义的字段名称,以更好地了解AI
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 <path> (需要) - API 端点路径
• -q, --query-params <json> (可选) - 查询参数为 JSON 字符串
• --jq <expression> (可选) - JMESPath 过滤表达式

对于 post, (中文(简体) ), put,以及 patch 命令 :

• -p, --path <path> (需要) - API 端点路径
• -b, --body <json> (需要) - 请求机构为 JSON 字符串
• -q, --query-params <json> (可选) - 查询参数为 JSON 字符串
• --jq <expression> (可选) - JMESPath 过滤表达式

对于 clone 命令 :

• --workspace-slug <slug> (可选) - 工作空间 sattle( 如果未提供默认使用)
• --repo-slug <slug> (需要) - 存储弹
• --target-path <path> (需要) - 将复制 repo 的父目录的绝对路径

调试

启用调试模式

设定 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="[email protected]"
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 桌面 :

1. 检查配置文件语法( 有效 JSON)
2. 完全重新启动 Claude 桌面
3. 检查 Claude 桌面日志 : ~/Library/Logs/Claude/mcp*.log (macOS) (英语)

工具无效 :

1. 允许 DEBUG 模式查看详细错误
2. 与 CLI 进行先隔离 MCP 对证书问题的测试
3. 校验 API 路径正确( 对大小写敏感)

解决问题

"校正失败"或"403紫禁"

1. 选择正确的认证方法数字 :

   • 标准阿特拉斯法 (建议):使用您的 Atlassian 账户电子邮件 + API 令牌( 任何 Atlassian 服务的工作)
   • Bitbucket 特定方法 (legacy):使用您的 Bitbucket 用户名 + App 密码( 仅 Bitbucket)

2. 范围化 API 键 (建议):

   • 转到 地图集API 键
   • 确定您的纪念物是否还在使用, 并有正确的瞄准镜
   • 所需范围 : repository, (中文(简体) ), workspace (编) pullrequest (经常预算)
   • 托肯应该从 ATATT

3. 对于 Bitbucket 应用密码 (遗产):

   • 转到 Bitbucket 应用密码
   • 确保您的应用程序密码有正确的权限
   • 记住:App密码将在2026年6月前贬值

4. 校验您的证书数字 :

   # Test credentials with CLI
   export ATLASSIAN_USER_EMAIL="[email protected]"
   export ATLASSIAN_API_TOKEN="your_token"
   npx -y @aashari/mcp-server-atlassian-bitbucket get --path "/workspaces"
   

5. 环境变量命名数字 :

   • 使用 ATLASSIAN_USER_EMAIL + 键 ATLASSIAN_API_TOKEN 范围符号
   • 使用 ATLASSIAN_BITBUCKET_USERNAME + 键 ATLASSIAN_BITBUCKET_APP_PASSWORD 应用程序密码
   • 别用 ATLASSIAN_SITE_NAME - 这对Bitbucket Cloud来说是不必要的

"未找到资源"或"404"

1. 检查 API 路径数字 :

   • 路径对大小写敏感
   • 使用工作空间 sattle( 来自 URL), 不显示名称
   • 示例:如果您的 repo URL 是 https://bitbucket.org/myteam/my-repo,使用时 myteam 财务报告和审定财务报表 my-repo

2. 验证资源是否存在数字 :

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

Claude 桌面整合问题

1. 重新启动 Claude 桌面 更新配置文件后
2. 验证配置文件位置数字 :
   • 马可斯: ~/.claude/claude_desktop_config.json
   • 窗口 : %APPDATA%\Claude\claude_desktop_config.json

获取帮助

如果你仍然有问题:

1. 运行一个简单的测试命令来验证所有工作
2. 检查 GitHub 问题 类似的问题
3. 以错误消息创建新问题并设置细节

经常被问到的问题

我需要什么许可?

范围化 API 键 (建议):

• 所需范围 : repository, (中文(简体) ), workspace
• 添加 pullrequest 公关管理

对于 Bitbucket 应用密码 (遗产):

• 对于 仅读访问:工作空间:读取,存储:读取,拉取请求:读取
• 对于 全功能: 添加存储和拉请求的“ 写入” 权限

我可以用这个 与私人的仓库?

没错! 这与公共和私人的储存库一起工作。 你只需要通过你的证书获得适当的许可.

人工智能助理是做什么工作的?

任何支持模式背景协议的AI助手:

• 克劳德桌面
• 光标AI
• 继续. 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. 默认 TON 格式 - 减少30-60%的代币(可用 outputFormat: "json"(中文(简体) )
4. 直接 Bitbucket API 访问 - API端点工程,新功能不需要更改代码

支助

需要帮忙吗? 如何获得援助:

1. 检查上面的故障排除区域 - 涉及最常见的问题
2. 访问 GitHub 仓库 文件和实例: github.com/aashari/mcp-server-atlassian-bitbucket 页面存档备份,存于互联网档案馆
3. 报告问题 时间 GitHub 问题
4. 开始讨论 专题请求或一般问题

为想将AI带入Bitbucket工作流程的开发者谨慎地制作.