AI导哈

Bitbucket MCP服务器

Bitbucket MCP服务器是一个为Bitbucket Cloud提供的模型上下文协议服务器，让AI代理（如Copilot、Claude等）能够安全、类型化地访问仓库、分支、拉取请求和部署。

  • by fnops
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 FernandoDevOps/bitbucket-mcp-server

使用说明

比特桶MCP服务器

一个社区 模型上下文协议 Bitbucket云服务器。 为AI代理（Copilot、Claude等）提供对存储库、分支、拉取请求和部署的安全、类型化访问。

快速开始

# 1 — Install
npm ci

# 2 — Configure (copy and fill in your credentials)
cp .env.example .env

# 3 — Build
npm run build

# 4 — Run
node build/index.js

特性

区域 工具
仓库 list_repositories, list_projects, list_branches, list_tags, get_branch_commits, clone_repository
分支 create_branch
拉取请求 create_pull_request, list_pull_requests, get_pull_request, approve_pull_request, decline_pull_request, merge_pull_request, get_pull_request_comments, add_pull_request_comment
部署 list_deployments, get_deployment

配置

环境变量

变量 必填 默认 描述
BITBUCKET_API_TOKEN 是* -- API令牌 （承载认证——推荐）
BITBUCKET_USERNAME 是* -- Bitbucket帐户电子邮件（基本身份验证--传统）
BITBUCKET_APP_PASSWORD 是* -- 应用程序密码 （基本身份验证--传统）
BITBUCKET_WORKSPACE 是 -- 工作区段塞
BITBUCKET_API_URL 没有 https://api.bitbucket.org/2.0 API基本URL（用于测试的覆盖）
MCP_TRANSPORT 没有 stdio stdio （本地开发）或 http （VPC服务）
MCP_PORT 没有 3000 HTTP服务器端口（仅当 MCP_TRANSPORT=http)
MCP_HOST 没有 0.0.0.0 HTTP服务器绑定地址
LOG_LEVEL 没有 info fatal, error, warn, info, debug, trace
NODE_ENV 没有 production development, production, test

* 身份验证：设置 BITBUCKET_API_TOKEN 或 两者 BITBUCKET_USERNAME + BITBUCKET_APP_PASSWORD如果两者都提供，则API令牌优先。

MCP客户端配置

本地（stdio--默认）

将此添加到您的MCP客户端设置中（VS Code、Claude Desktop等）：

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_API_TOKEN": "your-api-token",
        "BITBUCKET_WORKSPACE": "your-workspace"
      },
      "transportType": "stdio"
    }
  }
}

远程（HTTP--VPC服务）

使用部署服务器 MCP_TRANSPORT=http 并将客户端指向HTTP端点：

{
  "mcpServers": {
    "bitbucket": {
      "url": "http://your-mcp-host:3000/mcp",
      "transportType": "http"
    }
  }
}

HTTP服务器公开：

端点 方法 目的
/health GET 健康检查（ALB/ECS探测器）
/mcp POST MCP JSON-RPC请求
/mcp 服务器发起的消息的GET SSE流
/mcp DELETE 会话终止

创建Bitbucket应用程序密码

注： Bitbucket正在弃用应用程序密码。更喜欢 API令牌 （存储库或工作区访问令牌）用于新设置。

  1. 首选 https://bitbucket.org/account/settings/app-passwords/
  2. 点击 创建应用密码
  3. 选择权限：
    • 仓库：读、写、管理
    • 拉取请求：读，写
    • 账户：阅读
  4. 复制生成的密码

发展

先决条件

  • Node.js 24+
  • npm

脚本

npm run build          # Compile TypeScript → build/
npm run dev            # Watch mode (tsc --watch)
npm run typecheck      # Type-check without emitting
npm run lint           # ESLint
npm run lint:fix       # ESLint with auto-fix
npm run format         # Prettier write
npm run format:check   # Prettier check
npm run test           # Vitest (single run)
npm run test:watch     # Vitest (watch)
npm run test:coverage  # Vitest with coverage
npm run inspector      # MCP Inspector UI

项目结构

src/
├── index.ts               # Entry-point — McpServer setup & tool registration
├── config.ts              # Zod-validated environment config (singleton)
├── logger.ts              # Pino structured logger
├── httpClient.ts          # Axios instance w/ retry, rate-limit logging
├── errors.ts              # Custom error hierarchy
├── schemas.ts             # Zod input schemas for every tool
├── types.ts               # Bitbucket API response interfaces
├── *.test.ts              # Unit tests (Vitest)
└── handlers/
    ├── repository.ts      # Repos, branches, tags, commits, clone
    ├── branch.ts          # Branch creation
    ├── pullRequest.ts     # PR CRUD, review, merge, comments
    └── deployment.ts      # Deployment listing & details

建筑亮点

  • MCP SDK 1.x高级API --用途 McpServer.tool() 使用原生Zod模式注册（无手动JSON模式）。
  • 到处都是Zod --启动时验证配置；根据请求验证工具输入。
  • 结构化日志记录 --pino在生产中具有JSON输出，在开发中具有漂亮的打印功能。
  • 自动重试 --axios对429/5xx/网络错误进行指数回退重试。
  • 限速意识 --在Bitbucket时记录警告 X-RateLimit-Remaining 降至阈值以下。
  • 自定义错误类 — ValidationError, BitbucketApiError, NotFoundError, ConfigError.
  • 不 any --完全类型化的处理程序和模式。

码头工人

Dockerfile默认为HTTP模式(MCP_TRANSPORT=http)用于集装箱化部署。

# Build
docker build -t bitbucket-mcp-server .

# Run (HTTP mode — default in Docker)
docker run --env-file .env -p 3000:3000 bitbucket-mcp-server

或者使用Docker Compose：

docker compose up

Dockerfile使用多阶段构建 node:24-slim，以非root用户身份运行，并包含 HEALTHCHECK 指令。

可靠性

问题 如何处理
瞬时API失败 3次重试，带指数后退（1秒→ 2 s → 4 s)
速率限制 重试429个响应； X-RateLimit-* 记录标题
无效输入 Zod在进行任何API调用之前拒绝错误输入
缺少配置 启动失败很快，出现一个明确的错误，列出了所有缺少的变量
优雅关闭 SIGINT/SIGTERM处理程序干净地关闭MCP连接
双重运输 stdio 对于本地开发人员， http 对于VPC--相同的代码库

许可证

麻省理工学院

相关 MCP