AI导哈

Bitbucket MCP服务器

Bitbucket MCP服务器是一个基于Go语言的模型上下文协议服务器，用于Bitbucket Server/Data Center，使AI助手能够与Bitbucket仓库、拉取请求、分支和代码搜索交互。

  • by CruelSoftware
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 CruelSoftware/bitbucket-mcp

使用说明

比特桶MCP服务器

基于Go 模型上下文协议 （MCP）服务器 Bitbucket服务器/数据中心。使AI助手（Cursor、Claude Desktop等）能够与Bitbucket存储库、拉取请求、分支和代码搜索进行交互。

特性

  • PAT（个人访问令牌） --主要身份验证：通过Bitbucket令牌 Authorization: Bearer （在Bitbucket用户界面中创建）
  • OAuth发现 --受保护资源元数据（RFC 9728） /.well-known/oauth-protected-resource 对于VS代码，游标
  • 15工具 --PR、repos、分支、用户配置文件、文件内容、代码搜索
  • HTTP传输 --流式HTTP+SSE（不需要stdio）
  • 标头代理 --将自定义标头转发或注入Bitbucket
  • 优雅关闭 --清晰地处理信号/信号

安装指南

先决条件

  • Bitbucket服务器/数据中心 实例（v7+；代码搜索需要v8+）
  • 个人访问令牌 来自Bitbucket，具有存储库读/写权限
  • 码头工人 （推荐）或 转到1.22+ 从源头进行建设

1.使用Docker运行（推荐）

docker run -d \
  --name bitbucket-mcp \
  -p 3001:3001 \
  -e BITBUCKET_URL="https://your-bitbucket.example.com" \
  -e BITBUCKET_DEFAULT_PROJECT="MYPROJ" \
  ghcr.io/cruelsoftware/bitbucket-mcp:latest

验证它是否正在运行：

curl http://localhost:3001/health
# {"status":"healthy"}

2.从源头构建

git clone https://github.com/cruelsoftware/bitbucket-mcp.git
cd bitbucket-mcp
go build -o bitbucket-mcp ./cmd/server

BITBUCKET_URL=https://your-bitbucket.example.com ./bitbucket-mcp

3.配置您的MCP客户端

光标IDE

添加到光标MCP设置(.cursor/mcp.json 或全局设置）：

{
  "mcpServers": {
    "bitbucket": {
      "url": "http://localhost:3001/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_BITBUCKET_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

克劳德桌面版

增添 claude_desktop_config.json:

{
  "mcpServers": {
    "bitbucket": {
      "url": "http://localhost:3001/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_BITBUCKET_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

n8n

使用 MCP客户端 节点具有：

  • SSE URL: http://bitbucket-mcp:3001/mcp （如果在同一个Docker网络中运行）
  • 标头: Authorization: Bearer <token>

通用MCP客户端

任何支持Streamable HTTP传输的MCP客户端都可以连接：

POST http://localhost:3001/mcp   → MCP JSON-RPC requests
GET  http://localhost:3001/mcp   → SSE event stream
GET  http://localhost:3001/health → Health check (no auth)

所有MCP请求必须包括 Authorization: Bearer <token> 头球使用一个 Bitbucket个人访问令牌 （PAT）在Bitbucket UI中创建——令牌被转发到Bitbucket；不存储服务器级凭据。

OAuth发现： VS代码和光标探测 /.well-known/oauth-protected-resource 用于身份验证设置。在代理后面时，设置 MCP_PUBLIC_URL （例如。 https://mcp.example.com)因此发现返回正确的URL。

配置

所有配置都是通过环境变量进行的：

变量 必填 默认 描述
BITBUCKET_URL 是 -- 比特桶服务器基本URL（例如。 https://bitbucket.example.com)
MCP_HTTP_PORT 没有 3001 服务器侦听端口
MCP_HTTP_ENDPOINT 没有 /mcp MCP端点路径
MCP_PUBLIC_URL 没有 http://localhost:{port} OAuth发现的公共URL。设置何时在代理后面（例如。 https://mcp.example.com)
BITBUCKET_DEFAULT_PROJECT 否 -- 工具省略时的默认项目键 workspaceSlug
BITBUCKET_PROXY_HEADERS 没有 -- 逗号分隔的标头从MCP客户端转发到Bitbucket（例如。 X-Request-Id,X-Trace-Id)
BITBUCKET_EXTRA_HEADER_<NAME> 没有 -- 静态标头注入到每个Bitbucket请求中。下划线变为连字符（例如。 BITBUCKET_EXTRA_HEADER_X_CUSTOM=value → X-CUSTOM: value)
BITBUCKET_LOG_LEVEL 没有 info 日志级别： info, debug，或 off

Docker编写示例

services:
  bitbucket-mcp:
    image: ghcr.io/cruelsoftware/bitbucket-mcp:latest
    ports:
      - "3001:3001"
    environment:
      BITBUCKET_URL: "https://bitbucket.example.com"
      BITBUCKET_DEFAULT_PROJECT: "MYPROJ"
      BITBUCKET_LOG_LEVEL: "info"
    restart: unless-stopped

可用工具

工作区和用户

工具 说明
bitbucket_list_workspaces 列出用户可以访问的所有项目
bitbucket_get_user_profile 获取经过身份验证的用户的个人资料

仓库

工具 说明
bitbucket_list_repositories 列出项目中的存储库
bitbucket_get_repository_details 获取存储库元数据
bitbucket_search_content 跨仓库搜索代码（Bitbucket DC 8+）
bitbucket_get_file_content 读取给定引用处的文件内容

拉取请求

工具 说明
bitbucket_create_pull_request 创建新的pull请求
bitbucket_get_pull_request_details 获取PR详细信息和元数据
bitbucket_get_pull_request_diff 获取公关的原始差异
bitbucket_get_pull_request_reviews 获取公关参与者/审稿人
bitbucket_merge_pull_request 合并拉取请求
bitbucket_decline_pull_request 拒绝拉取请求
bitbucket_add_pull_request_comment 向PR添加评论

分支

工具 说明
bitbucket_create_branch 创建新分支
bitbucket_list_repository_branches 列出存储库中的分支

认证

主要方法：Bitbucket个人访问令牌（PAT）

每个MCP请求必须包括：

Authorization: Bearer <your_bitbucket_personal_access_token>

令牌被直接转发到Bitbucket的REST API。不存储服务器端凭据。

创建Bitbucket个人访问令牌

  1. 转到您的Bitbucket实例→ 个人资料 → 管理帐户 → 个人访问令牌
  2. 点击 创建令牌
  3. 授予权限： 存储库读取 （最小值）， 存储库写入 （用于创建PR、分支、合并）
  4. 复制令牌并在MCP客户端配置中使用它（例如。 headers.Authorization 光标/VS代码）

OAuth发现

服务器暴露 OAuth 2.0受保护的资源元数据 （RFC 9728）：

  • /.well-known/oauth-protected-resource
  • /.well-known/oauth-protected-resource/mcp （特定路径）

VS Code和Cursor将此用于身份验证设置。401，服务器返回 WWW-Authenticate 随着 resource_metadata 指向此文档。在反向代理后面运行时，设置 MCP_PUBLIC_URL 到您的公共URL，以便发现返回正确的URL。

发展

# Smoke test (fake Bitbucket + MCP server + basic requests)
./scripts/run-smoke-test.sh

# Run tests
go test -race ./...

# Run tests with coverage
go test -race -coverprofile=coverage.out -covermode=atomic ./...
go tool cover -func=coverage.out

# Run linter
golangci-lint run

# Build
go build -o bitbucket-mcp ./cmd/server

CI强制执行 最低测试覆盖率为90% 门槛。

Docker发布（GHCR）

图像被构建并推送到GitHub容器注册表 main/master 或标签 v*.

  • 图像: ghcr.io/cruelsoftware/bitbucket-mcp:latest
  • 平台: linux/amd64, linux/arm64 （带有Docker的苹果Silicon Mac会自动拉取arm64变体）
  • 标签: latest on main，semver on tags（例如。 v1.0.0 → 1.0.0, 1.0)
  • 设置：不需要额外的配置。 GITHUB_TOKEN 有 packages: write 默认情况下。

许可证

Apache许可证2.0——请参阅 许可证.

相关 MCP