Atlassian Bitbucket MCP 服务器
适用于 Atlassian Bitbucket Cloud 的 Node.js/TypeScript 模型上下文协议 (MCP) 服务器。它使 AI 系统（例如 Claude 或 Cursor AI 等 LLM）能够安全地实时与您的代码库、拉取请求、工作区和代码进行交互。
为什么要使用此服务器？
- 最少输入，最大输出：简单的标识符无需额外的标志即可提供全面的详细信息。
- 丰富的代码可视化：通过文件统计、差异视图和智能上下文深入了解代码变化。
- 安全的本地身份验证：使用您的凭据在本地运行，永远不会在远程服务器上存储令牌。
- 直观的 Markdown 响应：所有输出均采用结构良好、一致的 Markdown 格式。
- 完整的 Bitbucket 集成：访问工作区、存储库、拉取请求、评论、代码搜索等。
什么是 MCP？
模型上下文协议 (MCP) 是一种开放标准，用于将 AI 系统安全地连接到外部工具和数据源。此服务器为 Bitbucket Cloud 实现了 MCP，使 AI 助手能够以编程方式与您的 Bitbucket 数据进行交互。
先决条件
- Node.js （>=18.x）：下载
- Bitbucket 云帐户
设置
步骤 1：验证
选择以下身份验证方法之一：
选项 A：Bitbucket 应用程序密码（推荐）
从Bitbucket App Passwords生成一个。最低权限：
您还可以设置BITBUCKET_DEFAULT_WORKSPACE来指定未明确提供时的默认工作区。
选项 B：Atlassian API 令牌
从Atlassian API Tokens生成一个。
**注意：**强烈建议使用 Bitbucket App Passwords，因为它们提供更细粒度的、特定于 Bitbucket 的权限。
第 2 步：配置凭证
选项 A：MCP 配置文件（推荐）
编辑或创建~/.mcp/configs.json ：
使用 Bitbucket 应用程序密���：
{
"bitbucket": {
"environments": {
"ATLASSIAN_BITBUCKET_USERNAME": "<your_username>",
"ATLASSIAN_BITBUCKET_APP_PASSWORD": "<your_app_password>"
}
}
}
使用 Atlassian API 令牌：
{
"bitbucket": {
"environments": {
"ATLASSIAN_SITE_NAME": "bitbucket",
"ATLASSIAN_USER_EMAIL": "<your_email>",
"ATLASSIAN_API_TOKEN": "<your_api_token>"
}
}
}
选项 B：环境变量
export ATLASSIAN_BITBUCKET_USERNAME="<your_username>"
export ATLASSIAN_BITBUCKET_APP_PASSWORD="<your_app_password>"
步骤3：安装并运行
npx快速入门
npx -y @aashari/mcp-server-atlassian-bitbucket ls-workspaces
全局安装
npm install -g @aashari/mcp-server-atlassian-bitbucket
mcp-atlassian-bitbucket ls-workspaces
步骤4：连接到AI助手
配置与 MCP 兼容的客户端（例如 Claude、Cursor AI）：
{
"mcpServers": {
"bitbucket": {
"command": "npx",
"args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"]
}
}
}
MCP 工具
MCP 工具使用snake_case名称、 camelCase参数，并返回 Markdown 格式的响应。
- bb_ls_workspaces ：列出可用的工作区（
query ：str opt）。用途：查看可访问的工作区。 - bb_get_workspace ：获取工作区详细信息（
workspaceSlug ：str req）。用途：查看工作区信息。 - bb_ls_repos ：列出存储库（
workspaceSlug ：str opt， projectKey ：str opt， query ：str opt， role ：str opt）。用途：查找存储库。 - bb_get_repo ：获取存储库详细信息（
workspaceSlug ：str req， repoSlug ：str req）。用途：访问存储库信息。 - bb_search ：搜索 Bitbucket 内容（
workspaceSlug ：str req、 query ：str req、 scope ：str opt、 language ：str opt、 extension ：str opt）。用途：查找代码或 PR。 - bb_ls_prs ：列出拉取请求（
workspaceSlug ：str req、 repoSlug ：str req、 state ：str opt）。用途：查看打开或合并的 PR。 - bb_get_pr ：获取 PR 详细信息（
workspaceSlug ：str req、 repoSlug ：str req、 prId ：str req）。用途：查看带有差异的 PR 详细信息。 - bb_ls_pr_comments ：列出 PR 评论（
workspaceSlug ：str req、 repoSlug ：str req、 prId ：str req）。用途：查看 PR 讨论。 - bb_add_pr_comment ：向 PR 添加评论（
workspaceSlug ：str req、 repoSlug ：str req、 prId ：str req、 content ：str req、 inline ：obj opt）。用途：向 PR 添加反馈。 - bb_add_pr ：创建一个 PR（
workspaceSlug ：str req、 repoSlug ：str req、 title ：str req、 sourceBranch ：str req、 targetBranch ：str opt）。用途：创建新的 PR。 - bb_add_branch ：创建一个分支（
workspaceSlug ：str req， repoSlug ：str req， newBranchName ：str req， sourceBranchOrCommit ：str opt）。用途：创建一个功能分支。 - bb_clone_repo ：克隆存储库（
workspaceSlug ：str req， repoSlug ：str req， targetPath ：str req）。用途：本地克隆代码。 - bb_get_commit_history ：获取提交历史记录（
workspaceSlug ：str req， repoSlug ：str req， revision ：str opt， path ：str opt）。用途：查看代码历史记录。 - bb_get_file ：获取文件内容（
workspaceSlug ：str req、 repoSlug ：str req、 filePath ：str req、 revision ：str opt）。用途：查看特定文件。 - bb_diff_branches ：显示分支之间的差异（
workspaceSlug ：str req、 repoSlug ：str req、 sourceBranch ：str req、 targetBranch ：str req）。用途：比较分支。 - bb_diff_commits ：显示提交之间的差异（
workspaceSlug ：str req、 repoSlug ：str req、 sourceCommit ：str req、 targetCommit ：str req）。用途：比较提交。 - bb_list_branches ：列出分支（
workspaceSlug ：str req、 repoSlug ：str req、 query ：str opt、 sort ：str opt）。用途：查看所有分支。
bb_ls_workspaces
列出所有工作区：
搜索工作区：
bb_get_workspace
获取工作区详细信息：
{ "workspaceSlug": "acme-corp" }
bb_ls_repos
列出工作区中的存储库：
{ "workspaceSlug": "acme-corp", "projectKey": "PROJ" }
使用默认工作区列出存储库：
bb_get_repo
获取存储库详细信息：
{ "workspaceSlug": "acme-corp", "repoSlug": "backend-api" }
bb_search
搜索代码：
{
"workspaceSlug": "acme-corp",
"query": "Logger",
"scope": "code",
"language": "typescript"
}
bb_ls_prs
列出开放的 PR：
{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "state": "OPEN" }
bb_get_pr
获取 PR 详细信息：
{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "prId": "42" }
列出 PR 评论：
{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "prId": "42" }
添加一般评论：
{
"workspaceSlug": "acme-corp",
"repoSlug": "frontend-app",
"prId": "42",
"content": "Looks good."
}
添加内联评论：
{
"workspaceSlug": "acme-corp",
"repoSlug": "frontend-app",
"prId": "42",
"content": "Consider refactoring.",
"inline": { "path": "src/utils.js", "line": 42 }
}
bb_add_pr
创建拉取请求：
{
"workspaceSlug": "acme-corp",
"repoSlug": "frontend-app",
"title": "Add login screen",
"sourceBranch": "feature/login"
}
bb_add_branch
创建新分支：
{
"workspaceSlug": "acme-corp",
"repoSlug": "frontend-app",
"newBranchName": "feature/new-feature",
"sourceBranchOrCommit": "main"
}
bb_clone_repo
克隆存储库：
{
"workspaceSlug": "acme-corp",
"repoSlug": "backend-api",
"targetPath": "/Users/me/projects"
}
bb_get_commit_history
查看提交历史记录：
{
"workspaceSlug": "acme-corp",
"repoSlug": "backend-api"
}
过滤提交历史记录：
{
"workspaceSlug": "acme-corp",
"repoSlug": "backend-api",
"revision": "develop",
"path": "src/main/java/com/acme/service/UserService.java"
}
bb_get_file
获取文件内容：
{
"workspaceSlug": "acme-corp",
"repoSlug": "backend-api",
"filePath": "src/main/java/com/acme/service/Application.java",
"revision": "main"
}
bb_diff_branches
比较分支：
{
"workspaceSlug": "acme-corp",
"repoSlug": "web-app",
"sourceBranch": "develop",
"targetBranch": "main"
}
bb_diff_commits
比较提交：
{
"workspaceSlug": "acme-corp",
"repoSlug": "web-app",
"sourceCommit": "a1b2c3d",
"targetCommit": "e4f5g6h"
}
bb_list_branches
列出所有分支：
{
"workspaceSlug": "acme-corp",
"repoSlug": "frontend-app"
}
已过滤的分支：
{
"workspaceSlug": "acme-corp",
"repoSlug": "frontend-app",
"query": "feature/",
"sort": "name"
}
CLI 命令
CLI 命令使用kebab-case )。运行--help获取详细信息（例如， mcp-atlassian-bitbucket ls-workspaces --help ）。
- ls-workspaces ：列出工作区（
--query ）。例如： mcp-atlassian-bitbucket ls-workspaces 。 - get-workspace ：获取工作区详情 (
--workspace-slug )。例如： mcp-atlassian-bitbucket get-workspace --workspace-slug acme-corp 。 - ls-repos ：列出仓库（
--workspace-slug 、 --project-key 、 --query ）。例如： mcp-atlassian-bitbucket ls-repos --workspace-slug acme-corp 。 - get-repo ：获取仓库详情（
--workspace-slug ， --repo-slug ）。例如： mcp-atlassian-bitbucket get-repo --workspace-slug acme-corp --repo-slug backend-api 。 - search ：搜索代码（
--workspace-slug 、 --query 、 --scope 、 --language ）。例如： mcp-atlassian-bitbucket search --workspace-slug acme-corp --query "auth" 。 - ls-prs ：列出 PR（
--workspace-slug 、 --repo-slug 、 --state ）。例如： mcp-atlassian-bitbucket ls-prs --workspace-slug acme-corp --repo-slug backend-api 。 - get-pr ：获取 PR 详情（
--workspace-slug 、 --repo-slug 、 --pr-id ）。例如： mcp-atlassian-bitbucket get-pr --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 。 - ls-pr-comments ：列出 PR 注释（
--workspace-slug 、 --repo-slug 、 --pr-id ）。例如： mcp-atlassian-bitbucket ls-pr-comments --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 。 - add-pr-comment ：添加 PR 评论（
--workspace-slug 、 --repo-slug 、 --pr-id 、 --content ）。例如： mcp-atlassian-bitbucket add-pr-comment --workspace-slug acme-corp --repo-slug backend-api --pr-id 42 --content "Looks good" 。 - add-pr ：创建 PR（
--workspace-slug 、 --repo-slug 、 --title 、 --source-branch ）。例如： mcp-atlassian-bitbucket add-pr --workspace-slug acme-corp --repo-slug backend-api --title "New feature" --source-branch feature/login 。 - get-file ：获取文件内容（
--workspace-slug 、 --repo-slug 、 --file-path ）。例如： mcp-atlassian-bitbucket get-file --workspace-slug acme-corp --repo-slug backend-api --file-path src/main.js 。 - add-branch ：创建分支（
--workspace-slug 、 --repo-slug 、 --new-branch-name ）。例如： mcp-atlassian-bitbucket add-branch --workspace-slug acme-corp --repo-slug backend-api --new-branch-name feature/new 。
列出并查看工作区/存储库
# List all workspaces
mcp-atlassian-bitbucket ls-workspaces
# Get details of a specific workspace
mcp-atlassian-bitbucket get-workspace --workspace-slug acme-corp
# List repositories in a workspace
mcp-atlassian-bitbucket ls-repos --workspace-slug acme-corp --project-key PROJ
# Get details of a specific repository
mcp-atlassian-bitbucket get-repo --workspace-slug acme-corp --repo-slug backend-api
使用拉取请求
# List open pull requests in a repository
mcp-atlassian-bitbucket ls-prs --workspace-slug acme-corp --repo-slug frontend-app --state OPEN
# Get details of a specific pull request with code changes
mcp-atlassian-bitbucket get-pr --workspace-slug acme-corp --repo-slug frontend-app --pr-id 42
# List comments on a pull request
mcp-atlassian-bitbucket ls-pr-comments --workspace-slug acme-corp --repo-slug frontend-app --pr-id 42
# Add a comment to a pull request
mcp-atlassian-bitbucket add-pr-comment --workspace-slug acme-corp --repo-slug frontend-app --pr-id 42 --content "Looks good to merge."
# Create a new pull request
mcp-atlassian-bitbucket add-pr --workspace-slug acme-corp --repo-slug frontend-app --title "Add login screen" --source-branch feature/login
代码和提交
# Search for code
mcp-atlassian-bitbucket search --workspace-slug acme-corp --query "Logger" --scope code --language typescript
# View commit history
mcp-atlassian-bitbucket get-commit-history --workspace-slug acme-corp --repo-slug backend-api --revision develop
# Get file content
mcp-atlassian-bitbucket get-file --workspace-slug acme-corp --repo-slug backend-api --file-path "src/Application.java" --revision main
# Compare branches
mcp-atlassian-bitbucket diff-branches --workspace-slug acme-corp --repo-slug web-app --source-branch develop --target-branch main
# Compare commits
mcp-atlassian-bitbucket diff-commits --workspace-slug acme-corp --repo-slug web-app --source-commit a1b2c3d --target-commit e4f5g6h
分支机构管理
# List branches
mcp-atlassian-bitbucket list-branches --workspace-slug acme-corp --repo-slug frontend-app --query "feature/" --sort name
# Create a new branch
mcp-atlassian-bitbucket add-branch --workspace-slug acme-corp --repo-slug frontend-app --new-branch-name feature/new-feature --source-branch-or-commit main
# Clone a repository
mcp-atlassian-bitbucket clone --workspace-slug acme-corp --repo-slug backend-api --target-path ./cloned-projects
响应格式
所有回复均为 Markdown 格式，包括：
- 标题：执行的操作或查看的实体。
- 上下文：工作区、存储库、拉取请求或分支信息。
- 内容：文件内容、PR 详细信息或搜索结果等主要数据。
- 元数据：时间戳、作者和统计数据。
- 差异：代码更改，语法突出显示分支/提交之间的差异。
存储库详细信息
# Repository: backend-api
**Workspace:** acme-corp
**Full Name:** acme-corp/backend-api
**Language:** Java
**Created:** 2024-01-15 by John Smith
**Updated:** 2025-05-10 (2 days ago)
## Overview
Spring Boot backend API for the ACME product suite.
## Statistics
- **Default Branch:** main
- **Size:** 24.5 MB
- **Commits:** 358
- **Open PRs:** 4
- **Forks:** 3
## Recent Activity
- PR #42: "Add OAuth2 support" by Jane Doe (Open)
- PR #41: "Fix pagination bug" by Alex Kim (Merged)
- PR #40: "Update dependencies" by John Smith (Merged)
*Repository URL: https://bitbucket.org/acme-corp/backend-api*
拉取请求审查
# Pull Request #42: Add OAuth2 support
**Repository:** acme-corp/backend-api
**Author:** Jane Doe
**State:** OPEN
**Created:** 2025-05-15 (4 days ago)
**Updated:** 2025-05-18 (yesterday)
## Description
Implements OAuth2 authentication flow with support for:
- Authorization code grant
- Refresh tokens
- Token caching
## Changes
- **Files changed:** 7
- **Additions:** 245 lines
- **Deletions:** 32 lines
## Diff for src/auth/OAuthService.java
@@ -10,6 +10,25 @@ public class OAuthService {
private final TokenRepository tokenRepository;
private final HttpClient httpClient;
+ @Autowired
+ public OAuthService(
+ TokenRepository tokenRepository,
+ HttpClient httpClient) {
+ this.tokenRepository = tokenRepository;
+ this.httpClient = httpClient;
+ }
+
+ public TokenResponse refreshToken(String refreshToken) {
+ // Validate refresh token
+ if (StringUtils.isEmpty(refreshToken)) {
+ throw new InvalidTokenException("Refresh token cannot be empty");
+ }
+
+ // Call OAuth server for new access token
+ return httpClient.post("/oauth/token")
+ .body(Map.of("grant_type", "refresh_token", "refresh_token", refreshToken))
+ .execute()
+ .as(TokenResponse.class);
+ }
## Comments (3)
1. **John Smith** (2 days ago):
> Please add unit tests for the refresh token flow
2. **Jane Doe** (yesterday):
> Added tests in the latest commit
3. **Approval by:** Alex Kim (yesterday)
*Pull Request URL: https://bitbucket.org/acme-corp/backend-api/pull-requests/42*
发展
# Clone repository
git clone https://github.com/aashari/mcp-server-atlassian-bitbucket.git
cd mcp-server-atlassian-bitbucket
# Install dependencies
npm install
# Run in development mode
npm run dev:server
# Run tests
npm test
贡献
欢迎投稿！请：
- 分叉存储库。
- 创建功能分支（
git checkout -b feature/xyz ）。 - 提交更改（
git commit -m "Add xyz feature" ）。 - 推送到分支（
git push origin feature/xyz ）。 - 打开拉取请求。
有关详细信息，请参阅CONTRIBUTING.md 。
执照
ISC 许可证