MCP 服务器

Atlassian Bitbucket MCP Server

一个集成工具，使像 Claude 这样的人工智能助手能够直接访问和交互 Bitbucket 仓库、拉取请求和代码，而无需复制/粘贴操作。

Tools

list-workspaces

List Bitbucket workspaces available to your account. PURPOSE: Discovers workspaces you have access to with their slugs, names, and permission levels to help navigate Bitbucket's organization structure. WHEN TO USE: - When you need to discover what workspaces exist in your Bitbucket account - When you want to find the slugs needed for other Bitbucket operations - When you need to check what workspaces you have access to and their permission levels - Before accessing repositories or pull requests that require workspace information - When you're unfamiliar with the workspace organization structure WHEN NOT TO USE: - When you already know the workspace slug (use get-workspace or list-repositories instead) - When you need detailed workspace information (use get-workspace instead) - When you need to find specific repositories (use list-repositories after identifying the workspace) RETURNS: Formatted list of workspaces with slugs, names, and permission information, plus pagination details if available. EXAMPLES: - List all workspaces: {} - With sorting: {sort: "name"} - With pagination: {limit: 10, cursor: "next-page-token"} ERRORS: - Authentication failures: Check your Bitbucket credentials - No workspaces found: You might not have access to any workspaces - Rate limiting: Use pagination and reduce query frequency

get-workspace

Get detailed information about a specific Bitbucket workspace by slug. PURPOSE: Retrieves comprehensive workspace metadata including projects, permissions, and configuration. WHEN TO USE: - When you need detailed information about a specific workspace - When you need to check workspace permissions or membership - When you need to verify workspace settings or configuration - After using list-workspaces to identify the relevant workspace - Before performing operations that require detailed workspace context WHEN NOT TO USE: - When you don't know which workspace to look for (use list-workspaces first) - When you just need basic workspace information (slug, name) - When you're only interested in repositories (use list-repositories directly) RETURNS: Detailed workspace information including slug, name, type, description, projects, and permission levels. EXAMPLES: - Get workspace: {workspace: "myteam"} ERRORS: - Workspace not found: Verify the workspace slug is correct - Permission errors: Ensure you have access to the requested workspace - Rate limiting: Cache workspace information when possible

list-repositories

List Bitbucket repositories within a specific workspace. PURPOSE: Discovers repositories in a workspace with their slugs, names, and URLs to help navigate code resources. WHEN TO USE: - When you need to find repositories within a specific workspace - When you need repository slugs for other Bitbucket operations - When you want to explore available repositories before accessing specific content - When you need to check repository visibility and access levels - When looking for repositories with specific characteristics (language, size, etc.) WHEN NOT TO USE: - When you don't know which workspace to look for repos in (use list-workspaces first) - When you already know the repository slug (use get-repository instead) - When you need detailed repository information (use get-repository instead) - When you need to access pull requests or branches (use dedicated tools after identifying the repo) RETURNS: Formatted list of repositories with slugs, names, descriptions, URLs, and metadata, plus pagination info. EXAMPLES: - List all repos in workspace: {workspace: "myteam"} - With sorting: {workspace: "myteam", sort: "name"} - With filtering: {workspace: "myteam", query: "api"} - With pagination: {workspace: "myteam", limit: 10, cursor: "next-page-token"} ERRORS: - Workspace not found: Verify the workspace slug is correct - Authentication failures: Check your Bitbucket credentials - Permission errors: Ensure you have access to the requested workspace - Rate limiting: Use pagination and reduce query frequency

get-repository

Get detailed information about a specific Bitbucket repository. PURPOSE: Retrieves comprehensive repository metadata including branches, settings, permissions, and more. WHEN TO USE: - When you need detailed information about a specific repository - When you need repository URLs, clone links, or other reference information - When you need to check repository settings or permissions - After using list-repositories to identify the relevant repository - Before performing operations that require repository context (PRs, branches) WHEN NOT TO USE: - When you don't know which repository to look for (use list-repositories first) - When you just need basic repository information - When you're looking for pull request details (use list-pullrequests instead) - When you need content from multiple repositories (use list-repositories instead) RETURNS: Detailed repository information including slug, name, description, URLs, branch information, and settings. EXAMPLES: - Get repository: {workspace: "myteam", repoSlug: "project-api"} ERRORS: - Repository not found: Verify workspace and repository slugs - Permission errors: Ensure you have access to the requested repository - Rate limiting: Cache repository information when possible

list-pull-requests

List Bitbucket pull requests with optional filtering capabilities. PURPOSE: Allows you to find and browse pull requests across repositories with filtering options. WHEN TO USE: - When you need to find pull requests within a specific repository - When you want to check PR status (open, merged, declined, etc.) - When you need to track code review activity and progress - When you need PR IDs for other Bitbucket operations - When monitoring contributions from specific authors WHEN NOT TO USE: - When you don't know which repository to look in (use list-repositories first) - When you already know the PR ID (use get-pull-request instead) - When you need detailed PR content or comments (use get-pull-request instead) - When you need to browse repositories rather than PRs (use list-repositories) RETURNS: Formatted list of pull requests with IDs, titles, states, authors, branch information, and URLs, plus pagination info. EXAMPLES: - List all PRs in a repo: {workspace: "myteam", repoSlug: "project-api"} - Filter by state: {workspace: "myteam", repoSlug: "project-api", state: "OPEN"} - With pagination: {workspace: "myteam", repoSlug: "project-api", limit: 10, cursor: "next-page-token"} ERRORS: - Repository not found: Verify workspace and repository slugs - Authentication failures: Check your Bitbucket credentials - Permission errors: Ensure you have access to the requested repository - Rate limiting: Use pagination and reduce query frequency

get-pull-request

Get detailed information about a specific Bitbucket pull request. PURPOSE: Retrieves comprehensive PR data including description, comments, diff stats, reviewers, and branch information. WHEN TO USE: - When you need the full description and context of a specific PR - When you need to see comments, reviews, or approvals - When you need details about the source and destination branches - When you need diff statistics or changed files information - After using list-pull-requests to identify the relevant PR ID WHEN NOT TO USE: - When you don't know which PR to look for (use list-pull-requests first) - When you need to browse multiple PRs (use list-pull-requests instead) - When you only need basic PR information without comments or details - When you need repository information rather than PR details (use get-repository) RETURNS: Detailed PR information including title, description, status, author, reviewers, branches, comments, and related timestamps. EXAMPLES: - Get PR details: {workspace: "myteam", repoSlug: "project-api", id: 42} ERRORS: - PR not found: Verify workspace, repository slugs, and PR ID - Permission errors: Ensure you have access to the requested PR - Rate limiting: Cache PR information when possible for frequently referenced PRs

README

Atlassian Bitbucket MCP 服务器

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

概述

什么是 MCP？

模型上下文协议 (MCP) 是一种开放标准，允许 AI 系统安全且有上下文地连接到外部工具和数据源。

此服务器专门为 Bitbucket Cloud 实施 MCP，将您的 Bitbucket 数据与 AI 助手连接起来。

为什么使用此服务器？

最小输入，最大输出理念：只需要像 workspaceSlug 和 repoSlug 这样的简单标识符。每个工具都会返回全面的详细信息，而无需额外的标志。
丰富的代码可视化：通过文件统计信息、差异视图和围绕代码修改的智能上下文，深入了解存储库和代码更改。
安全的本地身份验证：凭据永远不会存储在服务器中。服务器在本地运行，因此您的令牌永远不会离开您的机器，并且您可以仅请求所需的权限。
直观的 Markdown 响应：所有响应都使用结构良好的 Markdown，以便于阅读，并具有一致的格式和导航链接。
完整的 Bitbucket 集成：通过统一的界面访问工作区、存储库、拉取请求、评论、代码搜索等。

入门

前提条件

Node.js (>=18.x): 下载
Bitbucket Cloud 帐户

步骤 1：身份验证

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

选项 A：Bitbucket 应用密码（推荐）

从 Bitbucket 应用密码生成一个。最低权限：

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

选项 B：Atlassian API 令牌

从 Atlassian API 令牌生成一个。

步骤 2：配置凭据

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

创建或编辑 ~/.mcp/configs.json：

使用 Bitbucket 应用密码：

{
	"@aashari/mcp-server-atlassian-bitbucket": {
		"environments": {
			"ATLASSIAN_BITBUCKET_USERNAME": "<your_username>",
			"ATLASSIAN_BITBUCKET_APP_PASSWORD": "<your_app_password>"
		}
	}
}

使用 Atlassian API 令牌：

{
	"@aashari/mcp-server-atlassian-bitbucket": {
		"environments": {
			"ATLASSIAN_SITE_NAME": "bitbucket",
			"ATLASSIAN_USER_EMAIL": "<your_email>",
			"ATLASSIAN_API_TOKEN": "<your_api_token>"
		}
	}
}

方法 B：环境变量

在运行服务器时直接传递凭据：

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

步骤 3：连接您的 AI 助手

配置您的 MCP 兼容客户端以启动此服务器。

Claude / Cursor 配置：

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

此配置在运行时自动启动服务器。

工具

本节介绍将此服务器与 AI 助手一起使用时可用的 MCP 工具。请注意，MCP 工具对工具名称使用 snake_case，对参数使用 camelCase。

`list_workspaces`

列出可用的 Bitbucket 工作区。

{}

或者：

{ "query": "devteam" }

"Show me all my Bitbucket workspaces." (显示我所有的 Bitbucket 工作区。)

`get_workspace`

获取特定工作区的完整详细信息。

{ "workspaceSlug": "acme-corp" }

"Tell me more about the 'acme-corp' workspace." (告诉我更多关于 'acme-corp' 工作区的信息。)

`list_repositories`

列出工作区中的存储库。

{ "workspaceSlug": "acme-corp" }

或者：

{ "workspaceSlug": "acme-corp", "query": "api" }

"List repositories in 'acme-corp'." (列出 'acme-corp' 中的存储库。)

`get_repository`

获取特定存储库的详细信息。

{ "workspaceSlug": "acme-corp", "repoSlug": "backend-api" }

"Show me the 'backend-api' repository in 'acme-corp'." (显示我 'acme-corp' 中的 'backend-api' 存储库。)

`search`

搜索 Bitbucket 内容。

存储库：

{ "workspaceSlug": "acme-corp", "query": "api", "scope": "repositories" }

拉取请求：

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api",
	"query": "fix",
	"scope": "pullrequests"
}

提交：

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "backend-api",
	"query": "update",
	"scope": "commits"
}

代码：

{ "workspaceSlug": "acme-corp", "query": "function getUser", "scope": "code" }

"Search for 'function getUser' in the 'acme-corp' workspace." (在 'acme-corp' 工作区中搜索 'function getUser'。)

`list_pull_requests`

列出存储库中的拉取请求。

{ "workspaceSlug": "acme-corp", "repoSlug": "frontend-app", "state": "OPEN" }

"Show open PRs in 'frontend-app'." (显示 'frontend-app' 中打开的 PR。)

`get_pull_request`

获取拉取请求的完整详细信息，包括代码差异和文件更改。

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

"Get PR #42 from 'frontend-app' with all code changes." (从 'frontend-app' 获取 PR #42，包含所有代码更改。)

`list_pr_comments`

列出特定拉取请求上的评论。

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

"Show me all comments on PR #42." (显示 PR #42 上的所有评论。)

`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 }
}

"Add a comment to PR #42 on line 42." (在 PR #42 的第 42 行添加评论。)

`pull_requests_create`

创建一个新的拉取请求。

{
	"workspaceSlug": "acme-corp",
	"repoSlug": "frontend-app",
	"title": "Add login screen",
	"sourceBranch": "feature/login"
}

"Create a PR from 'feature/login' to 'main'." (创建一个从 'feature/login' 到 'main' 的 PR。)

命令行界面 (CLI)

CLI 对命令（例如，list-workspaces）和选项（例如，--workspace-slug）使用 kebab-case。

使用 `npx` 快速使用

npx -y @aashari/mcp-server-atlassian-bitbucket list-workspaces
npx -y @aashari/mcp-server-atlassian-bitbucket get-repository \
  --workspace-slug acme-corp \
  --repo-slug backend-api

全局安装

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

然后直接运行：

mcp-atlassian-bitbucket list-workspaces

发现更多 CLI 选项

使用 --help 查看所有可用命令的标志和用法：

mcp-atlassian-bitbucket --help

或者获取特定命令的详细帮助：

mcp-atlassian-bitbucket get-repository --help
mcp-atlassian-bitbucket list-pull-requests --help
mcp-atlassian-bitbucket search --help

许可证

ISC 许可证