atlassian-dc-mcp-jira

Atlassian Data Center MCP

社区项目——与 Atlassian 无关联、未经其认可或支持。使用风险自负。

Model Context Protocol (MCP) 服务，可将 Claude Desktop、Claude Code、Cursor 及任何其他兼容 MCP 的 AI 助手连接到自托管的 Atlassian Data Center（以前称为 Server）实例：Jira、Confluence 和 Bitbucket。

通过 AI 助手搜索和管理 Jira 问题、阅读和编辑 Confluence 页面、审查 Bitbucket 拉取请求，同时将凭据存储在操作系统密钥链中，而非粘贴到客户端配置里。

软件包	版本	服务对象
jira-datacenter-mcp		Jira Data Center / Server
confluence-datacenter-mcp		Confluence Data Center / Server
bitbucket-datacenter-mcp		Bitbucket Data Center / Server
datacenter-mcp-core		共享运行时（自动安装，无需直接运行）

每种产品都是独立的软件包——只需安装所需的软件包。

---

目录

• 功能
• 快速开始
• 连接客户端 — Claude Desktop · Claude Code · Cursor 和其他客户端
• 身份验证与令牌
• 配置参考
• 特性
• 开发
• 许可证

---

功能

每个服务都会公开 MCP 工具（助手可以调用的操作）、资源（可读取的上下文端点）和 提示词（现成的工作流）。工具按领域分组，并遵循 <product>_verb_noun 命名模式（例如，jira_search_issues、bitbucket_get_pull_request）。

服务	工具	资源	提示词
Jira	288	4	4
Confluence	115	4	4
Bitbucket	120	4	4

Jira — 288 个工具

分组	工具	涵盖内容
issues	71	搜索（JQL）、创建/更新/转换、评论、工时记录、链接、附件、关注者、投票
projects	48	项目、版本、组件、角色、类别
users	29	用户查找/搜索、群组、可分配用户查询
workflows	25	工作流、状态、方案
agile	22	看板、冲刺、待办事项、史诗
admin	93	字段、屏幕、权限、通知/安全方案及其他管理类读写操作

Confluence — 115 个工具

分组	工具	涵盖内容
content	32	页面/博客文章的增删改查、正文、版本、标签、子项/后代项、搜索（CQL）
spaces	30	空间、空间内容、权限、关注者
users	22	用户、群组、成员关系
admin	11	全局权限、访问模式及其他管理类读取操作
webhooks	9	Webhook 注册和管理
attachments	11	上传、列出、更新附件；下载二进制内容、页面附件和嵌入式图片

Bitbucket — 120 个工具

分组	工具	涵盖内容
repositories	55	仓库、分支、提交、文件/浏览（文本和二进制）、差异、标签、标记、设置
pullRequests	30	PR 增删改查、差异/变更、行内及文件评论、任务、审查、合并/拒绝、参与者
builds	13	构建状态和代码洞察报告
permissions	8	项目/仓库权限授权
authentication	6	访问令牌、SSH 和 GPG 密钥
projects	5	项目增删改查
security	3	安全相关读取操作

每个工具都带有 MCP 注释（只读与破坏性操作提示），并为常见标识符（项目键、看板 ID、仓库 slug）提供参数补全，以便兼容的客户端自动补全这些内容。

---

快速开始

每个软件包都提供交互式 setup 命令，会将凭据保存在操作系统提供的最安全位置（macOS 钥匙串，或其他系统中的 0600 文件）。每个产品运行一次即可：

npx jira-datacenter-mcp setup
npx confluence-datacenter-mcp setup
npx bitbucket-datacenter-mcp setup

设置过程会提示输入主机、API 基础路径、默认页面大小和 API 令牌，随后会发起经过身份验证的实时请求，在保存前验证所有信息是否正确——主机或令牌错误会立即被发现。在允许匿名访问的实例上，将令牌留空即可配置匿名（未经身份验证）访问。

完成设置后，服务启动时无需任何环境变量——请参阅连接客户端。

更倾向于显式配置？ 你可以完全跳过 setup，改用环境变量或共享配置文件传递凭据。请参阅配置参考。

脚本化／非交互式设置

设置支持用于 CI 或远程引导的标志（完整列表请运行 --help）：

标志	短选项	描述
--host <value>	-H	主机，例如 jira.example.com
--api-base-path <value>	-b	API 基础路径或完整 URL
--token <value>	-t	API 令牌（PAT）
--username <value>	-u	Basic 身份验证的用户名（可替代 --token）
--password <value>	-p	Basic 身份验证的密码（需与 --username 搭配使用）
--default-page-size <n>	-s	默认页面大小（正整数）
--profile <name>	-P	用于同一产品第二个实例的命名配置
--non-interactive	-n	不显示提示；缺少必填值时以非零状态码退出
--help	-h	显示用法

# Fully scripted
npx jira-datacenter-mcp setup --non-interactive --host jira.example.com --token "$JIRA_TOKEN"

# Re-validate an already-stored token without re-entering it
npx jira-datacenter-mcp setup --non-interactive --host jira.example.com

在 --non-interactive 模式下，缺失的值会从现有配置中解析；首次验证失败时，命令会以状态码 1 退出，可用作 CI 门禁。

---

连接客户端

setup 保存凭据后，env 块可以留空。以下示例为清晰起见，将凭据直接传入；如果已运行 setup，请删除 env 条目。

将 *_HOST 设置为域名（可选带端口），不要包含协议 — 默认使用 https://。若要指向非标准路径或强制使用 http://，请改用包含完整 URL 的 *_API_BASE_PATH（系统会自动附加特定产品的 API 后缀 — 请勿包含该后缀）。

Claude Desktop

配置文件：~/Library/Application Support/Claude/claude_desktop_config.json（macOS） · %APPDATA%\Claude\claude_desktop_config.json（Windows）。只保留需要的服务。

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

运行 setup 后，配置可简化为：

{
  "mcpServers": {
    "atlassian-jira-dc": { "command": "npx", "args": ["-y", "jira-datacenter-mcp"] }
  }
}

Claude Code

# Project scope (writes .mcp.json); add -s user for all projects
claude mcp add atlassian-jira-dc \
  -e JIRA_HOST=jira.example.com \
  -e JIRA_API_TOKEN=your-token \
  -- npx -y jira-datacenter-mcp

将 -e JIRA_HOST=… 替换为 -e JIRA_API_BASE_PATH=https://jira.example.com/rest；如果已运行 setup，也可以直接删除所有 -e 标志。

Cursor 和其他 MCP 客户端

任何 stdio MCP 客户端都可使用。将其指向命令 npx -y <product>-datacenter-mcp，并通过其 env 机制提供凭据（或依赖 setup）。对于远程／多客户端托管，请使用 HTTP 传输。

---

身份验证与令牌

每个请求会按以下三种模式之一进行处理：

• 个人访问令牌（推荐） — 设置 *_API_TOKEN。以 Authorization: Bearer <token> 发送。
• Basic 身份验证 — 设置 *_USERNAME + *_PASSWORD（适用于不支持 PAT 的旧版实例）。如果两者均已配置，则优先使用此方式，而非令牌。
• 匿名 — 两者均不设置。不发送 Authorization 标头；适用于允许未经身份验证读取的实例。

生成个人访问令牌

产品	Web UI 中的路径
Jira	个人资料 → 个人访问令牌 → 创建令牌
Confluence	个人资料／设置 → 个人访问令牌 → 创建令牌
Bitbucket	管理账户 → HTTP 访问令牌 → 创建令牌

为令牌授予所需的最少权限，并立即复制 — 令牌只会显示一次。

---

配置参考

各产品变量

每种产品读取各自的前缀（JIRA_*、CONFLUENCE_*、BITBUCKET_*）：

变量	必需	描述
*_HOST	✅¹	域名（可带端口），不含协议 — 例如 jira.example.com
*_API_BASE_PATH	✅¹	包含协议的完整基础 URL — 可替代 *_HOST
*_API_TOKEN	—	个人访问令牌（Bearer 身份验证）
*_USERNAME / *_PASSWORD	—	Basic 身份验证凭据对（可替代令牌）
*_DEFAULT_PAGE_SIZE	—	分页端点的默认页面大小

¹ 请提供 *_HOST 或 *_API_BASE_PATH 其中之一。系统会自动附加 API 后缀，请勿包含该后缀：Jira /rest（+ /api/2）、Confluence /rest/api、Bitbucket /rest（+ /api/latest）。

全局变量

变量	默认值	描述
ATLASSIAN_DC_MCP_CONFIG_FILE	—	共享 dotenv 文件的绝对路径（见下文）；若设置但文件不存在，则会立即失败
ATLASSIAN_DC_MCP_PROFILE	—	选择已存储凭据的命名配置（多个实例）
ATLASSIAN_DC_MCP_HTTP_PORT	—	使用 HTTP 而非 stdio 提供服务
ATLASSIAN_DC_MCP_LOG_LEVEL	info	debug · info · warn · error
ATLASSIAN_DC_MCP_REQUEST_TIMEOUT_MS	30000	对 Atlassian API 的单次请求超时时间
ATLASSIAN_DC_MCP_MAX_RESPONSE_CHARS	100000	工具结果的字符数上限；0 表示不设上限
ATLASSIAN_DC_MCP_MAX_INLINE_BYTES	1048576 images 262144 other	下载文件以内联方式返回而无需指定 outputPath 的最大大小。设置后，同一值将同时应用于两者；0 表示始终需要 outputPath

优先级

启动时，每个配置项都会按顺序遍历以下来源，并采用第一个非空值：

优先级	来源	提供内容
100	process.env	所有配置项
80	环境文件 — ATLASSIAN_DC_MCP_CONFIG_FILE，或 ./.env	所有配置项
60	主目录文件 — ~/.atlassian-dc-mcp/<product>.env（Windows 上为 %USERPROFILE%\…）	所有配置项
40	macOS 钥匙串 — 服务 atlassian-dc-mcp，账户 <product>-token / <product>-password	令牌、密码

进程环境变量始终优先，因此你可以在单次会话中覆盖已存储的凭据。钥匙串读取仅在启动时缓存一次；工具调用不会通过 shell 执行外部命令。

共享配置文件

若要在一台机器上的多个 MCP 主机之间重复使用同一组凭据，请将 *_HOST / *_API_TOKEN / … 变量放入一个 dotenv 文件，并通过绝对路径的 ATLASSIAN_DC_MCP_CONFIG_FILE 让每个服务指向该文件：

JIRA_HOST=jira.example.com
JIRA_API_TOKEN=your-jira-token

CONFLUENCE_HOST=confluence.example.com
CONFLUENCE_API_TOKEN=your-confluence-token

BITBUCKET_HOST=bitbucket.example.com
BITBUCKET_API_TOKEN=your-bitbucket-token

{
  "mcpServers": {
    "atlassian-jira-dc": {
      "command": "npx",
      "args": ["-y", "jira-datacenter-mcp"],
      "env": { "ATLASSIAN_DC_MCP_CONFIG_FILE": "/Users/you/.config/atlassian-dc-mcp.env" }
    }
  }
}

---

功能

凭据的存储位置

setup 会将机密与非机密信息分开：

• macOS — 令牌/密码存入登录钥匙串（服务 atlassian-dc-mcp）；成功写入后，主目录文件中的副本会被清除，因此不会在安全性较低的位置保留第二份副本。
• Linux — 主目录文件 ~/.atlassian-dc-mcp/<product>.env，权限模式为 0600（仅限你的用户）。
• Windows — %USERPROFILE%\.atlassian-dc-mcp\<product>.env，继承你的用户配置文件 ACL。

非机密字段（主机、基本路径、页面大小）始终保存在主目录文件中。

多个实例（配置）

要运行同一产品的两个实例（例如两个 Jira 站点），请在设置时为每个实例指定一个 --profile，并在启动时通过 ATLASSIAN_DC_MCP_PROFILE 选择：

npx jira-datacenter-mcp setup --profile work     --host jira-work.example.com     --token "$WORK_TOKEN"
npx jira-datacenter-mcp setup --profile personal --host jira-personal.example.com --token "$PERSONAL_TOKEN"

{
  "mcpServers": {
    "jira-work":     { "command": "npx", "args": ["-y", "jira-datacenter-mcp"], "env": { "ATLASSIAN_DC_MCP_PROFILE": "work" } },
    "jira-personal": { "command": "npx", "args": ["-y", "jira-datacenter-mcp"], "env": { "ATLASSIAN_DC_MCP_PROFILE": "personal" } }
  }
}

配置仅会改变所使用的主目录文件（<product>.<profile>.env）和钥匙串账户。

传输方式：stdio 和 HTTP

默认情况下，每个服务都使用 stdio 通信——这是 Claude Desktop 等本地主机所期望的方式。将 ATLASSIAN_DC_MCP_HTTP_PORT 设为正整数，即可改用 Streamable HTTP 传输方式 提供服务（用于远程/多客户端访问）；每个进程只能选择其中一种方式。

ATLASSIAN_DC_MCP_HTTP_PORT=3000 npx jira-datacenter-mcp

除已配置的 Atlassian 凭据外，HTTP 传输本身不提供身份验证——在将其暴露到 localhost 之外之前，请先配置自己的反向代理、TLS 和访问控制。

弹性

• 重试 — 对瞬时故障（HTTP 429 和 5xx）进行指数退避并加入抖动重试（最多 3 次）。如果服务器提供了 Retry-After 标头，则遵循该标头（上限为 30s），而不是使用计算出的退避时间。4xx 客户端错误永远不会重试。
• 响应上限 — 超过 ATLASSIAN_DC_MCP_MAX_RESPONSE_CHARS（默认 100k 个字符）的工具结果会被截断并附带标记，避免单次宽泛查询占满上下文窗口。设为 0 可禁用。
• 有界分页 — 小型且自然有限的列表（项目的版本、页面的标签）会自动汇总为一个结果；开放式搜索（JQL/CQL、仓库列表）保持单页，由 Agent 驱动，避免返回无界数量的数据。
• 二进制下载 — 每个下载工具都接受可选的绝对路径 outputPath：指定后，文件会写入磁盘，返回内容仅包含其元数据，因此文件大小不受限制。未指定时，字节会作为独立内容块返回（图像或 base64 资源 blob），不受响应上限限制；超过 ATLASSIAN_DC_MCP_MAX_INLINE_BYTES 的内容会被拒绝，并提示使用 outputPath，而非截断。光栅图像的上限为 1 MiB，宿主会将其解码为图片；其他所有内容的上限为 256 KiB，宿主只能将其 base64 内容作为文本读取。

日志记录

所有日志都以每行一个 JSON 对象的形式写入 stderr（{"timestamp","level","message",…}），确保 stdout 保持干净，以供 stdio 协议使用。使用 ATLASSIAN_DC_MCP_LOG_LEVEL 控制日志详细程度：

ATLASSIAN_DC_MCP_LOG_LEVEL=debug npx jira-datacenter-mcp

---

开发

这是一个 pnpm 工作区单体仓库。packages/ 下有四个包：core（共享运行时）以及每个产品各一个包。

前置条件： Node.js ≥ 26 · pnpm（通过 packageManager 固定为 11.9.0）· 可访问的 Atlassian DC/Server 实例。

git clone https://github.com/MrRefactoring/atlassian-dc-mcp.git
cd atlassian-dc-mcp
pnpm install

pnpm build          # build all packages (core first — others depend on its types)
pnpm typecheck      # tsc --noEmit across src + tests
pnpm lint           # ESLint (flat config, whole repo)
pnpm test           # unit tests (Vitest); the API client is mocked — no network

pnpm dev:jira       # watch-mode build for one product (also :confluence, :bitbucket)

使用 --filter 构建或测试单个包：

pnpm --filter jira-datacenter-mcp build
pnpm --filter jira-datacenter-mcp test

实时冒烟测试

单元测试会模拟 API 客户端，因此无法发现针对真实实例的身份验证、网络或 API 结构回归问题。每个产品都可以运行一个选择启用的只读实时测试；未配置时会自行跳过（而非失败）：

cp packages/jira/.env.live.example packages/jira/.env.live
# edit .env.live with a real host + token (or username/password)
pnpm --filter jira-datacenter-mcp test -- jira-service.live

.env.live 已加入 gitignore — 切勿提交真实凭据。

发布

版本管理和发布使用 Changesets；四个包会同步更新（一个 fixed 组）。任何改变行为的 PR 都应包含一个 Changeset：

pnpm changeset

将生成的 .changeset/*.md 与你的更改一同提交。合并生成的“Version Packages” PR 后，才会发布到 npm 和 MCP Registry。

---

许可证

MIT