Name: Bitbucket MCP服务工具
Author: Lexmata

使用说明

@lexmata/比特桶mcp

Bitbucket Cloud的模型上下文协议（MCP）服务器-用于存储库、拉取请求、分支、提交、问题、管道和代码搜索的25多种工具。

特性

全面的Bitbucket云API覆盖：访问存储库、拉取请求、分支、提交、问题、管道和代码搜索
OAuth 2.0身份验证：通过基于浏览器的自动登录和令牌刷新进行安全身份验证
应用密码支持：使用Bitbucket应用程序密码的替代身份验证
MCP工具：25多种与Bitbucket交互的工具
MCP资源：访问存储库、拉取请求和文件作为资源
TypeScript：完全打字，可靠性和开发人员体验

安装

# Using npm
npm install -g @lexmata/bitbucket-mcp

# Using pnpm
pnpm add -g @lexmata/bitbucket-mcp

# Using yarn
yarn global add @lexmata/bitbucket-mcp

配置

选项1:OAuth 2.0（推荐）

OAuth提供了基于浏览器的自动身份验证和令牌刷新的最佳体验。

步骤1：创建OAuth消费者

转到您的Bitbucket工作区： https://bitbucket.org/{workspace}/workspace/settings/oauth-consumers
点击 “添加消费者”
填写：
- 名字: MCP Server （或任何名称）
- 回调URL: http://localhost:9876/callback （必填）
- 权限：选择以下内容：
  - 帐户：已读
  - 存储库：读、写、管理
  - 拉取请求：读取、写入
  - 问题：读，写
  - 管道：读、写
点击保存并注意钥匙（客户端ID）和秘密（客户机密）

步骤2：运行OAuth流

使用附带的辅助脚本进行身份验证：

# From the project directory
node scripts/oauth-flow.js "YOUR_CLIENT_ID" "YOUR_CLIENT_SECRET"

这将：

在端口9876上启动本地回叫服务器
打开浏览器进入Bitbucket的授权页面
授权后，显示要添加到MCP配置中的配置

步骤3：配置MCP客户端

将输出配置添加到MCP客户端配置文件中。

选项2：应用程序密码（简单设置）

供个人使用，无需OAuth设置：

转到Bitbucket： 个人设置 → 应用密码
点击 创建应用密码
为其命名并选择权限：
- 帐户：已读
- 存储库：读、写、管理
- 拉取请求：读取、写入
- 问题：读，写
- 管道：读、写
复制生成的密码

使用您的Bitbucket用户名和应用程序密码进行配置：

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["@lexmata/bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_ACCESS_TOKEN": "your-app-password"
      }
    }
  }
}

使用Cursor IDE

将以下内容添加到Cursor MCP配置文件中：

Linux: ~/.cursor/mcp.json macOS: ~/.cursor/mcp.json 视窗: %USERPROFILE%\.cursor\mcp.json

使用OAuth（推荐）

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["@lexmata/bitbucket-mcp"],
      "env": {
        "BITBUCKET_CLIENT_ID": "your-client-id",
        "BITBUCKET_CLIENT_SECRET": "your-client-secret",
        "BITBUCKET_ACCESS_TOKEN": "your-access-token",
        "BITBUCKET_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

当令牌过期时，服务器将使用刷新令牌自动刷新它们。如果刷新失败，将打开一个浏览器窗口进行重新身份验证。

使用应用程序密码

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["@lexmata/bitbucket-mcp"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_ACCESS_TOKEN": "your-app-password"
      }
    }
  }
}

使用Claude Desktop

将以下内容添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["@lexmata/bitbucket-mcp"],
      "env": {
        "BITBUCKET_CLIENT_ID": "your-client-id",
        "BITBUCKET_CLIENT_SECRET": "your-client-secret",
        "BITBUCKET_ACCESS_TOKEN": "your-access-token",
        "BITBUCKET_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

或者，如果全局安装：

{
  "mcpServers": {
    "bitbucket": {
      "command": "bitbucket-mcp",
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_ACCESS_TOKEN": "your-app-password"
      }
    }
  }
}

环境变量

变量	描述	必填
`BITBUCKET_CLIENT_ID`	OAuth消费者密钥	用于OAuth
`BITBUCKET_CLIENT_SECRET`	OAuth消费者秘密	适用于OAuth
`BITBUCKET_ACCESS_TOKEN`	OAuth访问令牌或应用程序密码	是
`BITBUCKET_REFRESH_TOKEN`	OAuth刷新令牌	用于OAuth
`BITBUCKET_USERNAME`	Bitbucket用户名	应用密码

许可证管理

OAuth令牌

访问令牌 2小时后过期
刷新令牌 用于自动获取新的访问令牌
令牌被持久化 ~/.config/bitbucket-mcp/tokens.json
如果令牌过期且刷新失败，浏览器将自动打开进行重新身份验证

重新验证

如果您需要手动重新进行身份验证：

node scripts/oauth-flow.js "YOUR_CLIENT_ID" "YOUR_CLIENT_SECRET"

或者删除令牌文件以触发重新身份验证：

rm ~/.config/bitbucket-mcp/tokens.json

可用工具

库管理

工具	说明
`list_repositories`	列出工作区中的存储库
`get_repository`	获取特定存储库的详细信息
`create_repository`	创建新存储库
`delete_repository`	删除存储库
`list_repository_forks`	列出存储库的所有分支

拉取请求

工具	说明
`list_pull_requests`	列出具有可选过滤功能的拉取请求
`get_pull_request`	获取特定拉取请求的详细信息
`create_pull_request`	创建新的pull请求
`update_pull_request`	更新拉取请求
`merge_pull_request`	合并拉取请求
`decline_pull_request`	拒绝拉取请求
`approve_pull_request`	批准拉取请求
`request_changes`	请求对pull请求进行更改
`list_pr_comments`	列出对pull请求的评论
`add_pr_comment`	在pull请求中添加注释
`get_pr_diff`	获取拉取请求的差异

分支

工具	说明
`list_branches`	列出存储库中的分支
`get_branch`	获取特定分支的详细信息
`create_branch`	创建新分支
`delete_branch`	删除分支

提交

工具	说明
`list_commits`	带有可选筛选的列表提交
`get_commit`	获取特定提交的详细信息
`get_commit_diff`	获取提交的差异

问题

工具	说明
`list_issues`	在存储库中列出问题
`get_issue`	获取特定问题的详细信息
`create_issue`	创建新问题
`update_issue`	更新问题
`delete_issue`	删除问题

管道

工具	说明
`list_pipelines`	列出管道运行
`get_pipeline`	获取管道运行的详细信息
`trigger_pipeline`	触发新的管道运行
`stop_pipeline`	停止正在运行的管道

代码搜索

工具	说明
`search_code`	跨存储库搜索代码

文件

工具	说明
`get_file_content`	获取文件内容

资源

服务器提供以下资源类型：

资源URI	描述
`bitbucket://repository/{workspace}/{repo}`	存储库信息
`bitbucket://pullrequest/{workspace}/{repo}/{id}`	拉取请求详细信息
`bitbucket://file/{workspace}/{repo}/{path}`	文件内容

例子

列出工作区中的存储库

Use the list_repositories tool with workspace "my-workspace"

创建pull请求

Use the create_pull_request tool with:
- workspace: "my-workspace"
- repo_slug: "my-repo"
- title: "Add new feature"
- source_branch: "feature/new-feature"
- destination_branch: "main"
- description: "This PR adds a new feature"

搜索代码

Use the search_code tool with:
- workspace: "my-workspace"
- search_query: "function handleError"

触发管道

Use the trigger_pipeline tool with:
- workspace: "my-workspace"
- repo_slug: "my-repo"
- ref_type: "branch"
- ref_name: "main"

发展

先决条件

Node.js 18+
pnpm 9+

设置

# Clone the repository
git clone https://github.com/lexmata/bitbucket-mcp.git
cd bitbucket-mcp

# Install dependencies
pnpm install

# Build
pnpm build

# Run in development mode
pnpm dev

脚本

脚本	描述
`pnpm build`	用SWC建造项目
`pnpm dev`	以开发模式运行
`pnpm start`	运行内置服务器
`pnpm typecheck`	运行TypeScript类型检查
`pnpm lint`	运行ESLint
`pnpm lint:fix`	修复ESLint问题
`pnpm format`	使用Prettier格式化代码
`pnpm format:check`	检查代码格式

OAuth流助手

这 scripts/oauth-flow.js 脚本提供了一种方便的身份验证方法：

node scripts/oauth-flow.js "CLIENT_ID" "CLIENT_SECRET"

此脚本：

在端口9876上启动本地HTTP服务器
打开浏览器进入Bitbucket的授权页面
处理OAuth回调
显示带有令牌的完整MCP配置

故障排除

“端口9876已在使用中”

另一个进程正在使用OAuth回调端口

使用端口9876关闭其他应用程序
请稍候，然后重试（之前的OAuth尝试可能仍在运行）

# Find and kill the process using port 9876
lsof -ti:9876 | xargs kill -9

“本地主机：9876返回未找到”

Bitbucket消费者中的OAuth回调URL不正确。确保设置为：

http://localhost:9876/callback

“令牌无效或已过期”

您的访问令牌已过期。服务器将自动：

尝试使用刷新令牌进行刷新
如果失败，请打开浏览器进行重新身份验证

要手动重新进行身份验证，请执行以下操作：

node scripts/oauth-flow.js "YOUR_CLIENT_ID" "YOUR_CLIENT_SECRET"

“身份验证失败（401）”

检查：

您的OAuth使用者具有正确的权限
您的应用程序密码（如果使用）具有所需的范围
对于应用程序密码，请确保 BITBUCKET_USERNAME 已设置

服务器未在Cursor中加载

验证您的 ~/.cursor/mcp.json 语法是有效的JSON
重新启动光标或重新加载窗口
检查MCP服务器日志是否有错误

许可证

看许可证了解详情。

贡献

欢迎投稿！请随时提交拉取请求。

克隆该仓库
创建功能分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add some amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求