使用说明

Atlassian比特桶MCP服务器

Atlassian Bitbucket Cloud的Node.js/TypeScript模型上下文协议（MCP）服务器。使AI系统（如Claude或Cursor AI等LLM）能够实时安全地与您的存储库、拉取请求、工作区和代码进行交互。

为什么要使用此服务器？

最小输入，最大输出：简单的标识符提供了全面的细节，不需要额外的标志。
丰富的代码可视化：通过文件统计、差异视图和智能上下文详细了解代码更改。
安全本地身份验证：使用您的凭据在本地运行，永远不要在远程服务器上存储令牌。
直观的Markdown响应：结构良好，所有输出的Markdown格式一致。
完整的Bitbucket集成：访问工作区、存储库、拉取请求、注释、代码搜索等。

什么是MCP？

模型上下文协议（MCP）是一个开放标准，用于将人工智能系统安全地连接到外部工具和数据源。该服务器为Bitbucket Cloud实现了MCP，使AI助手能够以编程方式与您的Bitbucket数据进行交互。

先决条件

Node.js （>=18.x）：下载
Bitbucket云账户

设置

第一步：身份验证

选择以下身份验证方法之一：

选项A:Bitbucket应用程序密码（推荐）

生成一个 Bitbucket应用程序密码.最小权限：

工作区：阅读
存储库：阅读
拉取请求：阅读

您还可以设置 BITBUCKET_DEFAULT_WORKSPACE 在未明确提供时指定默认工作区。

选项B：Atlassian API代币

生成一个大西洋API代币.

注：强烈建议使用Bitbucket应用程序密码，因为它们提供了更精细的、特定于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_工作区：列出可用工作区(query：str opt）。用途：查看可访问的工作区。
bb_get_工作空间：获取工作区详细信息(workspaceSlug：str请求）。用途：查看工作区信息。
bb_ls_repos：列出存储库(workspaceSlug：str opt， projectKey：str opt， query：str opt， role：str opt）。用途：查找存储库。
bb_get_repo：获取存储库详细信息(workspaceSlug：str请求， repoSlug：str请求）。用途：访问仓库信息。
bb_search：搜索Bitbucket内容(workspaceSlug：str请求， query：str请求， scope：str opt， language：str opt， extension：str opt）。用途：查找代码或PR。
bb_ls_prs：列出拉取请求(workspaceSlug：str请求， repoSlug：str请求， state：str opt）。使用：查看打开或合并的PR。
bb_get_pr：获取PR详细信息(workspaceSlug：str请求， repoSlug：str请求， prId：str请求）。用途：查看带有差异的PR详细信息。
bb_ls_pr_评论：列出公关评论(workspaceSlug：str请求， repoSlug：str请求， prId：str请求）。用途：查看公关讨论。
bb_add_pr注释：向PR添加评论(workspaceSlug：str请求， repoSlug：str请求， prId：str请求， content：str请求， inline：obj opt）。用途：为PR添加反馈。
bb_add_p：创建PR(workspaceSlug：str请求， repoSlug：str请求， title：str请求， sourceBranch：str请求， targetBranch：str opt）。用途：创建新的PR。
bb_add_branch：创建分支(workspaceSlug：str请求， repoSlug：str请求， newBranchName：str请求， sourceBranchOrCommit：str opt）。用途：创建要素分支。
bb_clone_repo：克隆存储库(workspaceSlug：str请求， repoSlug：str请求， targetPath：str请求）。使用：在本地克隆代码。
bb_get_commit_历史记录：获取提交历史记录(workspaceSlug：str请求， repoSlug：str请求， revision：str opt， path：str opt）。用途：查看代码历史记录。
bb_getfile：获取文件内容(workspaceSlug：str请求， repoSlug：str请求， filePath：str请求， revision：str opt）。用途：查看特定文件。
bb_diff_分支：显示分支之间的差异(workspaceSlug：str请求， repoSlug：str请求， sourceBranch：str请求， targetBranch：str请求）。用途：比较分支。
bb_diff_承诺：显示提交之间的差异(workspaceSlug：str请求， repoSlug：str请求， sourceCommit：str请求， targetCommit：str请求）。用途：比较提交。
bb_list_分支：列出分支(workspaceSlug：str请求， repoSlug：str请求， query：str opt， sort：str opt）。用途：查看所有分支。

MCP Tool Examples (Click to expand)

`bb_ls_workspaces`

列出所有工作区：

{}

搜索工作区：

{ "query": "devteam" }

`bb_get_workspace`

获取工作区详细信息：

{ "workspaceSlug": "acme-corp" }

`bb_ls_repos`

在工作区中列出存储库：

{ "workspaceSlug": "acme-corp", "projectKey": "PROJ" }

使用默认工作区列出仓库：

{ "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" }

`bb_ls_pr_comments`

列出公关评论：

{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "prId": "42" }

`bb_add_pr_comment`

添加一般性意见：

{
	"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工作区：列出工作区(--query).前任： mcp-atlassian-bitbucket ls-workspaces.
获取工作空间：获取工作区详细信息(--workspace-slug).前任： mcp-atlassian-bitbucket get-workspace --workspace-slug acme-corp.
ls仓库：列出存储库(--workspace-slug, --project-key, --query).前任： mcp-atlassian-bitbucket ls-repos --workspace-slug acme-corp.
获取回购：获取仓库详细信息(--workspace-slug, --repo-slug).前任： mcp-atlassian-bitbucket get-repo --workspace-slug acme-corp --repo-slug backend-api.
搜索：搜索代码(--workspace-slug, --query, --scope, --language).前任： mcp-atlassian-bitbucket search --workspace-slug acme-corp --query "auth".
ls pr：列出PR(--workspace-slug, --repo-slug, --state).前任： mcp-atlassian-bitbucket ls-prs --workspace-slug acme-corp --repo-slug backend-api.
获取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公关评论：列出公关评论(--workspace-slug, --repo-slug, --pr-id).前任： mcp-atlassian-bitbucket ls-pr-comments --workspace-slug acme-corp --repo-slug backend-api --pr-id 42.
添加公关评论：添加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".
添加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.
获取文件：获取文件内容(--workspace-slug, --repo-slug, --file-path).前任： mcp-atlassian-bitbucket get-file --workspace-slug acme-corp --repo-slug backend-api --file-path src/main.js.
添加分支：创建分支(--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.

CLI Command Examples (Click to expand)

列出和查看工作区/资源库

# 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

处理Pull请求

# 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详细信息或搜索结果。
元数据：时间戳、作者和统计数据。
差异：代码更改，语法突出显示分支/提交之间的差异。

Response Format Examples (Click to expand)

存储库详细信息

# 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请求审核

# 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).
打开一个pull请求。

看贡献.md 了解详情。

许可证

ISC许可证

使用说明

Atlassian比特桶MCP服务器

为什么要使用此服务器？

什么是MCP？

先决条件

设置

第一步：身份验证

选项A:Bitbucket应用程序密码（推荐）

选项B：Atlassian API代币

步骤2：配置凭据

选项A:MCP配置文件（推荐）

选项B：环境变量

步骤3：安装并运行

快速入门 npx

全球安装

步骤4：连接到AI助手

MCP工具

bb_ls_workspaces

bb_get_workspace

bb_ls_repos

bb_get_repo

bb_search

bb_ls_prs

bb_get_pr

bb_ls_pr_comments

bb_add_pr_comment

bb_add_pr

bb_add_branch

bb_clone_repo

bb_get_commit_history

bb_get_file

bb_diff_branches

bb_diff_commits

bb_list_branches