# @aashari/mcp-server-atlassian-bitbucket 中文文档

规范地址：https://npmcn.com/package/%40aashari/mcp-server-atlassian-bitbucket/

版本：3\.1\.0
npm 元数据更新时间：2026-02-17T08:38:51.150Z
中文译文更新时间：2026-11-05T20:11:17.289Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aashari/mcp-server-atlassian-bitbucket
原文对照：https://npmcn.com/package/%40aashari/mcp-server-atlassian-bitbucket/?lang=original
项目主页：https://github.com/aashari/mcp-server-atlassian-bitbucket#readme
源码仓库：https://github.com/aashari/mcp-server-atlassian-bitbucket

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：428 kB，82 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：8 个
- 首次发布：2025-03-24T12:22:35.877Z
- 最新版本发布：2026-02-17T08:38:50.868Z
- 近 30 天下载量：31161（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：143（近 12 个月 6 个）

## 中文简介

为Atlassian Bitbucket服务的Node.js/TypeScript MCP服务器. 允许AI系统(LLMs)通过工具(列表,获取,评论,搜索)与工作空间,寄存器进行交互并拉动请求. 通过标准MC直接连接AI到版本控制工作流程

## 安装

```sh
npm install @aashari/mcp-server-atlassian-bitbucket
```

也可以使用：`pnpm add @aashari/mcp-server-atlassian-bitbucket`、`yarn add @aashari/mcp-server-atlassian-bitbucket`、`bun add @aashari/mcp-server-atlassian-bitbucket`

## README

# 连接 AI 到您的 Bitbucket 仓库

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

[![NPM Version](https://img.shields.io/npm/v/@aashari/mcp-server-atlassian-bitbucket)](https://www.npmjs.com/package/@aashari/mcp-server-atlassian-bitbucket) [![License](https://img.shields.io/npm/l/@aashari/mcp-server-atlassian-bitbucket)](https://github.com/aashari/mcp-server-atlassian-bitbucket/blob/main/LICENSE)

## 你能做什么吗

-   **问你的密码**:"我主库中的最新承诺是什么?"
-   **获取公关的见解**:"给我看所有需要审查的拉开请求"
-   **搜索您的密码库**:"找到所有使用认证函数的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 键](https://id.atlassian.com/manage-profile/security/api-tokens)
2.  点击 **"创造API 有瞄准镜"**
3.  选择 **"鸟"** 作为产品
4.  选择合适的范围 :
    -   **仅读访问**数字 : `repository`, (中文(简体) ), `workspace`
    -   **用于全功能**数字 : `repository`, (中文(简体) ), `workspace`, (中文(简体) ), `pullrequest`
5.  复制生成的符号( 启动于 `ATATT`(中文(简体) )
6.  用您的 Atlassian 电子邮件作为用户名

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

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

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

### 2\. 立即尝试

```bash
# 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 配置文件( E)`~/.claude/claude_desktop_config.json`:

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

```json
{
  "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月将贬值)**

```json
{
  "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:在全球安装:**

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

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

**支持的AI助手:**

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

### 选项: 配置文件

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

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

```json
{
  "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月将贬值)**

```json
{
  "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 端点:

| 工具 | 说明 | 参数 |
| --- | --- | --- |
| `bb_get` | 获取任何 Bitbucket API 端点( 读取数据) | `path`, (中文(简体) ), `queryParams?`, (中文(简体) ), `jq?`, (中文(简体) ), `outputFormat?` |
| `bb_post` | POST 到任何终点( 创建资源) | `path`, (中文(简体) ), `body`, (中文(简体) ), `queryParams?`, (中文(简体) ), `jq?`, (中文(简体) ), `outputFormat?` |
| `bb_put` | PUT 到任意终点(替换资源) | `path`, (中文(简体) ), `body`, (中文(简体) ), `queryParams?`, (中文(简体) ), `jq?`, (中文(简体) ), `outputFormat?` |
| `bb_patch` | PATCH 任意终点( 部分更新) | `path`, (中文(简体) ), `body`, (中文(简体) ), `queryParams?`, (中文(简体) ), `jq?`, (中文(简体) ), `outputFormat?` |
| `bb_delete` | DELETE 任意终点( 调走资源) | `path`, (中文(简体) ), `queryParams?`, (中文(简体) ), `jq?`, (中文(简体) ), `outputFormat?` |
| `bb_clone` | 克隆本地仓库 | `workspaceSlug?`, (中文(简体) ), `repoSlug`, (中文(简体) ), `targetPath` |

### 工具参数

所有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/ (中文(简体) )](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 页面存档备份,存于互联网档案馆](https://github.com/toon-format/toon)

### JMESPath 过滤

所有工具都支持可选 JMESPath (`jq`过滤以提取具体数据并进一步减少象征性费用:

**重要内容:** 总是使用 `jq` 过滤响应! 未过滤的API响应可能非常大,从信使方面来说也是昂贵的.

```bash
# 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](https://jmespath.org/)

## 现实世界实例

### 探索您的仓库

问你的人工智能助手:

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

### 管理拉动请求

问你的人工智能助手:

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

### 与分支机构和守则合作

问你的人工智能助手:

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

## 高级使用

### 成本优化提示

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

### 查询参数示例

```bash
# 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进一步过滤反应

结合所有技术的例子:

```bash
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 模式) .

### 可用命令

```bash
# 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` 要查看详细记录的环境变量 :

```bash
# 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 检查器:

```bash
# 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 桌面 :**

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 键](https://id.atlassian.com/manage-profile/security/api-tokens)
    -   确定您的纪念物是否还在使用, 并有正确的瞄准镜
    -   所需范围 : `repository`, (中文(简体) ), `workspace` (编) `pullrequest` (经常预算)
    -   托肯应该从 `ATATT`
3.  **对于 Bitbucket 应用密码** (遗产):
    
    -   转到 [Bitbucket 应用密码](https://bitbucket.org/account/settings/app-passwords/)
    -   确保您的应用程序密码有正确的权限
    -   记住:App密码将在2026年6月前贬值
4.  **校验您的证书**数字 :
    
    ```bash
    # 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"
    ```
    
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.  **验证资源是否存在**数字 :
    
    ```bash
    # 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 问题](https://github.com/aashari/mcp-server-atlassian-bitbucket/issues) 类似的问题
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
```

### 移徙实例

| v1.x 工具 | v2.0+ 等价键 |
| --- | --- |
| `bb_ls_workspaces()` | `bb_get(path: "/workspaces")` |
| `bb_ls_repos(workspace: "myteam")` | `bb_get(path: "/repositories/myteam")` |
| `bb_get_repo(workspace: "myteam", repo: "myrepo")` | `bb_get(path: "/repositories/myteam/myrepo")` |
| `bb_list_branches(workspace: "myteam", repo: "myrepo")` | `bb_get(path: "/repositories/myteam/myrepo/refs/branches")` |
| `bb_add_branch(...)` | `bb_post(path: "/repositories/.../refs/branches", body: {...})` |
| `bb_ls_prs(workspace: "myteam", repo: "myrepo")` | `bb_get(path: "/repositories/myteam/myrepo/pullrequests")` |
| `bb_get_pr(workspace: "myteam", repo: "myrepo", id: 42)` | `bb_get(path: "/repositories/myteam/myrepo/pullrequests/42")` |
| `bb_add_pr(...)` | `bb_post(path: "/repositories/.../pullrequests", body: {...})` |
| `bb_update_pr(...)` | `bb_patch(path: "/repositories/.../pullrequests/42", body: {...})` |
| `bb_approve_pr(workspace: "myteam", repo: "myrepo", id: 42)` | `bb_post(path: "/repositories/myteam/myrepo/pullrequests/42/approve", body: {})` |
| `bb_diff_branches(...)` | `bb_get(path: "/repositories/.../diff/branch1..branch2")` |

### 密钥更改

1.  **所有工具现在都需要明确的路径** - 更动词更灵活
2.  **使用 JMESPath 过滤** - 只提取你需要的去减值符
3.  **默认 TON 格式** - 减少30-60%的代币(可用 `outputFormat: "json"`(中文(简体) )
4.  **直接 Bitbucket API 访问** - API端点工程,新功能不需要更改代码

## 支助

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

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

* * *

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

## 常见问题

### @aashari/mcp-server-atlassian-bitbucket 是什么？

为Atlassian Bitbucket服务的Node\.js/TypeScript MCP服务器\. 允许AI系统\(LLMs\)通过工具\(列表,获取,评论,搜索\)与工作空间,寄存器进行交互并拉动请求\. 通过标准MC直接连接AI到版本控制工作流程

### 如何安装 @aashari/mcp-server-atlassian-bitbucket？

在项目目录运行 npm install @aashari/mcp-server-atlassian-bitbucket，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp-atlassian-bitbucket，可以用 npx mcp-atlassian-bitbucket 直接运行。

### @aashari/mcp-server-atlassian-bitbucket 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aashari/mcp-server-atlassian-bitbucket 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aashari/mcp-server-atlassian-bitbucket 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aashari/mcp-server-atlassian-bitbucket 可以商用吗？

@aashari/mcp-server-atlassian-bitbucket 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aashari/mcp-server-atlassian-bitbucket 的下载量有多少？

根据 npm 官方下载统计，@aashari/mcp-server-atlassian-bitbucket 在 2026/10/05 – 2026/11/03 这 30 天内被下载 31,161 次，日均约 1,039 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aashari/mcp-server-atlassian-bitbucket 还在维护吗？

最新版本 3\.1\.0 发布于 2026/02/17（8 个月前）；至今共发布 143 个版本，其中过去 12 个月发布了 6 个；首次发布于 2025/03/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。