Atlassian Bitbucket MCP 服务器

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

NPM 版本构建状态

为什么要使用此服务器？

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

Related MCP server: GitHub MCP Tools

什么是 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`

列出所有工作区：

{}

搜索工作区：

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

列出 PR 评论：

{ "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-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 许可证

Atlassian Bitbucket MCP 服务器

为什么要使用此服务器？

什么是 MCP？

先决条件

设置

步骤 1：验证

选项 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