将 AI 连接到您的 Bitbucket 仓库

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

您可以做什么

✅ 向 AI 询问您的代码： “我的主仓库中最新提交是什么？”
✅ 获取拉取请求洞察： “显示所有需要审查的开放拉取请求”
✅ 搜索您的代码库： “查找所有使用身份验证功能的 JavaScript 文件”
✅ 审查代码更改： “比较我的功能分支与主分支之间的差异”
✅ 管理拉取请求： “为我的新功能分支创建一个拉取请求”
✅ 自动化工作流程： “将测试结果添加到拉取请求 #123 的评论中”

适合谁

• 开发人员：希望 AI 协助代码审查和仓库管理
• 团队领导：需要快速了解项目状态和拉取请求活动
• DevOps 工程师：自动化仓库工作流程和分支管理
• 任何人：希望使用自然语言与 Bitbucket 交互

快速开始

在 2 分钟内启动并运行：

1. 获取您的 Bitbucket 凭据

⚠️ 重要：Bitbucket 应用密码即将弃用，并将在 2026 年 6 月 之前移除。我们建议新设置使用 范围化 API 令牌。

选项 A：范围化 API 令牌（推荐 - 面向未来）

Bitbucket 正在弃用应用密码。请改用新的范围化 API 令牌：

1. 前往 Atlassian API 令牌
2. 点击 “创建带有范围化的 API 令牌”
3. 选择 “Bitbucket” 作为产品
4. 选择适当的范围：
   • 仅读取访问：repository, workspace
   • 完整功能：repository, workspace, pullrequest
5. 复制生成的令牌（以 ATATT 开头）
6. 与您的 Atlassian 电子邮件一起作为用户名使用

选项 B：应用密码（旧版 - 即将弃用）

生成 Bitbucket 应用密码（旧版方法）：

1. 前往 Bitbucket 应用密码
2. 点击“创建应用密码”
3. 为其命名，例如“AI 助手”
4. 选择以下权限：
   • 工作区：读取
   • 仓库：读取（如果您希望 AI 创建拉取请求/评论，则选择写入）
   • 拉取请求：读取（用于拉取请求管理则选择写入）

2. 立即尝试

# 设置您的凭据（选择一种方法）

# 方法 1：范围化 API 令牌（推荐 - 面向未来）
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_scoped_api_token"  # 以 ATATT 开头的令牌

# 或方法 2：旧版应用密码（将在 2026 年 6 月弃用）
export ATLASSIAN_BITBUCKET_USERNAME="your_username"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="your_app_password"

# 列出您的工作区
npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces

# 列出您工作区中的仓库
npx -y @aashari/mcp-server-atlassian-bitbucket ls-repos --workspace-slug your-workspace

# 获取特定仓库的详细信息  
npx -y @aashari/mcp-server-atlassian-bitbucket get-repo --workspace-slug your-workspace --repo-slug your-repo

连接到 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 桌面，您将在状态栏中看到“🔗 bitbucket”。

对于其他 AI 助手

大多数 AI 助手都支持 MCP。全局安装服务器：

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

然后配置您的 AI 助手以使用带有 STDIO 传输的 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"。

实际示例

🔍 探索您的仓库

询问您的 AI 助手：

• “列出我的主工作区中的所有仓库”
• “显示关于 backend-api 仓库的详细信息”
• “feature-auth 分支的提交历史是什么？”
• “获取 main 分支中 src/config.js 的内容”

📋 管理拉取请求

询问您的 AI 助手：

• “显示所有需要审查的开放拉取请求”
• “获取拉取请求 #42 的详细信息，包括代码更改”
• “从 feature-login 分支创建一个拉取请求到 main 分支”
• “在拉取请求 #15 中添加一条评论，说测试通过了”
• “批准拉取请求 #33”

🔧 处理分支和代码

询问您的 AI 助手：

• “比较我的功能分支与主分支”
• “从 main 分支创建一个名为 hotfix-login 的新分支”
• “列出 user-service 仓库中的所有分支”
• “显示提交 abc123 和 def456 之间的差异”

🔎 搜索和发现

询问您的 AI 助手：

• “搜索包含‘authentication’的 JavaScript 文件”
• “查找与登录功能相关的所有拉取请求”
• “搜索移动项目中的仓库”
• “显示使用 React 框架的代码文件”

故障排除

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

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

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

2. 对于 Bitbucket 应用密码（如果使用选项 2）：

   • 前往 Bitbucket 应用密码
   • 确保您的应用密码具有正确的权限（工作区：读取，仓库：读取，拉取请求：读取）

3. 对于范围化 API 令牌（推荐）：

   • 前往 Atlassian API 令牌
   • 确保您的令牌仍然有效并具有正确的范围
   • 更新您的 ~/.mcp/configs.json 文件以使用新的范围化 API 令牌格式：

   {
     "@aashari/mcp-server-atlassian-bitbucket": {
       "environments": {
         "ATLASSIAN_USER_EMAIL": "your.email@company.com",
         "ATLASSIAN_API_TOKEN": "ATATT3xFfGF0..."
       }
     }
   }
   

4. 验证您的凭据：

   # 测试您的凭据是否有效
   npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces
   

“工作区未找到”或“仓库未找到”

1. 检查您的工作区 slug：

   # 列出您的工作区以查看正确的 slugs
   npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces
   

2. 使用 Bitbucket URL 中的确切 slug：

   • 如果您的仓库 URL 是 https://bitbucket.org/myteam/my-repo
   • 工作区 slug 是 myteam
   • 仓库 slug 是 my-repo

“未配置默认工作区”

设置默认工作区以避免每次指定：

export BITBUCKET_DEFAULT_WORKSPACE="your-main-workspace-slug"

Claude 桌面集成问题

1. 更新配置文件后重启 Claude 桌面
2. 检查状态栏中的“🔗 bitbucket”指示器
3. 验证配置文件位置：
   • macOS：~/.claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

获取帮助

如果您仍然遇到问题：

1. 运行一个简单的测试命令以验证一切正常
2. 查看 GitHub Issues 以查找类似问题
3. 创建一个新问题，附上您的错误消息和设置详情

常见问题

我需要什么权限？

对于范围化 API 令牌（推荐）：

• 您常规的 Atlassian 帐户，并具有对 Bitbucket 的访问权限
• 在 id.atlassian.com/manage-profile/security/api-tokens 创建的范围化 API 令牌
• 所需范围：repository, workspace（添加 pullrequest 用于拉取请求管理）

对于 Bitbucket 应用密码（旧版 - 即将弃用）：

• 对于 仅读取访问（查看仓库、拉取请求、提交）：
  • 工作区：读取
  • 仓库：读取
  • 拉取请求：读取
• 对于 完整功能（创建拉取请求、评论）：
  • 添加“写入”权限以用于仓库和拉取请求

我可以将此用于私有仓库吗？

是的！这适用于公共和私有仓库。您只需通过 Bitbucket 应用密码获得适当的权限。

每次都需要指定工作区吗？

不需要！在您的环境或配置文件中设置 BITBUCKET_DEFAULT_WORKSPACE，当您未指定工作区时，它将自动使用。

这个工具适用于哪些AI助手？

任何支持模型上下文协议（MCP）的AI助手都可以使用：

• Claude Desktop（最受欢迎）
• Cursor AI
• Continue.dev
• 其他许多助手

我的数据安全吗？

是的！这个工具：

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

我可以为多个Bitbucket账户使用这个工具吗？

目前，每个安装仅支持一组凭据。对于多个账户，您需要单独的配置。

支持

需要帮助吗？以下是获取帮助的方式：

1. 查看上面的故障排除部分 - 大多数常见问题都在那里有解答
2. 访问我们的GitHub仓库 获取文档和示例：github.com/aashari/mcp-server-atlassian-bitbucket
3. 在GitHub Issues上报告问题：GitHub Issues
4. 发起讨论 提出功能请求或一般问题

---

为希望将AI引入Bitbucket工作流程的开发者们，用心制作。