mcp-atlassian-extended

mcp-atlassian-extended

安装： uvx mcp-atlassian-extended | PyPI | MCP Registry | 更新日志

uvx mcp-atlassian-extended                          # with writes
MCP_READ_ONLY=true uvx mcp-atlassian-extended       # locked read-only: write tools are not listed

mcp-atlassian-extended 是一个适用于 Jira 和 Confluence 的 Model Context Protocol (MCP) 服务。它为 AI 助手提供 22 个工具、15 个资源和 5 个提示词，用于处理 Jira 和 Confluence 工作。这些工具可以使用自定义字段创建和更新问题、关联问题、管理附件以及搜索用户。它们还可以运行敏捷看板和冲刺、跟踪项目版本（API v2）、读取团队日历并规划冲刺容量。它在 mcp-atlassian 的基础上扩展，工具完全没有重叠。它可在两种模式下运行：启用写入，或锁定为只读模式（MCP_READ_ONLY=true），这样就不会向模型提供 10 个写入工具。

该服务支持 MCP 2026-07-28 规范（通常称为 MCP 2.0），并兼容 2025-11-25 客户端。它适用于 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code Copilot 以及任何兼容 MCP 的客户端。

该服务支持 Jira Cloud、Jira Data Center、Confluence Cloud 和 Confluence Data Center（可自托管）。无需 Atlassian Premium 计划。

基于 FastMCP、httpx 和 Pydantic 构建。

协议支持

• 该服务实现 MCP 2026-07-28 规范，通常称为 MCP 2.0。
• 它兼容 2025-11-25 客户端。
• 传输方式：stdio（默认）和 streamable-http（推荐用于远程客户端）。sse 传输方式仍可使用，但 2026-07-28 规范已将其弃用，因此该服务会打印警告。
• 该服务不使用 roots、sampling、logging、elicitation 或资源订阅。2026-07-28 规范中的弃用事项不会影响它。
• 基于 FastMCP 4.x 和 MCP Python SDK 2.x 构建。

错误结果

预期的失败情况——404、401/403、只读拒绝、参数无效——会作为带有 isError: true 的工具结果返回，因此 MCP 客户端会看到失败，而不是一个碰巧包含“error”一词的结果。结果正文仍是与之前相同的 {"error": …, "hint": …} 对象；如果失败来自 API，还会包含 status_code 和 body；hint 会说明如何修复。此对象是结果的文本内容；不会设置 structuredContent，因为严格的 MCP 客户端会根据工具的输出架构验证 structuredContent，即使 isError 为 true 也是如此，而错误封装对象与之不匹配。真正的 Bug 仍会作为协议级工具错误抛出，并记录带有回溯信息的日志。

成功时，工具会将相同的美化格式 JSON 作为文本内容，并将该 JSON 对象作为 structuredContent——之前 2.0 版本中的 {"result": "<json string>"} 封装已移除（如果有效负载是 JSON 数组，例如多文件上传响应，则只提供文本，因为 structuredContent 必须是对象）。工具不声明 outputSchema：上游字段会以未类型化的形式传递；如果客户端需要类型化架构，可通过 @mcp.tool(...) 上的 output_schema=，为单个工具选择启用。

与 mcp-atlassian 的关系

本项目与 mcp-atlassian 配合使用，而非取代它。请配置两个服务：

• mcp-atlassian 负责：问题、搜索、状态转换、评论、工作日志、页面、Confluence 搜索
• mcp-atlassian-extended 负责：附件、敏捷、用户、字段、版本（API v2）、日历、休假

工具之间没有重叠——本服务只实现 mcp-atlassian 缺少的工具。

一键安装

💡 提示： 对于其他 AI 助手（Claude Code、Windsurf、IntelliJ、Gemini CLI），请访问 Atlassian Extended MCP 安装入口。

# with writes
claude mcp add atlassian-extended \
  -e JIRA_URL=https://your-company.atlassian.net -e [email protected] -e JIRA_API_TOKEN=your_api_token \
  -- uvx mcp-atlassian-extended
# locked read-only: write tools are not listed
claude mcp add atlassian-extended -e MCP_READ_ONLY=true \
  -e JIRA_URL=https://your-company.atlassian.net -e [email protected] -e JIRA_API_TOKEN=your_api_token \
  -- uvx mcp-atlassian-extended

{
  "mcpServers": {
    "atlassian-extended": {
      "command": "uvx",
      "args": ["mcp-atlassian-extended"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your_api_token",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
gemini mcp add -s user -e JIRA_URL=https://your-company.atlassian.net -e [email protected] -e JIRA_API_TOKEN=your_api_token -e CONFLUENCE_URL=https://your-company.atlassian.net/wiki -e [email protected] -e CONFLUENCE_API_TOKEN=your_api_token atlassian-extended uvx mcp-atlassian-extended
# locked read-only
gemini mcp add -s user -e MCP_READ_ONLY=true -e JIRA_URL=https://your-company.atlassian.net -e [email protected] -e JIRA_API_TOKEN=your_api_token -e CONFLUENCE_URL=https://your-company.atlassian.net/wiki -e [email protected] -e CONFLUENCE_API_TOKEN=your_api_token atlassian-extended uvx mcp-atlassian-extended

{
  "servers": {
    "atlassian-extended": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-atlassian-extended"],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token",
        "MCP_READ_ONLY": "true"
      }
    }
  }
}

# with writes
codex mcp add atlassian-extended --env JIRA_URL=https://your-company.atlassian.net --env [email protected] --env JIRA_API_TOKEN=your_api_token -- uvx mcp-atlassian-extended
# locked read-only
codex mcp add atlassian-extended --env MCP_READ_ONLY=true --env JIRA_URL=https://your-company.atlassian.net --env [email protected] --env JIRA_API_TOKEN=your_api_token -- uvx mcp-atlassian-extended

uv pip install mcp-atlassian-extended

配置

Jira Cloud（基本身份验证）

Jira Data Center / 自托管（Bearer Token）

服务会按顺序检查这些环境变量，使用第一个匹配项：

1. JIRA_PAT
2. JIRA_PERSONAL_TOKEN
3. JIRA_TOKEN

Basic 认证优先。如果同时设置了 JIRA_USERNAME 和 JIRA_API_TOKEN，服务会使用 Basic 认证，并忽略任何个人访问令牌。只有在 Cloud 配置不完整时，服务才会使用 Bearer 认证。若要强制使用 Bearer，请取消设置 JIRA_USERNAME 和 JIRA_API_TOKEN。

Confluence Cloud（Basic 认证）

Confluence Data Center / 自托管（Bearer Token）

服务会按顺序检查这些环境变量，使用第一个匹配项：

1. CONFLUENCE_PAT
2. CONFLUENCE_PERSONAL_TOKEN
3. CONFLUENCE_TOKEN

这里 Basic 认证也优先：CONFLUENCE_USERNAME + CONFLUENCE_API_TOKEN 优先于 任何个人访问令牌。

所有 Confluence 日历工具都需要 Team Calendars 插件 （/rest/calendar-services/1.0/）。未安装该插件的实例上，每个日历工具都会返回 404，并提示插件名称。

可选设置

兼容性

工具（22 个）

该服务将精选的 Jira 和 Confluence 工作流指南作为 MCP 资源公开。

提示词（5）

该服务提供 MCP 提示词——可复用的多工具工作流模板，客户端可以将其显示为斜杠命令。

使用示例

问题管理

"Create a story in PROJ with custom story points"
→ jira_create_issue(project_key="PROJ", summary="Add OAuth login", issue_type="Story",
    custom_fields={"customfield_10004": 5})

"Update a ticket's priority and add labels"
→ jira_update_issue(issue_key="PROJ-123", fields={"priority": {"name": "High"}, "labels": ["urgent"]})

"Create an epic and link related stories"
→ jira_create_issue(project_key="PROJ", summary="Q1 Auth Overhaul", issue_type="Epic")
→ jira_create_link(link_type="Relates", inward_issue="PROJ-100", outward_issue="PROJ-200")

附件

"List attachments on PROJ-123"
→ jira_get_attachments(issue_key="PROJ-123")

"Upload a screenshot to a ticket"
→ jira_upload_attachment(issue_key="PROJ-123", file_path="./screenshot.png")

"Download an attachment"
→ jira_download_attachment(content_url="https://jira.example.com/rest/api/2/attachment/content/456",
    save_path="report.pdf")  # lands in ./atlassian-downloads/report.pdf (or ATLASSIAN_DOWNLOAD_DIR)

敏捷与 Sprint 管理

"Get the current sprint for board 42"
→ jira_get_board(board_id=42) → jira_get_sprint(sprint_id=7)

"Move tickets into the next sprint"
→ jira_move_to_sprint(sprint_id=8, issue_keys=["PROJ-1", "PROJ-2", "PROJ-3"])

"View backlog for board 42"
→ jira_backlog(board_id=42, max_results=50)

版本管理

"List versions for project PROJ"
→ jira_get_project_versions(project_key="PROJ")

"Create a new release version"
→ jira_create_version(project_key="PROJ", name="v2.0.0", release_date="2026-04-01")

"Mark version as released"
→ jira_update_version(version_id="200", released=True)

休假与 Sprint 容量

"Who is out today?"
→ confluence_get_time_off(start_date="today", end_date="today", group_by_person=True)

"Get team time-off for the next two weeks"
→ confluence_get_time_off(start_date="today", end_date="+14d", group_by_person=True)

"Calculate sprint capacity accounting for PTO"
→ confluence_sprint_capacity(
    team_members=["Alice", "Bob", "Carol"],
    sprint_start="2025-03-03", sprint_end="2025-03-14")

安全注意事项

• 令牌范围：对于 Jira Cloud，请使用权限范围最小化的 API 令牌。对于 Data Center，请使用项目级访问权限的 PAT。
• 只读模式：在你控制的启动环境中设置 MCP_READ_ONLY=true（或 ATLASSIAN_READ_ONLY=true），服务器启动后便会锁定：10 个写入工具和写入工作流提示词不会列出，调用其中任意一个都会返回“Unknown tool”，而防护机制会拒绝任何仍到达服务器的写入操作。运行时无法解除锁定——其他来源提供的 false、.env 文件或工具参数均不行；任何不是 false/0/no/off/空值的值都会锁定，而 --read-only 只能加强锁定。锁定强度取决于启动环境：请在用户无法编辑的位置设置，例如受管理的 MCP 配置（如 Claude Code managed-mcp.json）、容器、k8s 或 systemd 环境变量，或托管的 HTTP 部署。自行启动服务器的用户可以控制其环境。所有写入工具都是 Jira 工具；两种模式下的 Confluence 工具都为只读。
• HTTP 传输身份验证：HTTP 传输（--transport streamable-http/sse）会向任何能访问端口的人开放所有使用已配置 Atlassian 凭据的工具，因此绑定到非环回地址时必须使用共享 bearer 令牌。设置 ATLASSIAN_HTTP_BEARER_TOKEN（至少 16 个字符；openssl rand -hex 32），客户端发送 Authorization: Bearer <token>；令牌采用恒定时间比较。未设置令牌时，服务器会拒绝在 127.0.0.1/localhost/::1 以外的任何主机上启动。服务器还会验证 HTTP 请求中的 Host/Origin 标头（host_origin_protection="auto"），防止 DNS 重绑定页面操控绑定到环回地址的服务器。
• 上传目录限制：jira_upload_attachment 只会读取上传根目录中的文件——如果设置了 ATLASSIAN_UPLOAD_DIR，则使用其指定目录，否则使用工作目录。路径会在检查是否位于根目录内之前解析（跟随符号链接），因此指向根目录外的符号链接会被拒绝；根目录下的点文件和点目录也会被拒绝。大小上限为 100 MB。
• 下载目录限制：jira_download_attachment 只会写入下载目录（ATLASSIAN_DOWNLOAD_DIR，默认为 ./atlassian-downloads/，首次使用时创建）。save_path 必须是纯文件名——目录、绝对路径和点文件都会被拒绝，不会被静默删减。现有文件绝不会被覆盖：系统会添加 -1、-2 这样的数字后缀，并返回最终路径。下载内容上限为 100 MB，与上传上限一致。请将 atlassian-downloads/ 添加到项目的 .gitignore。
• 桌面客户端注意事项：Claude Desktop 等客户端会以 / 或 $HOME 作为工作目录启动 stdio 服务，这会使文件系统的大部分区域成为上传根目录（点文件除外）。对于此类客户端，请明确设置 ATLASSIAN_UPLOAD_DIR（如果需要，也可设置 ATLASSIAN_DOWNLOAD_DIR）。
• 迁移（0.11 → 0.12）：上传现在仅限于 ATLASSIAN_UPLOAD_DIR（默认值：服务器的工作目录），且会拒绝点文件——如果客户端要从 ~/Downloads 上传，请设置 ATLASSIAN_UPLOAD_DIR=~/Downloads。下载现在会写入 ./atlassian-downloads/（或 ATLASSIAN_DOWNLOAD_DIR），而不是工作目录；save_path 只能是文件名，且现有文件绝不会被覆盖。
• 下载 URL 验证：服务器会根据已配置的 Jira URL 域名验证每个附件下载 URL，以防止 SSRF。
• SSL 验证：服务器默认会为 Jira 和 Confluence 启用 SSL 验证。仅当可信网络中使用自签名证书时才应禁用。
• MCP 工具注解：每个工具都会声明 readOnlyHint、destructiveHint 和 idempotentHint，用于客户端侧的权限提示。
• 不存储凭据：服务器在启动时从环境变量读取令牌，绝不会存储这些令牌。

速率限制和权限

速率限制

Jira Cloud 对每位用户实施速率限制。触发速率限制时，工具会返回 429 错误，并提示等待。由于 Team Calendars 插件的架构，Confluence Calendar API 调用可能较慢。

所需权限

CLI 与传输选项

# Default: stdio transport (for MCP clients)
uvx mcp-atlassian-extended

# HTTP transport. Use streamable-http for remote clients.
uvx mcp-atlassian-extended --transport streamable-http --port 9000

# A non-loopback HTTP bind requires a shared bearer token (>= 16 chars).
# Clients send it as "Authorization: Bearer <token>".
ATLASSIAN_HTTP_BEARER_TOKEN=$(openssl rand -hex 32) \
  uvx mcp-atlassian-extended --transport streamable-http --host 0.0.0.0 --port 9000

# sse still works, but the MCP 2026-07-28 spec deprecates it. The server prints a warning.
uvx mcp-atlassian-extended --transport sse --host 127.0.0.1 --port 8000

# CLI overrides for config
JIRA_PAT=xxx uvx mcp-atlassian-extended --jira-url https://jira.example.com --read-only

--jira-token、--jira-api-token、--confluence-token 和 --confluence-api-token 标志仍然可用，但已弃用且不会显示在 --help 中：它们会使令牌暴露在 ps 和 shell 历史记录中。请改用 JIRA_PAT / JIRA_API_TOKEN / CONFLUENCE_PAT / CONFLUENCE_API_TOKEN。

服务会通过 python-dotenv 自动从工作目录加载 .env 文件。

部分配置：你可以分别配置 Jira 和 Confluence。可以设置其中一个，也可以同时设置。服务始终会公布全部 22 个工具。对于未配置产品的工具，会返回“未配置”错误，并指出需要设置的变量。服务不会在启动时失败。

Docker

提供了一个精简的非 root 镜像。镜像默认锁定为只读模式（MCP_READ_ONLY=true）；传入 -e MCP_READ_ONLY=false 即可允许写入。

docker build -t mcp-atlassian-extended .
docker run --rm -i \
  -e JIRA_URL=https://your-company.atlassian.net \
  -e [email protected] -e JIRA_API_TOKEN=your_api_token \
  mcp-atlassian-extended

入口点是 mcp-atlassian-extended 命令；请在镜像名称后传入 CLI 标志。若要在已发布的端口上使用 HTTP 传输，还需设置 ATLASSIAN_HTTP_BEARER_TOKEN，并使用 --transport streamable-http --host 0.0.0.0 运行。

常见问题

是否支持 MCP 2026-07-28 规范（MCP 2.0）？

支持。它实现了 MCP 2026-07-28 规范（MCP 2.0），并兼容 2025-11-25 客户端。

支持哪些传输方式？

支持 stdio（默认）和 streamable-http（推荐用于远程客户端）。sse 传输仍然可用，但已被 2026-07-28 规范弃用。

我可以以只读模式运行 mcp-atlassian-extended，让助手无法更改任何内容吗？

可以。使用 MCP_READ_ONLY=true（或 ATLASSIAN_READ_ONLY=true）启动。这样一来，10 个写入工具和写入工作流提示词都不会被列出，因此模型不会看到它们；调用其中任何一个都会返回“未知工具”，并且在进程运行期间无法重新启用写入功能。请在你能控制的启动环境中设置该变量，例如受管 MCP 配置、容器或 systemd 环境，或托管部署，因为自行启动服务的用户可以不设置该变量。

它能与可自托管的 Jira 和 Confluence 配合使用吗？

可以。它支持 Jira Cloud、Jira Data Center、Confluence Cloud 和 Confluence Data Center。它使用 Jira REST API v2，可用于 Cloud 和 Server/Data Center。

需要哪些权限和令牌范围？

它需要 Jira API 令牌（Cloud）或个人访问令牌（Data Center）。每项操作都需要对应的 Jira 权限。请参阅所需权限。

它会取代 mcp-atlassian 吗？

不会。它与 mcp-atlassian 并行运行，不会有任何工具重叠。mcp-atlassian 负责核心搜索和 CRUD；此服务增加了附件、敏捷看板、版本和日历功能。

Confluence 工具需要附加组件吗？

需要。三个 Confluence 日历工具都需要 Team Calendars 附加组件。若未安装，它们会返回 404，并提示附加组件名称。

它提供多少个工具？

它为 Jira 和 Confluence 提供 22 个工具、15 个资源和 5 个提示词。

相关 MCP 服务

• mcp-gitlab — GitLab 集成（83 个工具、7 个资源、6 个提示词）
• mcp-coda — Coda 集成（53 个工具、12 个资源、5 个提示词）
• mcp-argocd — Argo CD 集成（37 个工具、7 个资源、7 个提示词）

致谢

灵感来自 sooperset 开发的 mcp-atlassian。架构和模式遵循类似的惯例。

开发

git clone https://github.com/vish288/mcp-atlassian-extended.git
cd mcp-atlassian-extended
uv sync --all-extras

uv run pytest --cov
uv run ruff check .
uv run ruff format --check .

许可证

MIT