让 AI 直接操控你的 Jira 和 Confluence：mcp-atlassian 深度解析

想象这样一个场景：你是某科技公司的项目经理，每天早上的第一件事是打开 Jira，搜索"分配给我的任务"，再打开 Confluence 查找昨天更新的产品文档，然后在两个系统之间来回切换，把信息拼凑成一份日报。这个流程枯燥且耗时，但每天都在重复。

mcp-atlassian 试图解决的就是这个问题——它不是又一个 Jira 插件，而是一座桥：让 AI 助手直接"听懂"你对 Jira 和 Confluence 的操作需求，并用自然语言完成查询、创建、更新等任务。

背景：MCP 协议与 Atlassian 生态的碰撞

mcp-atlassian 由独立开发者 sooperset 创建，遵循 Anthropic 提出的 Model Context Protocol（MCP） 规范。MCP 的核心理念是：为 AI 语言模型定义一套标准化的"工具调用协议"，让 AI 能够安全、可控地调用外部工具。

Atlassian 生态（Jira + Confluence）是全球最广泛使用的项目管理与知识管理平台组合，尤其在软件开发和 IT 服务领域占据统治地位。然而，Atlassian 官方对 AI 集成的支持一直相对保守，这给开源社区留下了填补空白的空间。mcp-atlassian 正是瞄准这一缺口：让任何支持 MCP 的 AI 客户端（如 Claude Desktop、Cursor、Cline）都能直接操作 Atlassian 数据。

截至目前，该项目在 GitHub 上拥有超过 5300 颗星，被收录在 Anthropic 官方的 MCP Servers 列表中，展示了其在 MCP 生态中的重要地位。

核心功能：AI 与 Atlassian 的双向通道

mcp-atlassian 将操作能力封装为 MCP Tools，分两大模块：Jira 模块和 Confluence 模块。

Jira 工具集

Jira 模块是整个项目最核心的部分，支持 Jira Cloud 和 Jira Server/Data Center 双版本。核心工具包括：

• jira_search：使用 JQL（Jira Query Language）执行高级搜索，如"查找过去一周内更新的、分配给我的所有未完成 BUG"。
• jira_get_issue：获取某个 Issue 的完整详情，包括描述、评论、附件、子任务链路。
• jira_create_issue：在指定项目中创建新 Issue，自动处理字段映射和必填校验。
• jira_update_issue：更新 Issue 状态、描述、字段值，支持状态流转（transition）。
• jira_get_my_issues：快速获取当前用户被分配的 Issue 列表，无需手动写 JQL。
• jira_add_comment：在 Issue 下添加评论，支持 Atlassian Document Format（ADF）格式。
• jira_get_transitions：查询某个 Issue 当前可执行的状态流转操作。
• jira_get_sprints、jira_get_boards：获取敏捷看板和冲刺信息，支持 Scrum 和 Kanban 两种模式。
• jira_worklog：管理工时记录，支持查看和添加工作日志。
• jira_sla：读取 Jira Service Management 的 SLA 数据，帮助监控响应时效。

Confluence 工具集

Confluence 模块同样支持 Cloud 和 Data Center 双版本：

• confluence_search：使用 CQL（Confluence Query Language）搜索页面内容，支持全文检索。
• confluence_get_page：获取页面内容，支持将 Markdown 渲染为 HTML（用于展示）和 ADF 格式（用于编辑）。
• confluence_create_page：在指定空间下创建新页面，支持 Markdown 输入。
• confluence_update_page：更新页面内容，支持增量更新而非全量覆盖。
• confluence_get_spaces：列出用户有权访问的所有空间（Space）。
• confluence_get_comments：获取页面下的评论线程。
• confluence_get_attachments：管理页面附件，支持上传和下载。

认证与多租户支持

mcp-atlassian 支持多种认证方式，灵活适配不同部署场景：

Cloud 版：使用 JIRA_USERNAME + JIRA_API_TOKEN（从 https://id.atlassian.com/manage-profile/security/api-tokens 获取）。支持 OAuth 2.0 授权码流程，适合多用户场景。

Server/Data Center 版：使用 Personal Access Token（PAT），绕过 API Token 机制。兼容 Jira 8.14+ 和 Confluence 6.0+。

此外，项目还提供了 HTTP Transport 支持（通过 SSE 或 streamable-http），允许以 HTTP 服务方式运行 MCP Server，支持多用户并发访问，而不局限于单一本地进程。

技术架构：FastMCP 驱动的模块化设计

从代码结构来看，mcp-atlassian 采用分层模块化架构，核心分为以下几层：

Server 层（src/mcp_atlassian/servers/）：使用 FastMCP 框架作为 MCP Server 运行时，基于 Starlette 构建 HTTP 层，集成 Uvicorn ASGI 服务器。负责 MCP 协议的传输层（stdio / SSE / HTTP）抽象和生命周期管理。

协议适配层（src/mcp_atlassian/jira/ 和 src/mcp_atlassian/confluence/）：每个产品有独立的 Fetcher 类（如 JiraFetcher、ConfluenceFetcher），封装与 Atlassian REST API 的交互逻辑。包括 HTTP 客户端、认证头注入、请求重试、分页处理等。

模型层（src/mcp_atlassian/models/）：使用 Pydantic 定义数据结构，确保 API 响应的类型安全和序列化。Jira 模型支持 ADF（Atlassian Document Format）、Issue、Project、Sprint、Board 等核心实体；Confluence 模型覆盖 Page、Space、Comment、Label 等。

预处理层（src/mcp_atlassian/preprocessing/）：将 Atlassian API 返回的原始数据（如 HTML 内容、ADF 文档）转换为 Markdown，方便 AI 理解和处理。反向转换（Markdown → ADF）支持将 AI 生成的内容写回 Confluence。

工具层（src/mcp_atlassian/utils/）：提供通用能力——日志脱敏（mask_sensitive）、敏感信息管理（keyring 集成）、OAuth 流程、SSL/TLS 配置、URL 校验（防 SSRF）等。

关键依赖包括：atlassian-python-api（Atlassian API 封装）、fastmcp（MCP 协议框架）、httpx（异步 HTTP 客户端，支持 SOCKS 代理）、fakeredis（内存事件存储，用于 SSE 传输）、pydantic（数据验证）、trio（异步 I/O 运行时）。

项目使用 uv 作为包管理工具（Python 生态的新一代包管理器，速度极快），配合 hatchling + uv-dynamic-versioning 实现版本管理。Dockerfile 也基于 uv 构建多阶段镜像，体积控制优秀。

部署方式：从零到生产

mcp-atlassian 提供了多种部署路径，适合从个人开发到企业级的不同场景。

最简方式（uvx）：一行命令即可启动，无需手动安装 Python 环境：

uvx mcp-atlassian

前提是配置好 JIRA_URL、JIRA_API_TOKEN 等环境变量，然后在你使用的 AI IDE（如 Claude Desktop）的 MCP 配置文件中引用即可。

Docker 部署：提供了多阶段 Dockerfile，基于 python:3.13-alpine，最终镜像极小。容器启动命令如下（请根据实际环境替换占位符）：

docker run -e JIRA_URL=https://xxx.atlassian.net
  -e JIRA_USERNAME=your@email.com
  -e JIRA_API_TOKEN=xxx
  -p 8000:8000 ghcr.io/sooperset/mcp-atlassian

Helm 部署：项目自带生产级 Helm Chart，支持 Kubernetes 部署，提供 ConfigMap、Secret、Deployment、Service、Ingress、HPA（自动扩缩容）、RBAC 等全套 K8s 资源。对于已经在 K8s 上运行 AI 应用的企业，这是最推荐的部署方式。

硬件需求极低：无需 GPU，512MB RAM + 1GB 磁盘即可流畅运行。

代码质量：工程化程度高

从工程实践角度审视，mcp-atlassian 展现了较高的代码质量：

• 类型标注：全面使用 Python 类型注解，配合 mypy 进行静态类型检查。
• 代码规范：使用 ruff 作为 linter 和 formatter，遵循 PEP 8 和更多规则集（E/F/B/W/I/N/UP/ANN/S/BLE/FBT/C4/DTZ/EM/ISC/ICN），行长度 88 字符（Black 标准）。
• 测试覆盖：集成测试使用 pytest-asyncio，包含三类标记测试：integration（需要真实 Atlassian 实例）、cloud_e2e（云端端到端测试）、dc_e2e（Data Center 端到端测试）。
• 预提交检查：配置了 pre-commit 钩子，提交前自动运行格式化、类型检查等。
• 安全实践：实现了 SSRF 防护（validate_url_for_ssrf）、敏感信息脱敏（OAuth Token、API Token 不写入日志）、keyring 集成存储密钥、SSL/TLS 自定义配置。

局限与注意事项

mcp-atlassian 并非完美，以下几点在实际使用时需要特别注意：

1. API 权限依赖：AI 的操作能力完全取决于配置时使用的 Atlassian 账号权限。如果账号是普通成员，AI 无法访问受限页面或执行管理操作。

2. 无 Web UI：项目没有提供图形界面，所有配置和操作都需要通过环境变量或 AI 对话完成，对非技术用户有一定门槛。

3. SLA 限制：Confluence 的 SLA 功能需要 Jira Service Management，标准 Jira Software 用户无法使用。

4. Data Center 版本兼容：对 Jira Server 8.14 以下的版本和早期 Confluence 版本不支持，需要注意升级路径。

5. 数据隐私：API Token 以环境变量方式传递，需要确保运行环境安全，避免 Token 泄露。

行业意义：AI 助手进入企业协作流程的里程碑

mcp-atlassian 的出现标志着 AI 助手正在从"问答机器人"向"协作参与者"转型。在传统的 AI 应用范式中，AI 只能回答问题或生成内容；而 MCP 协议让 AI 获得了"动手能力"——它不再只是告诉你"这个 BUG 分配给谁了"，而是直接帮你创建 Issue、搜索文档、更新状态。

从技术趋势看，MCP 正在成为 AI 工具调用的"USB 标准"：Anthropic 主导的规范得到了 Claude Desktop、Cursor、Cline 等主流 AI 编程工具的支持。mcp-atlassian 作为最早一批 MCP Server 实现之一，在 Atlassian 生态内具有重要的示范意义——它证明了通过标准化协议，AI 可以深度接入企业级 SaaS 工具。

随着 MCP 生态的持续扩展，未来我们可以期待：AI 直接在 Jira 中创建冲刺计划、在 Confluence 中生成会议记录并自动关联相关 Issue。mcp-atlassian 为这些场景奠定了技术基础。

---

项目地址：sooperset/mcp-atlassian | 语言：Python | License：MIT | 星标：5,308