atlassian-dc-mcp-bitbucket

Atlassian Data Center MCP

注意： 这是一个由社区维护的项目，与 Atlassian 没有关联，未获 Atlassian 认可，也不受其支持。 使用风险由您自行承担。

本项目为 Atlassian Data Center 产品提供 Model Context Protocol（MCP）集成，包括 Jira、Confluence 和 Bitbucket。

快速设置

每个程序包都提供交互式 setup 子命令，可将凭据存储在操作系统上最安全的位置。每种产品运行一次即可：

npx @atlassian-dc-mcp/jira setup
npx @atlassian-dc-mcp/confluence setup
npx @atlassian-dc-mcp/bitbucket setup

设置 CLI 会提示您输入主机、API 基础路径、默认页面大小和 API 令牌。保存前，它会检查明显的输入错误，并向所选 Atlassian 产品发送带超时的身份验证请求，以便在设置过程中发现错误的主机、基础路径或令牌。

CLI 标志和非交互模式

设置支持使用标志预填值或完全跳过提示（适用于脚本化引导、CI 或远程会话）。运行 npx @atlassian-dc-mcp/<product> setup --help 查看完整列表。

标志	简写	说明
--host <value>	-H	主机，例如 jira.example.com
--api-base-path <value>	-b	API 基础路径或完整 URL
--token <value>	-t	API 令牌
--default-page-size <n>	-s	默认页面大小（正整数）
--non-interactive	-n	跳过提示；如果无法解析必需值则失败
--help	-h	显示用法并退出

在交互模式下，传入的任何标志都会预填对应提示（例如，--host 会跳过主机提示，但仍会询问其余信息）。在 --non-interactive 模式下，设置会从现有配置（进程环境变量、~/.atlassian-dc-mcp/<product>.env 或 macOS Keychain）解析所有缺失值；如果找不到主机（或完整 URL --api-base-path）和令牌，则以非零状态退出。省略 --token 时会重用现有令牌。

# Scripted, no prompts, write everything from flags
npx @atlassian-dc-mcp/jira setup --non-interactive \
  --host jira.example.com \
  --token "$JIRA_TOKEN"

# Re-validate the existing token without re-entering it
npx @atlassian-dc-mcp/jira setup --non-interactive --host jira.example.com

凭据验证在两种模式下的行为有所不同：交互模式下验证失败时会提供重试或仍然保存的选项；而 --non-interactive 模式会在首次验证失败时以代码 1 退出，因此可用作 CI 检查门禁。

令牌存储位置：

• macOS — 通过 /usr/bin/security 写入登录 Keychain（服务 atlassian-dc-mcp，账户 <product>-token）。
• Linux — 写入 ~/.atlassian-dc-mcp/<product>.env，POSIX 权限模式为 0600（仅您的用户可读写；其他本地用户账户无法读取）。
• Windows — 写入 %USERPROFILE%\.atlassian-dc-mcp\<product>.env。Node 会传递权限位，但 Windows 会忽略它们，因此该文件会继承用户配置文件目录的 ACL——通常只有您的用户、SYSTEM 和 Administrators 可读取。

非机密字段（主机、API 基础路径、默认页面大小）始终写入主目录文件——macOS/Linux 上为 ~/.atlassian-dc-mcp/<product>.env，Windows 上为 %USERPROFILE%\.atlassian-dc-mcp\<product>.env。成功写入 Keychain 后，主目录文件中的令牌行会被清除，因此不会在安全性较低的位置留下第二份副本。

运行设置后，MCP 服务无需任何环境变量即可启动：

{
  "mcpServers": {
    "atlassian-jira-dc": { "command": "npx", "args": ["-y", "@atlassian-dc-mcp/jira"] },
    "atlassian-confluence-dc": { "command": "npx", "args": ["-y", "@atlassian-dc-mcp/confluence"] },
    "atlassian-bitbucket-dc": { "command": "npx", "args": ["-y", "@atlassian-dc-mcp/bitbucket"] }
  }
}

您仍可通过环境变量或 ATLASSIAN_DC_MCP_CONFIG_FILE 传递凭据，如下文所示；这些凭据的优先级高于设置保存的值。

配置来源与优先级

启动时，每个 MCP 服务都会按以下顺序遍历各个来源，为每个配置键取第一个非空值：

优先级	来源	读取内容	设置程序写入内容
100	process.env（JIRA_*、CONFLUENCE_*、BITBUCKET_*）	所有键	—
80	环境文件 — ATLASSIAN_DC_MCP_CONFIG_FILE 或 ./.env	所有键	—
60	主目录文件 — macOS/Linux 上的 ~/.atlassian-dc-mcp/<product>.env，Windows 上的 %USERPROFILE%\.atlassian-dc-mcp\<product>.env（POSIX 上模式为 0600；Windows 继承用户配置文件的 ACL）	所有键	host、apiBasePath、defaultPageSize（始终）；token（非 darwin 系统或作为钥匙串回退）
40	macOS 钥匙串 — 服务 atlassian-dc-mcp，账户 <product>-token	仅 token	token（仅 darwin）

说明：

• 进程环境变量的优先级最高，因此你始终可以在单次会话中覆盖已存储的凭据。
• ATLASSIAN_DC_MCP_CONFIG_FILE 必须是绝对路径；如果已设置但文件不存在，服务会立即失败。
• 钥匙串读取结果会在初始化时缓存（每个产品令牌执行一次 execFileSync），因此工具调用不会启动 Shell 命令。
• 如果某个高优先级来源会覆盖设置程序即将保存的值，设置程序会打印警告并指出环境变量名称，以便你取消设置。
• Atlassian API 请求默认在 30 秒后超时。将 ATLASSIAN_DC_MCP_REQUEST_TIMEOUT_MS 设置为正数毫秒值即可覆盖此设置。

Claude Desktop 配置

Anthropic 官方快速入门指南

要在 Claude Desktop 中使用这些 MCP 连接器，请将以下内容添加到 Claude Desktop 配置中。

*_HOST 变量只能设置为不含协议的域名 + 端口（例如 your-instance.atlassian.net）。默认使用 https 协议。

或者，你可以使用 *_API_BASE_PATH 变量代替 *_HOST，以指定包含协议的完整 API 基础 URL（例如 https://your-instance.atlassian.net/rest）。请注意，/api/latest/ 部分是固定的，会在代码中自动添加，因此无需将其包含在 *_API_BASE_PATH 值中。

配置中只需保留你需要的服务。

macOS：

~/Library/Application Support/Claude/claude_desktop_config.json

Windows：

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "atlassian-jira-dc": {
      "command": "npx",
      "args": ["-y", "@atlassian-dc-mcp/jira"],
      "env": {
        "JIRA_HOST": "your-jira-host",
        "JIRA_API_TOKEN": "your-token"
      }
    },
    "atlassian-confluence-dc": {
      "command": "npx",
      "args": ["-y", "@atlassian-dc-mcp/confluence"],
      "env": {
        "CONFLUENCE_HOST": "your-confluence-host",
        "CONFLUENCE_API_TOKEN": "your-token"
      }
    },
    "atlassian-bitbucket-dc": {
      "command": "npx",
      "args": ["-y", "@atlassian-dc-mcp/bitbucket"],
      "env": {
        "BITBUCKET_HOST": "your-bitbucket-host",
        "BITBUCKET_API_TOKEN": "your-token"
      }
    }
  }
}

你也可以使用备用 API 基础路径配置：

{
  "mcpServers": {
    "atlassian-jira-dc": {
      "command": "npx",
      "args": ["-y", "@atlassian-dc-mcp/jira"],
      "env": {
        "JIRA_API_BASE_PATH": "https://your-jira-host/rest",
        "JIRA_API_TOKEN": "your-token"
      }
    },
    "atlassian-confluence-dc": {
      "command": "npx",
      "args": ["-y", "@atlassian-dc-mcp/confluence"],
      "env": {
        "CONFLUENCE_API_BASE_PATH": "https://your-confluence-host/rest",
        "CONFLUENCE_API_TOKEN": "your-token"
      }
    },
    "atlassian-bitbucket-dc": {
      "command": "npx",
      "args": ["-y", "@atlassian-dc-mcp/bitbucket"],
      "env": {
        "BITBUCKET_API_BASE_PATH": "https://your-bitbucket-host/rest",
        "BITBUCKET_API_TOKEN": "your-token"
      }
    }
  }
}

共享外部配置文件

如果你希望同一台计算机上的多个 MCP 主机或工具共用相同的 Atlassian 凭据，请将现有的 JIRA_*、CONFLUENCE_* 和 BITBUCKET_* 变量放入一个 dotenv 格式文件，并通过 ATLASSIAN_DC_MCP_CONFIG_FILE 指定各个 MCP 服务使用该文件。

路径必须是绝对路径。直接设置的环境变量仍会覆盖共享文件中的值。

共享文件示例：

JIRA_HOST=your-jira-host
JIRA_API_TOKEN=your-jira-token
JIRA_DEFAULT_PAGE_SIZE=50

CONFLUENCE_HOST=your-confluence-host
CONFLUENCE_API_TOKEN=your-confluence-token

BITBUCKET_HOST=your-bitbucket-host
BITBUCKET_API_TOKEN=your-bitbucket-token
BITBUCKET_DEFAULT_PAGE_SIZE=50

Claude Desktop 使用单个共享文件的示例：

{
  "mcpServers": {
    "atlassian-jira-dc": {
      "command": "npx",
      "args": ["-y", "@atlassian-dc-mcp/jira"],
      "env": {
        "ATLASSIAN_DC_MCP_CONFIG_FILE": "/Users/your-user/.config/atlassian-dc-mcp.env"
      }
    },
    "atlassian-confluence-dc": {
      "command": "npx",
      "args": ["-y", "@atlassian-dc-mcp/confluence"],
      "env": {
        "ATLASSIAN_DC_MCP_CONFIG_FILE": "/Users/your-user/.config/atlassian-dc-mcp.env"
      }
    },
    "atlassian-bitbucket-dc": {
      "command": "npx",
      "args": ["-y", "@atlassian-dc-mcp/bitbucket"],
      "env": {
        "ATLASSIAN_DC_MCP_CONFIG_FILE": "/Users/your-user/.config/atlassian-dc-mcp.env"
      }
    }
  }
}

Windows 示例路径：

{
  "mcpServers": {
    "atlassian-jira-dc": {
      "command": "npx",
      "args": ["-y", "@atlassian-dc-mcp/jira"],
      "env": {
        "ATLASSIAN_DC_MCP_CONFIG_FILE": "C:\\\\Users\\\\your-user\\\\AppData\\\\Roaming\\\\atlassian-dc-mcp.env"
      }
    }
  }
}

Claude Code CLI 配置

要在 Claude Code 中使用这些 MCP 连接器，请使用 claude mcp add 命令添加 MCP 服务。

你可以在项目范围（存储在 .mcp.json 中）或用户范围（-s user）添加服务。根据需要调整范围和包含的服务。

# Jira
claude mcp add atlassian-jira-dc \
  -e JIRA_HOST=your-jira-host \
  -e JIRA_API_TOKEN=your-token \
  -- npx -y @atlassian-dc-mcp/jira

# Confluence
claude mcp add atlassian-confluence-dc \
  -e CONFLUENCE_HOST=your-confluence-host \
  -e CONFLUENCE_API_TOKEN=your-token \
  -- npx -y @atlassian-dc-mcp/confluence

# Bitbucket
claude mcp add atlassian-bitbucket-dc \
  -e BITBUCKET_HOST=your-bitbucket-host \
  -e BITBUCKET_API_TOKEN=your-token \
  -- npx -y @atlassian-dc-mcp/bitbucket

你也可以使用 *_API_BASE_PATH 代替 *_HOST（与上述 Claude Desktop 示例相同）：

claude mcp add atlassian-jira-dc \
  -e JIRA_API_BASE_PATH=https://your-jira-host/rest \
  -e JIRA_API_TOKEN=your-token \
  -- npx -y @atlassian-dc-mcp/jira

要在用户范围添加服务（适用于所有项目）：

claude mcp add -s user atlassian-jira-dc \
  -e JIRA_HOST=your-jira-host \
  -e JIRA_API_TOKEN=your-token \
  -- npx -y @atlassian-dc-mcp/jira

要使用共享配置文件，而不是内联传递凭据：

claude mcp add atlassian-jira-dc \
  -e ATLASSIAN_DC_MCP_CONFIG_FILE=/Users/your-user/.config/atlassian-dc-mcp.env \
  -- npx -y @atlassian-dc-mcp/jira

Windows PowerShell 示例：

claude mcp add atlassian-jira-dc `
  -e ATLASSIAN_DC_MCP_CONFIG_FILE=C:\Users\your-user\AppData\Roaming\atlassian-dc-mcp.env `
  -- npx -y @atlassian-dc-mcp/jira

生成 API 令牌

对于 Data Center 安装，你需要为每项服务生成个人访问令牌（PAT）：

Jira Data Center

1. 登录你的 Jira 实例
2. 前往 Profile > Personal Access Tokens
3. 点击“Create token”
4. 为令牌设置有意义的名称和适当的权限
5. 立即复制生成的令牌（之后将无法再次查看）

Confluence Data Center

1. 登录你的 Confluence 实例
2. 前往 Settings > Personal Access Tokens
3. 点击“Create token”
4. 为令牌命名并设置所需权限
5. 保存并复制令牌（仅显示一次）

Bitbucket Data Center

1. 登录 Bitbucket
2. 前往 Manage Account > HTTP access tokens
3. 点击“Create token”
4. 设置名称和权限
5. 立即生成并复制令牌

请妥善保管这些令牌，并按照上文所示在 Claude Desktop 配置中使用它们。

概览

Atlassian DC MCP 允许 AI 助手通过标准化接口与 Atlassian 产品交互。它提供以下工具：

• Jira：搜索、查看和创建问题
• Confluence：访问和管理内容
• Bitbucket：与代码仓库和代码交互

前提条件

• Node.js 18 或更高版本
• npm 7 或更高版本（用于支持工作区）
• Atlassian Data Center 实例或云实例
• 你要使用的 Atlassian 产品的 API 令牌

安装

克隆代码仓库：

git clone https://github.com/b1ff/atlassian-dc-mcp.git
cd atlassian-dc-mcp

开发

此项目采用 npm monorepo 结构，并使用工作区。工作区位于 packages/ 目录中，每个 Atlassian 产品集成都有独立的包。

安装依赖项

要为 monorepo 中的所有包安装全部依赖项：

npm install

这将安装：

• 根目录 package.json 中定义的根级依赖项
• 工作区中每个包的所有依赖项

要为特定包安装依赖项：

npm install <package-name> --workspace=@atlassian-dc-mcp/jira

要在根级别安装依赖项：

npm install <package-name> -W

构建项目

要构建所有包：

npm run build

要构建特定包：

npm run build --workspace=@atlassian-dc-mcp/jira

在开发模式下运行

要在开发模式下运行特定包：

npm run dev:jira     # For Jira
npm run dev:confluence  # For Confluence
npm run dev:bitbucket   # For Bitbucket

配置

用于生产环境时，建议使用上文的 快速设置 CLI——它会自动将令牌写入 macOS Keychain，并将非机密字段写入用户主目录下的文件（macOS/Linux 上为 ~/.atlassian-dc-mcp/<product>.env，Windows 上为 %USERPROFILE%\.atlassian-dc-mcp\<product>.env）。

用于本地开发时，请在根目录中创建 .env 文件，或在磁盘上的任意位置创建共享的 dotenv 格式文件，并将 ATLASSIAN_DC_MCP_CONFIG_FILE 指向该文件。文件中包含以下变量：

# Jira configuration - choose one of these options:
JIRA_HOST=your-instance.atlassian.net
# OR
JIRA_API_BASE_PATH=https://your-instance.atlassian.net/rest
# Note: part /api/2/search/ is added automatically, do not include it
JIRA_API_TOKEN=your-api-token

# Confluence configuration - choose one of these options:
CONFLUENCE_HOST=your-instance.atlassian.net
# OR
CONFLUENCE_API_BASE_PATH=https://your-instance.atlassian.net/confluence
# Note: part /rest/api is added automatically, do not include it
CONFLUENCE_API_TOKEN=your-api-token

# Bitbucket configuration - choose one of these options:
BITBUCKET_HOST=your-instance.atlassian.net
# OR
BITBUCKET_API_BASE_PATH=https://your-instance.atlassian.net/rest
# Note: part /api/latest/ is added automatically, do not include it
BITBUCKET_API_TOKEN=your-api-token

每个键的解析顺序为 process.env → ATLASSIAN_DC_MCP_CONFIG_FILE（或 ./.env）→ 用户主目录下的文件（macOS/Linux 上为 ~/.atlassian-dc-mcp/<product>.env，Windows 上为 %USERPROFILE%\.atlassian-dc-mcp\<product>.env）→ macOS Keychain。请参阅上文的配置来源和优先级。

许可证

MIT