mcp-jira-dc

Atlassian Data Center MCP

面向在自有服务器上运行 Jira、Confluence 和 Bitbucket 的 AI 优先型企业打造的领先 Atlassian Data Center MCP。

团队选择 Data Center，是为了掌控自己的数据。但不应该因此放弃最优秀的 AI 模型。三个 Model Context Protocol（MCP）服务让 Claude、Cursor 和任何其他 MCP 客户端都能使用可自托管的 Atlassian 工具：搜索和更新问题、读取和编写页面、审查拉取请求，同时避免模型上下文被大量内容塞满。每个服务只需一条 npx 命令。你的 Agent 使用个人访问令牌登录，因此它能做你能做的事，仅此而已。

npx -y mcp-jira-dc setup                    # ← saves your Jira address and token
claude mcp add jira -- npx -y mcp-jira-dc   # ← connects Claude Code

Claude 现在可以使用 14 个 Jira 工具：用于处理问题、评论和状态转换的日常工具，以及一个需要时可访问另外 43 个工具的搜索工具，还有一个能将多次读取合并为一个答案的沙箱。

一个社区项目。与 Atlassian 无关，也未获得 Atlassian 认可。Jira、Confluence 和 Bitbucket 是 Atlassian 的商标。

你会喜欢它的原因

• 一条命令，无需托管任何内容：npx 在你的计算机上运行每个服务。无需 Python、Docker，也无需运行服务器。专为 Data Center 和 Server 版本打造，这些版本不在 Atlassian 自家 MCP 服务的支持范围内。
• 工具列表精简，但能力不受限：每个列出的工具都会在每次请求中消耗令牌，因此列表只展示日常工具，其余工具则通过搜索按需使用。Agent 看到的是 14 个 Jira 工具，而不是 61 个，但仍可使用全部工具。
• 直接给出答案，而不是数页 JSON：对于需要多次调用的问题，Agent 会编写一个短脚本，在沙箱中执行调用并仅返回答案。下面的一个示例返回 226 个字符，而不是 1,215 个。
• 只提供你有权限使用的工具：Jira 服务启动时会读取你的权限，并隐藏你的账号无法使用的工具。
• 写入操作清晰可见：每个工具都会告知客户端自己是读取、更改还是删除，因此客户端可以先征求你的同意。脚本只能读取数据；删除操作始终需要你开启相关设置。
• 需要时提供审计记录：开启审计日志后，会记录 Agent 调用的每个工具，包括通过搜索或脚本调用的工具，但不会记录读取或写入的内容。
• 需要时严格限制访问：提供只读模式、精确的工具允许列表、仅允许在指定的仓库和目标分支上合并，以及仅允许在指定文件夹中使用附件。
• 妥善保管凭据：setup 会先用令牌验证服务器，然后将其存储在操作系统的钥匙串中（macOS Keychain、Windows Credential Manager 或 Linux 桌面密钥环），或者存储在仅当前用户可读取的文件中。服务写入的所有内容都会对令牌进行遮蔽。

为什么要在自己的机器上运行？

Data Center 通常位于防火墙或 VPN 后面。在你工作所在位置运行的服务端，可以像浏览器一样访问它。

	托管式 MCP 连接器	这些服务端
能否访问防火墙或 VPN 后面的实例	仅当实例向该服务开放时	可以：只要你的机器能够访问
令牌存放位置	服务中	你的机器上：操作系统密钥链，或仅你的用户可读取的文件
由谁决定 Agent 能看到哪些工具	服务	你，通过少量设置决定
需要托管、审批或付费的内容	服务	都不需要：由 npx 运行

Atlassian 的官方 MCP 服务是面向 Atlassian Cloud 的托管服务。这些服务端面向 Data Center 和 Server。

三种服务端

服务端	npm 包	Agent 可以做什么
Jira	mcp-jira-dc	使用 JQL 搜索，创建、更新和转换问题，管理评论、链接、版本、冲刺、工作日志、服务台队列、字段和用户。提供 18 个工具集中的 63 个工具；安装 Xray 后还可使用测试管理功能。
Confluence	mcp-confluence-dc	使用 CQL 搜索，读取、创建和更新页面，管理页面树、版本历史和差异、标签、评论、限制和附件。提供 11 个工具集中的 26 个工具。
Bitbucket	mcp-bitbucket-dc	浏览项目、仓库、文件、分支和提交，搜索代码，并审查和评论拉取请求。合并和拒绝操作需选择启用。提供 27 个工具，另有 2 个需选择启用的工具。

只安装你会用到的服务端。它们共用一种配置格式，因此一个设置文件就能供三者使用。

支持的 Jira 应用

Jira 服务端还提供适用于以下 Marketplace 应用的工具：

应用	版本	状态
Xray，测试管理	8	Beta
Jira Service Management	未记录	Beta

Beta 表示已构建并检查，但尚未在该应用的实际运行实例上测试。支持的应用列出了各应用工具构建所依据的具体版本，以及检查方式。

安装

npx -y mcp-jira-dc setup

需要 Node.js 22.22.2 或更高版本、Data Center 或 Server 实例，以及个人访问令牌。将其他服务端替换为 mcp-confluence-dc 或 mcp-bitbucket-dc。

快速入门

1. 保存地址和令牌

setup 会询问你的主机地址和令牌，发送一次经过身份验证的请求以验证它们，然后保存：

npx -y mcp-jira-dc setup

要在 Jira 或 Confluence 中创建令牌，请打开个人资料图片，然后选择 Personal Access Tokens > Create token。 在 Bitbucket 中，选择 Manage account > HTTP access tokens。在脚本和 CI 中，setup --non-interactive 可通过标志接收所有参数；如果令牌无效，则以非零状态码退出。

2. 连接你的 Agent

install 会为你将服务端注册到 Claude Code 或 Claude Desktop：

npx -y mcp-jira-dc install --claude-code      # runs claude mcp add
npx -y mcp-jira-dc install --claude-desktop   # edits Claude Desktop's config, after backing it up

Cursor、VS Code 以及其他使用 mcpServers 文件的客户端：

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

然后可以提问，例如 “我们当前冲刺中有哪些问题被阻塞了？分别由谁负责？”

3. 选择列出的工具

所有设置均为可选。未设置时，Jira 和 Confluence 会列出日常使用的工具，其余工具可通过搜索获取。

设置	作用
TOOLSETS	直接列出整个工具集，例如，对于主要使用冲刺的团队，可以设置为 default,jira_agile。all 会列出所有工具。
READ_ONLY_MODE=true	仅提供不会更改任何内容的工具。
ENABLED_TOOLS	精确的工具名称允许列表，适用于严格受限的配置。
TOOL_GATEWAY=off	关闭搜索：所选工具集之外的工具不会列出。
CODE_EXECUTION=off	移除代码沙箱。
PERMISSION_FILTER=off	列出 Jira 工具时不先检查你的权限。
ATLASSIAN_DC_MCP_AUDIT=1	保留审计日志：每次工具调用记录一行，包含工具、结果和耗时，但绝不记录参数或结果。通过搜索或代码运行的工具也会记录。

每个服务的 README 都列出了其工具集，以及用于启用风险较高工具的设置： Jira、Confluence、 Bitbucket。

4. 检查配置

doctor 会逐步检查每个环节，并说明如何修复问题。它会像 MCP 客户端那样启动服务， 因此会准确显示 Agent 将获得的内容：

$ npx -y mcp-jira-dc doctor
mcp-jira-dc doctor

✓ Node.js   22.22.2
✓ Settings  everything needed is set
            JIRA_HOST: jira.example.com, from C:\Users\alice\.atlassian-dc-mcp\jira.env
            JIRA_API_BASE_PATH: (not set)
            JIRA_API_TOKEN: ••••HcU1, from Windows Credential Manager
            JIRA_DEFAULT_PAGE_SIZE: 25 (default)
✓ Keychain  token kept in Windows Credential Manager
✓ Sign-in   signed in as Alice Smith (alice)
✓ Tools     11 listed, about 2,900 tokens of context
            32 more through jira_searchTools
            jira_runCode is on
            server: Permission filter hid 14 Jira tools: jira_transitionIssue, jira_linkIssues, ...

令牌会被屏蔽，因此可以放心将输出粘贴到错误报告中。

Agent 看到的内容

以下是 Jira 服务针对测试 Jira 运行时返回的真实响应。工具列表包含日常使用的工具和另外四个工具：

jira_searchIssues, jira_getIssue, jira_getIssueComments, jira_createIssue, jira_updateIssue,
jira_postIssueComment, jira_updateIssueComment, jira_getTransitions, jira_transitionIssue,
jira_downloadAttachment, jira_searchTools, jira_runReadTool, jira_runWriteTool, jira_runCode

当被问及冲刺相关问题时，Agent 会搜索工具。jira_searchTools 会返回匹配项及其输入架构 （此处省略），并说明每个工具是读取还是写入：

[
  { "name": "jira_getSprintIssues", "toolset": "jira_agile", "access": "read",
    "description": "List the issues in a sprint in the JIRA Data Center edition instance, in rank order, optionally narrowed by JQL. Returns key, summary, status, type, priority and assignee per issue." },
  { "name": "jira_addIssuesToSprint", "toolset": "jira_agile", "access": "write",
    "description": "Move issues into a future or active sprint in the JIRA Data Center edition instance, taking them out of any other sprint. At most 50 issues per call." },
  { "name": "jira_moveIssuesToBacklog", "toolset": "jira_agile", "access": "write",
    "description": "Move issues to the backlog in the JIRA Data Center edition instance, removing them from their future or active sprint. At most 50 issues per call." }
]

它可以使用 jira_runReadTool 运行读取工具；或者，为了一步回答问题，也可以编写脚本交给 jira_runCode 执行：

const { issues } = await tools.jira_getSprintIssues({ sprintId: 42 });
const blocked = issues.filter((issue) => issue.status === 'Blocked');
console.log(`${blocked.length} of ${issues.length} issues are blocked`);
return blocked.map((issue) => `${issue.key} ${issue.summary} (${issue.assignee?.displayName ?? 'unassigned'})`);

{
  "result": [
    "PAY-102 Migrate payouts to new ledger (Ben Okafor)",
    "PAY-104 Upgrade payment SDK (Amira Haddad)",
    "PAY-106 Refund API returns 500 on partial refunds (Ben Okafor)"
  ],
  "logs": ["3 of 7 issues are blocked"],
  "toolCalls": 1
}

这个答案有 226 个字符。它所依据的完整冲刺列表有 1,215 个字符；在真实冲刺中，每个问题都会让两者之间的差距进一步扩大。

工作原理

每个服务都作为 MCP 客户端的子进程在你的计算机上运行，并使用你的令牌调用 Atlassian 实例的 REST API：

sequenceDiagram
    autonumber
    participant Agent as 🤖 Claude / Cursor / any MCP client
    participant Server as mcp-jira-dc<br/>(on your machine)
    participant Sandbox as Code sandbox<br/>(QuickJS, own thread)
    participant Jira as 🏢 Jira Data Center

    Agent->>Server: tools/list
    Server-->>Agent: everyday tools, search, run tools, runCode

    Agent->>Server: jira_searchTools "sprint issues"
    Server-->>Agent: matching tools with their schemas

    Agent->>Server: jira_runCode (a short script)
    Server->>Sandbox: run the script
    Sandbox->>Server: tools.jira_getSprintIssues(...)
    Server->>Jira: GET /rest/agile/1.0/sprint/42/issue
    Jira-->>Server: the sprint's issues
    Server-->>Sandbox: issue data
    Sandbox-->>Server: the script's return value
    Server-->>Agent: the answer, and console output

脚本在 QuickJS 中运行。这是一个编译为 WebAssembly 的 JavaScript 引擎，运行在独立的工作线程中。它无法访问网络、文件或你的进程，只能调用读取工具。运行 30 秒或 50 次工具调用后，脚本会停止；即使它导致引擎崩溃，也只会影响本次运行。

与列出所有工具相比

对比使用 TOOLSETS=all 的同一个 Jira 服务与默认配置：

	默认配置	列出所有工具
每个请求中的工具	14 个（架构约 13,900 个字符）	61 个（约 56,000 个字符）
使用不太常见的工具	搜索一次，然后调用	直接调用
需要多次调用的问题	编写一个脚本，只返回答案	每个步骤调用一次，每个结果都在上下文中
写入	一次一个，每次都对客户端可见	一次一个，每次都对客户端可见
删除	仅限你启用的工具集	与其他工具一并列出

它能保证什么

• 绝不会扩大访问权限。 每个请求都会携带你的令牌，因此 Jira、Confluence 和 Bitbucket 会决定你能做什么。隐藏工具只会减少 Agent 可见的内容，不会解锁任何功能。
• 脚本只会读取。 沙箱中的代码只能调用读取工具，不能做其他操作。任何更改都必须通过工具调用进行，客户端可以看到并征求你的意见。
• 是否删除始终由你决定。 工具搜索绝不会提供删除工具，沙箱也无法访问此类工具。删除工具只会出现在你启用的工具集中，有些还需要单独设置，例如 JIRA_VERSION_DELETE_ENABLED。
• 绝不会自行重试调用。 如果请求失败，Agent 会看到错误并决定如何处理。
• 绝不会无限期等待。 对你实例的每个请求默认会在 30 秒后超时（ATLASSIAN_DC_MCP_REQUEST_TIMEOUT_MS）；每个脚本也会在运行 30 秒或调用 50 个工具后超时。
• 不会访问你的文件。 附件只会从你指定的文件夹中读取，也只会保存到这些文件夹；保存的文件绝不会覆盖现有文件。

你实例中的内容由其他人编写，因此问题文本、评论、页面和附件会作为数据传递给 Agent，而非指令。在必要之处，工具说明会明确这一点。

我们如何确认它能正常工作？

Agent 会以你的账户执行操作，因此工具若执行了说明之外的操作，就会造成严重问题。每次拉取请求都会在 Ubuntu 和 Windows 上运行 1,000 多项自动化测试：

• 每个工具都有记录： 如果工具未列入其服务的目录，服务就无法启动。测试会检查只读模式是否仅提供读取工具、每个会更改数据的 Jira 工具是否注明所需权限（少数任何人都能执行的操作除外，例如自行关注问题），以及搜索是否绝不提供破坏性工具。
• 有意攻击沙箱： 测试会尝试访问 require、process 和网络，并运行忙循环、永不完成的 Promise、无限递归、原生栈溢出和无限内存占用。每项测试都必须安全失败，同时服务继续正常工作。
• 检查发布的包： CI 会按照 npm 接收包的方式打包每个服务并加载该包，因此缺少依赖会导致构建失败，而不是等到你安装时才发现。
• 谨慎管理依赖： 每个版本都精确锁定；新版本发布至少七天后我们才会采用；npm 包通过 CI 使用 npm 可信发布进行发布，不使用长期有效的令牌。
• 扫描安全问题： CodeQL 会在每次拉取请求中检查代码和工作流；依赖项审查会阻止引入已知漏洞依赖项的拉取请求；Dependabot 会使依赖项和操作保持最新；每项操作都固定到某个提交；OpenSSF Scorecard 会根据开源安全实践跟踪项目情况。SECURITY.md 说明了如何报告问题。

文档

指南	内容
Jira 服务	设置、18 个工具集、权限过滤器、附件、删除版本
Confluence 服务	设置、11 个工具集、附件
Bitbucket 服务	设置、工具、允许合并指定仓库
支持的应用	提供工具的 Jira 应用、构建所用的确切版本，以及验证方式
配置参考	每个 setup 标志、凭据的存储位置、读取设置的顺序、完整的客户端配置
参与贡献	构建和测试、工具选择、搜索和沙箱的工作方式、发布
更新日志	每个版本的变更内容

状态与路线图

这是 0.47，新增了在所有平台上将令牌存储在 OS 钥匙串中、doctor、install、审计日志，以及从 Xray 开始支持 Jira 应用。变更日志列出了所有变更，以及升级时需要做什么。 在 1.0 之前，次要版本可能包含破坏性变更，变更日志会对此进行说明。接下来计划推出：

• 更多 Jira 应用（插件），通过工具搜索访问，因此在使用前不会产生任何开销。首个应用是用于测试管理的 Xray
• Jira 管理工具

有疑问？想要提供帮助？

欢迎通过问题提出疑问、想法和 Bug 报告。若要贡献代码或文档，请先阅读贡献指南；所有参与者都必须遵守行为准则。请通过私密渠道报告安全问题，不要在公开问题中报告。

使用自己的实例运行受支持 Jira 应用的工具，是最有价值的贡献之一：这能让应用从 Beta 阶段进入 Tested 阶段。Jira 应用支持问题表单会询问我们所需的信息。

感谢所有贡献者，也感谢本项目所依赖的开源项目。

packages/jira/          mcp-jira-dc
packages/confluence/    mcp-confluence-dc
packages/bitbucket/     mcp-bitbucket-dc
packages/common/        shared code (configuration, setup, tool selection, the tool search, the code sandbox),
                        bundled into each server and never published on its own
scripts/                bundling, versioning and release scripts
docs/                   guides

运行测试：

npm install
npm run build
npm test

致谢与许可证

MIT 许可证。

部分代码来自两个采用 MIT 许可证的项目：b1ff/atlassian-dc-mcp 和 sooperset/mcp-atlassian。相关声明见 LICENSE。 感谢这两个项目。本项目基于官方的 MCP TypeScript SDK 和 quickjs-emscripten 构建，由 Tekthar 维护。

姊妹项目： abp-mcp，让你的 ABP 应用可供 AI Agent 使用，并沿用你已有的权限；以及 CASL .NET，适用于 .NET、可朗读的权限。