AI导哈

Bitbucket集成服务器

Bitbucket MCP服务器是一个用于与Bitbucket Cloud和Server API集成的模型上下文协议服务器，使AI助手能够与Bitbucket仓库、拉取请求、流水线等资源进行交互。

  • by ATERCATES
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 ATERCATES/bitbucket-mcp

使用说明

比特桶MCP服务器

用于与Bitbucket云和服务器API集成的模型上下文协议（MCP）服务器。此MCP服务器使Claude和Cursor等AI助手能够与您的Bitbucket存储库、拉取请求、管道和其他资源进行交互。

特性

✨ 全面的Bitbucket集成 -59个工具，涵盖存储库、PR、分支、提交、管道等

🔒 安全认证 -通过Bitbucket进行细粒度权限控制的应用密码令牌或基本身份验证

📝 有据可查的 -中的完整API参考资料、体系结构指南和部署说明 /docs

🧪 经过全面测试 -具有完整工具覆盖的综合单元测试套件（Vitest）

⚡ 模块化设计 -按功能域组织的干净、可维护的架构（11个处理程序模块）

🛡️ 安全第一 -3种操作模式（只读、安全、完整），具有细粒度的工具控制

🚀 生产就绪 -使用pnpm、ESLint、Prettier和现代TypeScript构建

快速开始

安装

# Option 1: Global install
pnpm add -g @atercates/bitbucket-mcp

# Option 2: Use with NPX (no installation required)
npx -y @atercates/bitbucket-mcp@latest

# Option 3: Local development
git clone https://github.com/ATERCATES/bitbucket-mcp.git
cd bitbucket-mcp
pnpm install
pnpm build
pnpm start

配置

所需的环境变量：

# Authentication (Personal API Token ONLY)
export BITBUCKET_USERNAME="user@example.com"    # Your Atlassian email address
export BITBUCKET_API_TOKEN="ATBBxxxxxxxxxxxxx"  # Personal API Token (starts with ATBB or ATATT)

# Default Workspace (optional but recommended)
export BITBUCKET_WORKSPACE="my-workspace"       # Your default workspace name

可选配置：

# Server Operation Mode
export BITBUCKET_MODE="safe"  # readonly | safe (default) | full

# Fine-grained tool control
export BITBUCKET_ENABLED_TOOLS="getPullRequest,listPullRequests,createPullRequest"
export BITBUCKET_DISABLED_TOOLS="deleteBranch,deleteRepository"

# Custom API URL (for self-hosted Bitbucket Server)
export BITBUCKET_URL="https://bitbucket.company.com/rest/api/2.0"

🔐 操作模式：

  • readonly -仅GET操作（无修改）
  • safe -GET+POST/PUT操作，但不删除（默认）
  • full -所有操作，包括危险删除

⚠️ 身份验证说明：

  • 此MCP服务器严格执行 个人API代币 （从 ATBB 或 ATATT)
  • 应用程序密码和访问令牌（BBAT xxx）是 不支持
  • BITBUCKET_USERNAME 必须是您的Atlassian电子邮件地址

运行服务器

# If installed globally
bitbucket-mcp

# If using NPX
npx -y @atercates/bitbucket-mcp@latest

# If installed locally
pnpm start

服务器将启动并通过stdio监听MCP协议连接。

与MCP客户端集成

克劳德/光标配置

添加到MCP配置(.mcp.json 或类似）：

{
  "mcpServers": {
    "bitbucket": {
      "command": "bitbucket-mcp",
      "env": {
        "BITBUCKET_USERNAME": "user@example.com",
        "BITBUCKET_API_TOKEN": "ATBBxxxxxxxxxxxxx",
        "BITBUCKET_WORKSPACE": "my-workspace",
        "BITBUCKET_MODE": "safe"
      }
    }
  }
}

示例：

// Read-only mode (safe for production analysis)
{
  "BITBUCKET_MODE": "readonly"
}

// Safe mode (default - no deletes)
{
  "BITBUCKET_MODE": "safe"
}

// Full mode (all operations including deletes)
{
  "BITBUCKET_MODE": "full"
}

// Fine-grained control (only specific tools)
{
  "BITBUCKET_ENABLED_TOOLS": "getPullRequest,listPullRequests,getPullRequestDiff"
}

// Blacklist specific tools
{
  "BITBUCKET_DISABLED_TOOLS": "deleteBranch,deleteRepository,deleteTag"
}

或者使用npx：

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@atercates/bitbucket-mcp@latest"],
      "env": {
        "BITBUCKET_USERNAME": "user@example.com",
        "BITBUCKET_API_TOKEN": "ATBBxxxxxxxxxxxxx",
        "BITBUCKET_WORKSPACE": "my-workspace",
        "BITBUCKET_MODE": "safe"
      }
    }
  }
}

可用工具

该服务器提供59个工具，分为11类：

类别 工具
仓库 列出、获取、创建存储库
拉取请求 创建、批准、合并、拒绝PR
PR评论 创建、删除PR评论
公关任务 创建、更新、删除PR任务（TODO）
Pr含量 获取差异和提交
分支和标签 列出、创建、删除分支和标签
提交 列出提交和提交详细信息
管道 列出、运行、停止管道运行
源代码 从存储库读取文件内容
用户 获取当前用户和工作区信息
分支模型 获取分支策略配置

完整参考： 看 docs/TOOLS.md

环境变量

身份验证（必需）

  • BITBUCKET_USERNAME -您的Atlassian电子邮件地址（例如。， user@example.com)
  • BITBUCKET_API_TOKEN -个人API代币开始于 ATBB- 或 ATATT-

如何创建：

  1. 首选https://bitbucket.org/account/settings/app-passwords/
  2. 点击“创建API令牌”
  3. 选择权限：存储库（读取、写入）、拉取请求（读取、写）、管道（读取）
  4. 复制生成的令牌
  5. 设置到期日期（最多1年）

配置（可选）

  • BITBUCKET_WORKSPACE -默认工作区名称（可在每次工具调用时提供）
  • BITBUCKET_URL -API基本URL（默认值： https://api.bitbucket.org/2.0)
  • BITBUCKET_MODE -操作模式： readonly, safe （默认），或 full
  • BITBUCKET_ENABLED_TOOLS -以逗号分隔的要启用的工具列表（白名单模式）
  • BITBUCKET_DISABLED_TOOLS -以逗号分隔的禁用工具列表（黑名单模式）

日志记录（可选）

  • BITBUCKET_LOG_DISABLE -禁用文件日志记录（默认值： false)
  • BITBUCKET_LOG_FILE -自定义日志文件路径
  • BITBUCKET_LOG_DIR -自定义日志目录
  • BITBUCKET_LOG_PER_CWD -创建每个目录的日志（默认值： false)

文档

  • 工具参考 -所有59个工具的完整API文档及示例
  • 架构指南 -技术设计、模块化结构和扩展指南

发展

先决条件

  • Node.js 24
  • pnpm（或npm）

设置

git clone https://github.com/ATERCATES/bitbucket-mcp.git
cd bitbucket-mcp
pnpm install

构建

pnpm build          # Compile TypeScript
pnpm lint           # Run ESLint  
pnpm format         # Format with Prettier
pnpm format:check   # Check formatting

测试

pnpm test           # Run Vitest suite
pnpm test:watch     # Watch mode

在发展中奔跑

pnpm dev            # Run with tsx (watch mode, no build required)
# OR
pnpm build && pnpm start

MCP检查员（调试）

pnpm inspector      # Launch interactive MCP inspector to test tools

项目结构

src/
├─ index.ts              # Entry point
├─ server.ts             # MCP server orchestration
├─ client.ts             # Bitbucket API client
├─ config.ts             # Configuration management
├─ logger.ts             # File-based logging
├─ types.ts              # TypeScript definitions
├─ schemas.ts            # JSON schemas
├─ utils.ts              # Utilities
├─ pagination.ts         # Pagination helper
└─ handlers/             # Feature modules
   ├─ repositories.ts
   ├─ pull-requests.ts
   ├─ pr-comments.ts
   ├─ pr-tasks.ts
   ├─ pr-content.ts
   ├─ refs.ts
   ├─ commits.ts
   ├─ pipelines.ts
   ├─ source.ts
   ├─ users.ts
   ├─ branching-model.ts
   └─ index.ts

docs/
├─ TOOLS.md              # Tools reference
└─ architecture/
   └─ ARCHITECTURE.md    # Technical design

__tests__/
├─ test-utils.ts         # Test helpers
└─ handlers/             # Handler tests

建筑

服务器使用基于模块化处理程序的架构：

MCP Client → Server → Handler Modules → BitbucketClient → Bitbucket API

每个处理程序模块：

  • 定义工具（名称、模式、描述）
  • 实现处理程序（异步函数）
  • 可以将工具标记为危险
  • 由服务器自动注册

看 docs/architecture/architecture.md 了解详情。

危险作业

一些执行破坏性操作的工具被标记为危险：

  • deletePullRequestComment
  • deletePullRequestTask
  • deleteBranch
  • deleteTag

这些要求 BITBUCKET_MODE=full 使用时，防止意外数据丢失。

故障排除

身份验证问题

测试您的凭据：

# Test Personal API Token
curl -u "user@example.com:ATBBxxxxxx" \
  https://api.bitbucket.org/2.0/user

# Should return your user info if credentials are valid

常见错误：

  1. “BITBUCKET_USERNAME是必需的”

    • 集 BITBUCKET_USERNAME 发送至您的Atlassian电子邮件地址。

  2. “需要BITBUCKET_API_TOKEN”

    • 集 BITBUCKET_API_TOKEN 您的个人API代币（从ATBB开始）。

  3. “令牌格式无效”

    • 令牌必须以开头 ATBB。不支持应用程序密码和访问令牌。

  4. “401未经授权”

    • 检查用户名/令牌是否正确
    • 验证令牌未过期（最多1年）
    • 确保您正在使用 电子邮件地址 作为用户名

查看日志

macOS：

tail -f ~/Library/Logs/bitbucket-mcp/bitbucket.log

Linux：

tail -f ~/.local/state/bitbucket-mcp/bitbucket.log

窗户：

Get-Content -Path "$env:LOCALAPPDATA\bitbucket-mcp\bitbucket.log" -Tail 50 -Wait

自托管Bitbucket

对于自托管Bitbucket服务器，设置API URL：

BITBUCKET_URL=https://bitbucket.mycompany.com/rest/api/2.0 bitbucket-mcp

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

  • 🔧 检查 docs/TOOLS.md 用于工具文档和示例
  • 🏗️ 审查 docs/architecture/architecture.md 了解技术细节
  • 🐛 启用日志记录 BITBUCKET_LOG_DISABLE=false 用于调试
  • 🐞 报告问题https://github.com/ATERCATES/bitbucket-mcp/issues

架构： 基于模块化处理器的设计，具有11个功能模块
测试框架： 维测试
包管理器： pnpm

相关 MCP