Atlassian Read-only MCP

一个为 AI 助手提供 Jira 和 Confluence 只读访问权限的小型 MCP 服务器。只读访问通过两层机制强制实现：

1. Atlassian 令牌仅包含只读作用域。

2. 服务器仅实现允许列表中的 GET 请求。

它提供四个工具：

• 读取 Jira 问题（issue）

• 使用 JQL 搜索 Jira

• 读取 Confluence 页面

• 使用 CQL 搜索 Confluence

没有通用的 HTTP 工具，也没有实现 POST、PUT、PATCH 或 DELETE。即使意外提供了更广的凭据，MCP 客户端仍然没有任何工具可以更改 Jira 或 Confluence 的内容。响应大小受到限制，可能涉密的字段会被脱敏，Confluence 存储 HTML 会转换为 Markdown，并且可选的 JMESPath 投影可以精简返回的数据。

要求

• Node.js 20 或更高版本

• 有权访问已配置的 Atlassian Cloud 租户

• 为 Jira 和 Confluence 分别创建带作用域的 API 令牌

• 一个 MCP 客户端，例如 VS Code 中的 GitHub Copilot

Related MCP server: MCP Atlassian Server

安装

git clone https://github.com/AlexSchaap-TMMC/atlassian-readonly-mcp.git C:\Tools\atlassian-readonly
Set-Location C:\Tools\atlassian-readonly
npm install
npm test

创建 API 令牌

打开 Atlassian API 令牌页面，创建两个令牌。

Jira 令牌

read:jira-work

该经典作用域单独通过验证，可用于问题检索和 JQL 搜索。仅包含等价细粒度作用域的 Jira 令牌曾被 Atlassian 拒绝，返回 401 Unauthorized; scope does not match。

Confluence 令牌

read:page:confluence
read:content-details:confluence
search:confluence

这些细粒度作用域已通过 CQL 搜索和页面全文检索的验证。

令牌创建完成后，作用域便固定不变。Jira 和 Confluence 需要分别使用单独的令牌。请从一次性令牌创建对话框中复制令牌，不要将其放入源文件、MCP 配置、shell 历史、issue 或聊天中。

不要添加写入或管理作用域。受到限制的令牌能确保 Atlassian 独立于 MCP 实现之外直接拒绝写入操作。

存储凭据

在仓库目录下执行：

npm run configure -- jira
npm run configure -- confluence

隐藏的提示会将每个令牌分别保存到 Windows 凭据管理器、macOS Keychain 或 Linux Secret Service 中。Atlassian 账户邮箱应放在 MCP 环境中，而不是凭据存储中。

在 VS Code 中配置 GitHub Copilot

在命令面板中运行 MCP: Open User Configuration：

{
  "servers": {
    "atlassian-readonly": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\Tools\\atlassian-readonly\\src\\server.mjs"],
      "env": {
        "ATLASSIAN_USER_EMAIL": "your.atlassian.email@example.com",
        "NODE_OPTIONS": "--use-system-ca"
      }
    }
  }
}

重新加载 VS Code、打开 Copilot Chat、选择 Configure Tools，然后启用这四个 Atlassian 工具。

示例提示：

Read HEC-123 and summarize its acceptance criteria.
Search Jira for open bugs assigned to me.
Search Confluence for pages about Kafka retry handling.

配置 GitHub Copilot CLI

copilot mcp add atlassian-readonly `
  --env ATLASSIAN_USER_EMAIL="your.atlassian.email@example.com" `
  --env NODE_OPTIONS="--use-system-ca" `
  -- node C:\Tools\atlassian-readonly\src\server.mjs

添加或更改服务器之后，请重启 Copilot CLI。

故障排查

认证

请检查以下各项：

• 邮箱与创建令牌的 Atlassian 账户一致。

• 存入了正确的环境令牌。

• 令牌仍然有效，且账户有权访问所请求的内容。

• Jira 使用 read:jira-work，而不只是细粒度的单个 Jira 作用域。

• Confluence 已包含上文列出的全部三个作用域。

• 替换令牌后重启了 MCP 宿主。

带作用域的令牌必须使用 Atlassian 的产品网关：

https://api.atlassian.com/ex/jira/{cloudId}
https://api.atlassian.com/ex/confluence/{cloudId}

本服务器使用 src/atlassian.mjs 中固定的租户 Cloud ID。

企业证书

TLS 检查产品（如 Zscaler）会使用企业证书颁发机构对 HTTPS 流量重新签名。Windows 可能会信任该颁发机构，但 Node.js 仍在使用自带的 CA 列表。在受支持的 Node.js 版本中，请把以下变量保留在 MCP 环境中：

NODE_OPTIONS=--use-system-ca

如有必要，请将未过期的企业 CA 导出为 Base-PEM 格式，并设置 NODE_EXTRA_CA_CERTS 为其绝对路径。绝不 TLS 验证。

WSL 拥有独立的 Linux 信任库。请将从 Windows 导出的适用企业根证书和中间证书保存为 .crt 扩展名，复制到 /usr/local/share/ca-certificates/，然后运行：

sudo update-ca-certificates

在重新尝试 curl、Docker、Node.js 或其他 HTTPS 客户端之前，请先重启 WSL。

WSL 与 headless 系统

如果没有桌面 keystore，请使用受限的令牌文件：

mkdir -p ~/.config
install -m 600 /dev/null ~/.config/atlassian-jira-token
install -m 600 /dev/null ~/.config/atlassian-confluence-token
read -rsp "Jira API token: " token; echo
printf '%s' "$token" > ~/.config/atlassian-jira-token
read -rsp "Confluence API token: " token; echo
printf '%s' "$token" > ~/.config/atlassian-confluence-token
unset token

在 MCP 环境中配置这些变量：

ATLASSIAN_USER_EMAIL
ATLASSIAN_JIRA_TOKEN_FILE
ATLASSIAN_CONFLUENCE_TOKEN_FILE

ATLASSIAN_JIRA_API_TOKEN 和 ATLASSIAN_CONFLUENCE_API_TOKEN 适用于进程范围的 CI 使用，但不应保存在桌面配置中。

轮换或删除凭据

替换已存储的令牌：

npm run configure -- jira
npm run configure -- confluence

删除已存储的令牌：

npm run configure -- jira delete
npm run configure -- confluence delete

本地删除不会吊销令牌。请另行在 Atlassian 的令牌管理页面吊销令牌。

安全边界

本项目采用纵深防御机制：

令牌强制： 文档中记录的令牌只包含 Atlassian 只读作用域，因此 Atlassian 不会授权写入操作。 实现强制： 只有四个边界窄化的只读工具。它们的 URL 和 HTTP 方法是固定的；调用方无法选择其他主机、端点或方法。 响应控制： 响应大小受限制，疑似敏感的字段会被脱敏，投影能够极端化返回的数据。

令牌仍然继承创建者的可见范围：MCP 只能读取该账户此前可访问的内容。如果提供权限更大，则令牌层被削弱，但不会为 MCP 增加写入操作。

许可证

MIT