Atlassian Bitbucket MCP Server

Atlassian Bitbucket MCP Server

镜子 (jìng zi)

MCP-Mirror

开发者工具
访问服务器

README

Atlassian Bitbucket MCP 服务器

本项目提供了一个模型上下文协议 (MCP) 服务器，它充当 AI 助手（如 Anthropic 的 Claude、Cursor AI 或其他兼容 MCP 的客户端）和您的 Atlassian Bitbucket 实例之间的桥梁。它允许 AI 安全地访问和实时地与您的存储库、拉取请求和工作区进行交互。

什么是 MCP 以及为什么要使用此服务器？

模型上下文协议 (MCP) 是一种开放标准，使 AI 模型能够安全地连接到外部工具和数据源。此服务器专门为 Bitbucket Cloud 实现了 MCP。

优势：

  • 实时访问： 您的 AI 助手可以直接访问最新的 Bitbucket 数据（存储库、PR 等）。
  • 消除复制/粘贴： 无需手动在 Bitbucket 和您的 AI 助手之间传输信息。
  • 增强的 AI 功能： 使 AI 能够分析存储库、审查拉取请求、理解代码上下文，并直接与您的版本控制系统一起工作。
  • 安全性： 您可以通过 API 凭据（Atlassian API 令牌或 Bitbucket 应用密码）控制访问。AI 通过服务器进行交互，敏感操作保持在受控范围内。

接口理念：简单输入，丰富输出

此服务器遵循“最小接口，最大细节”的方法：

  1. 简单工具： 仅请求必要的标识符（如 workspaceSlug、repoSlug、prId）。
  2. 丰富细节： 当您请求特定项目（如 get-repository）时，服务器默认提供所有相关信息（描述、所有者、链接等），而无需额外的标志。

可用工具

此 MCP 服务器为您的 AI 助手提供以下工具：

列出工作区 (list-workspaces)

目的： 发现您可以访问的可用 Bitbucket 工作区，并找到它们的“slug”（唯一标识符）。

使用场景： 当您需要知道哪些工作区可用，或者找到特定工作区的 slug 以用于其他工具时。

对话示例： “显示我所有的 Bitbucket 工作区。”

参数示例： {}（基本列表不需要参数）或 { query: "devteam" }（用于过滤）。

获取工作区 (get-workspace)

目的： 使用工作区的 slug 检索有关 特定 工作区的详细信息。

使用场景： 当您知道工作区 slug 并且需要其完整详细信息或指向其内容的链接时。

对话示例： “告诉我更多关于 'acme-corp' 工作区的信息。”

参数示例： { workspaceSlug: "acme-corp" }

列出存储库 (list-repositories)

目的： 列出特定工作区中的存储库，并找到它们的“slug”。需要工作区 slug。

使用场景： 当您需要在已知工作区中查找存储库或获取特定存储库的 slug 时。

对话示例： “列出 'acme-corp' 工作区中的存储库。”

参数示例： { workspaceSlug: "acme-corp" } 或 { workspaceSlug: "acme-corp", query: "backend" }（用于过滤）。

获取存储库 (get-repository)

目的： 使用工作区和存储库 slug 检索有关 特定 存储库的详细信息。

使用场景： 当您知道工作区和存储库 slug 并且需要完整详细信息（如描述、语言、所有者等）时。

对话示例： “显示 'acme-corp' 工作区中 'backend-api' 存储库的详细信息。”

参数示例： { workspaceSlug: "acme-corp", repoSlug: "backend-api" }

列出拉取请求 (list-pull-requests)

目的： 列出特定存储库中的拉取请求。需要工作区和存储库 slug。

使用场景： 当您需要在已知存储库中查找打开/合并等的拉取请求，或者获取特定 PR 的 ID 时。

对话示例： “显示 'acme-corp/frontend-app' 存储库的打开的拉取请求。”

参数示例： { workspaceSlug: "acme-corp", repoSlug: "frontend-app", state: "OPEN" }

获取拉取请求 (get-pull-request)

目的： 使用工作区 slug、存储库 slug 和 PR ID 检索有关 特定 拉取请求的详细信息。

使用场景： 当您知道特定 PR 的标识符并且需要其完整描述、审查者、状态、分支等时。

对话示例： “获取 'acme-corp/frontend-app' 存储库中拉取请求 #42 的详细信息。”

参数示例： { workspaceSlug: "acme-corp", repoSlug: "frontend-app", prId: "42" }

添加拉取请求评论 (add-pr-comment)

目的： 向拉取请求添加评论，包括常规 PR 评论和内联代码评论。

使用场景： 当您需要提供反馈、提出问题或与特定 PR 上的贡献者进行交流时。

对话示例： “在 'acme-corp/frontend-app' 存储库中向拉取请求 #42 添加评论，内容为 '看起来可以合并了'。”

参数示例： { workspaceSlug: "acme-corp", repoSlug: "frontend-app", prId: "42", content: "看起来可以合并了" } 或带有内联评论：{ workspaceSlug: "acme-corp", repoSlug: "frontend-app", prId: "42", content: "这里考虑使用常量", inline: { path: "src/utils.js", line: 42 } }

创建拉取请求 (create-pull-request)

目的： 在存储库中从一个分支到另一个分支创建一个新的拉取请求。

使用场景： 当您需要为已完成的功能或错误修复启动代码审查，或者想要将更改从功能分支合并到主分支时。

对话示例： “在 'acme-corp/frontend-app' 存储库中，从 'feature/new-login' 分支到 'main' 创建一个标题为 '添加新登录屏幕' 的拉取请求。”

参数示例： { workspaceSlug: "acme-corp", repoSlug: "frontend-app", title: "添加新登录屏幕", sourceBranch: "feature/new-login" }

前提条件

  • Node.js 和 npm： 确保您已安装 Node.js（包括 npm）。从 nodejs.org 下载。
  • Bitbucket 帐户： 一个活跃的 Bitbucket Cloud 帐户，可以访问您想要连接的工作区和存储库。

快速入门指南

按照以下步骤将您的 AI 助手连接到 Bitbucket：

步骤 1：设置身份验证

您有两种选择来验证 Bitbucket 的身份：

选项 A：Bitbucket 应用密码（推荐用于仅 Bitbucket 的使用）

重要提示： 将您的应用密码视为密码。不要共享它或将其提交到版本控制。

  1. 导航到您的 Bitbucket 个人设置： https://bitbucket.org/account/settings/app-passwords/
  2. 单击 创建应用密码。
  3. 给它一个 标签（例如，mcp-bitbucket-access）。
  4. 授予以下 权限（至少）：
    • 工作区：读取
    • 存储库：读取
    • 拉取请求：读取
  5. 单击 创建。
  6. 立即复制生成的应用密码。 您将无法再次看到它。安全地存储它。

选项 B：Atlassian API 令牌（如果连接其他 Atlassian 工具（如 Jira/Confluence），请使用此选项）

重要提示： 将您的 API 令牌视为密码。

  1. 转到您的 Atlassian API 令牌管理页面： https://id.atlassian.com/manage-profile/security/api-tokens
  2. 单击 创建 API 令牌。
  3. 给它一个描述性的 标签（例如，mcp-bitbucket-access）。
  4. 单击 创建。
  5. 立即复制生成的 API 令牌。 安全地存储它。

步骤 2：配置服务器凭据

选择以下方法 之一：

方法 A：全局 MCP 配置文件（推荐）

这可以使凭据保持分离和组织。

  1. 创建目录（如果需要）：~/.mcp/

  2. 创建/编辑文件： ~/.mcp/configs.json

  3. 添加配置： 粘贴以下 JSON 结构 之一，对应于您选择的身份验证方法，替换占位符：

    使用 Bitbucket 应用密码：

    {
	"@aashari/mcp-server-atlassian-bitbucket": {
		"environments": {
			"ATLASSIAN_BITBUCKET_USERNAME": "<YOUR_BITBUCKET_USERNAME>",
			"ATLASSIAN_BITBUCKET_APP_PASSWORD": "<YOUR_COPIED_APP_PASSWORD>"
		}
	}
}
    • <YOUR_BITBUCKET_USERNAME>：您的 Bitbucket 用户名。
    • <YOUR_COPIED_APP_PASSWORD>：来自步骤 1 的应用密码。

    使用 Atlassian API 令牌：

    {
	"@aashari/mcp-server-atlassian-bitbucket": {
		"environments": {
			"ATLASSIAN_SITE_NAME": "<YOUR_ATLASSIAN_SITE_NAME_UNUSED_BUT_NEEDED>",
			"ATLASSIAN_USER_EMAIL": "<YOUR_ATLASSIAN_EMAIL>",
			"ATLASSIAN_API_TOKEN": "<YOUR_COPIED_API_TOKEN>"
		}
	}
}
    • <YOUR_ATLASSIAN_SITE_NAME_UNUSED_BUT_NEEDED>：输入任何值（如 bitbucket）。此字段是底层传输所必需的，但在使用 API 令牌时，不用于 Bitbucket API 身份验证。
    • <YOUR_ATLASSIAN_EMAIL>：您的 Atlassian 帐户电子邮件。
    • <YOUR_COPIED_API_TOKEN>：来自步骤 1 的 API 令牌。

方法 B：环境变量（替代方法）

运行服务器时设置环境变量。选择与您的身份验证匹配的集合：

使用 Bitbucket 应用密码：

ATLASSIAN_BITBUCKET_USERNAME="<YOUR_USERNAME>" \
ATLASSIAN_BITBUCKET_APP_PASSWORD="<YOUR_APP_PASSWORD>" \
npx -y @aashari/mcp-server-atlassian-bitbucket

使用 Atlassian API 令牌：

ATLASSIAN_SITE_NAME="bitbucket" \
ATLASSIAN_USER_EMAIL="<YOUR_EMAIL>" \
ATLASSIAN_API_TOKEN="<YOUR_API_TOKEN>" \
npx -y @aashari/mcp-server-atlassian-bitbucket

步骤 3：连接您的 AI 助手

配置您的 MCP 客户端（Claude Desktop、Cursor 等）以运行此服务器。

Claude Desktop

  1. 打开设置（齿轮图标）> 编辑配置。

  2. 添加或合并到 mcpServers：

    {
	"mcpServers": {
		"aashari/mcp-server-atlassian-bitbucket": {
			"command": "npx",
			"args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"]
		}
	}
}

  3. 保存并 重启 Claude Desktop。

  4. 验证： 单击“工具”（锤子）图标；应列出 Bitbucket 工具。

Cursor AI

  1. 命令面板 (Cmd+Shift+P / Ctrl+Shift+P) > Cursor 设置 > MCP。
  2. 单击 + 添加新的 MCP 服务器。
  3. 输入：
    • 名称：aashari/mcp-server-atlassian-bitbucket
    • 类型：command
    • 命令：npx -y @aashari/mcp-server-atlassian-bitbucket
  4. 单击 添加。
  5. 验证： 等待服务器名称旁边的指示器变为绿色。

步骤 4：使用工具

您现在可以向您的 AI 助手提出与您的 Bitbucket 实例相关的问题：

  • “列出我可以访问的所有 Bitbucket 工作区。”
  • “显示 'dev-team' 工作区中的所有存储库。”
  • “获取有关 'dev-team' 工作区中 'main-api' 存储库的信息。”
  • “显示 'dev-team/main-api' 存储库的打开的拉取请求。”
  • “总结 'dev-team/main-api' 存储库中的拉取请求 #42。”
  • “在 'dev-team/main-api' 存储库中，从 'feature/login' 分支到 'main' 创建一个标题为 '添加新登录功能' 的拉取请求。”

用作命令行工具 (CLI)

您也可以直接从终端使用此软件包：

使用 npx 快速使用

无需安装 - 使用 npx 直接运行：

# 列出工作区
npx -y @aashari/mcp-server-atlassian-bitbucket list-workspaces

# 获取存储库详细信息
npx -y @aashari/mcp-server-atlassian-bitbucket get-repository --workspace my-team --repository my-api

# 列出拉取请求
npx -y @aashari/mcp-server-atlassian-bitbucket list-pull-requests --workspace my-team --repository my-api --state OPEN

全局安装

为了频繁使用，您可以将软件包全局安装在您的系统上：

  1. 使用 npm 全局安装：

    npm install -g @aashari/mcp-server-atlassian-bitbucket

  2. 通过检查版本验证安装：

    mcp-atlassian-bitbucket --version

  3. 使用命令，无需 npx 前缀：

    # 列出工作区
mcp-atlassian-bitbucket list-workspaces

# 获取工作区详细信息
mcp-atlassian-bitbucket get-workspace --workspace my-team

# 列出工作区中的存储库
mcp-atlassian-bitbucket list-repositories --workspace my-team

# 获取存储库详细信息
mcp-atlassian-bitbucket get-repository --workspace my-team --repository my-api

# 列出拉取请求
mcp-atlassian-bitbucket list-pull-requests --workspace my-team --repository my-api --state OPEN

使用全局安装进行配置

全局安装后，您仍然可以使用相同的配置方法：

  1. 使用环境变量：

    # 使用 Bitbucket 应用密码
ATLASSIAN_BITBUCKET_USERNAME="<YOUR_USERNAME>" \
ATLASSIAN_BITBUCKET_APP_PASSWORD="<YOUR_APP_PASSWORD>" \
mcp-atlassian-bitbucket list-workspaces

# 使用 Atlassian API 令牌
ATLASSIAN_SITE_NAME="bitbucket" \
ATLASSIAN_USER_EMAIL="<YOUR_EMAIL>" \
ATLASSIAN_API_TOKEN="<YOUR_API_TOKEN>" \
mcp-atlassian-bitbucket list-workspaces

  2. 使用全局 MCP 配置文件（推荐）： 按照快速入门指南中的描述设置 ~/.mcp/configs.json 文件。

许可证

ISC

推荐服务器

Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
MCP Package Docs Server

MCP Package Docs Server

促进大型语言模型高效访问和获取 Go、Python 和 NPM 包的结构化文档，通过多语言支持和性能优化来增强软件开发。

精选
本地
TypeScript
Claude Code MCP

Claude Code MCP

一个实现了 Claude Code 作为模型上下文协议（Model Context Protocol, MCP）服务器的方案，它可以通过标准化的 MCP 接口来使用 Claude 的软件工程能力（代码生成、编辑、审查和文件操作）。

精选
本地
JavaScript
@kazuph/mcp-taskmanager

@kazuph/mcp-taskmanager

用于任务管理的模型上下文协议服务器。它允许 Claude Desktop（或任何 MCP 客户端）在基于队列的系统中管理和执行任务。

精选
本地
JavaScript
mermaid-mcp-server

mermaid-mcp-server

一个模型上下文协议 (MCP) 服务器，用于将 Mermaid 图表转换为 PNG 图像。

精选
JavaScript
Jira-Context-MCP

Jira-Context-MCP

MCP 服务器向 AI 编码助手（如 Cursor）提供 Jira 工单信息。

精选
TypeScript
Linear MCP Server

Linear MCP Server

一个模型上下文协议（Model Context Protocol）服务器，它与 Linear 的问题跟踪系统集成，允许大型语言模型（LLM）通过自然语言交互来创建、更新、搜索和评论 Linear 问题。

精选
JavaScript
Sequential Thinking MCP Server

Sequential Thinking MCP Server

这个服务器通过将复杂问题分解为顺序步骤来促进结构化的问题解决，支持修订，并通过完整的 MCP 集成来实现多条解决方案路径。

精选
Python
Curri MCP Server

Curri MCP Server

通过管理文本笔记、提供笔记创建工具以及使用结构化提示生成摘要，从而实现与 Curri API 的交互。

官方
本地
JavaScript