MCP-Atlassian 项目详细介绍

项目概述

MCP-Atlassian 是一个基于 Model Context Protocol (MCP) 的服务器，专为 Atlassian 产品（Confluence 和 Jira）设计。该项目允许 AI 助手（如 Claude）直接访问和操作您的 Atlassian 工作空间数据，实现智能化的工作流程管理。

项目基本信息

• 项目名称: mcp-atlassian
• 开发者: sooperset
• GitHub地址: https://github.com/sooperset/mcp-atlassian
• 部署方式: Docker 容器

核心功能特性

AI 驱动的智能操作

项目支持多种 AI 助手驱动的智能操作：

• 📝 自动 Jira 更新 - "从我们的会议记录更新 Jira"
• 🔍 AI 驱动的 Confluence 搜索 - "在 Confluence 中找到我们的 OKR 指南并总结"
• 🐛 智能 Jira 问题过滤 - "显示上周 PROJ 项目中的紧急 bug"
• 📄 内容创建与管理 - "为 XYZ 功能创建技术设计文档"

产品兼容性支持

产品	部署类型	支持状态
Confluence	Cloud	✅ 完全支持
Confluence	Server/Data Center	✅ 支持 (版本 6.0+)
Jira	Cloud	✅ 完全支持
Jira	Server/Data Center	✅ 支持 (版本 8.14+)

安装与配置

前置要求

• Docker 环境
• Atlassian API Token（云版）或个人访问令牌（服务器版）

获取认证令牌

Atlassian Cloud:

1. 访问 https://id.atlassian.com/manage-profile/security/api-tokens
2. 点击 "Create API token"，命名并复制令牌

Server/Data Center:

1. 前往个人资料 → 个人访问令牌
2. 点击 "Create token"，设置到期时间并复制令牌

Docker 镜像获取

# 拉取预构建镜像
docker pull ghcr.io/sooperset/mcp-atlassian:latest

IDE 集成配置

Claude Desktop 配置

配置文件位置：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

方法1：直接传递变量

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME", 
        "-e", "CONFLUENCE_API_TOKEN",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com", 
        "JIRA_API_TOKEN": "your_jira_api_token"
      }
    }
  }
}

方法2：使用环境文件

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm", 
        "-i",
        "--env-file",
        "/path/to/your/mcp-atlassian.env",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}

Server/Data Center 配置

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i", 
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_PERSONAL_TOKEN",
        "-e", "CONFLUENCE_SSL_VERIFY",
        "-e", "JIRA_URL", 
        "-e", "JIRA_PERSONAL_TOKEN",
        "-e", "JIRA_SSL_VERIFY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_confluence_pat",
        "CONFLUENCE_SSL_VERIFY": "false",
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_jira_pat", 
        "JIRA_SSL_VERIFY": "false"
      }
    }
  }
}

环境变量说明

常用环境变量：

• CONFLUENCE_SPACES_FILTER: 按空间键过滤 (例如: "DEV,TEAM,DOC")
• JIRA_PROJECTS_FILTER: 按项目键过滤 (例如: "PROJ,DEV,SUPPORT")
• READ_ONLY_MODE: 设置为 "true" 禁用写操作
• MCP_VERBOSE: 设置为 "true" 启用详细日志
• ENABLED_TOOLS: 逗号分隔的工具名称列表

可用工具功能

Confluence 工具

工具名称	功能描述
confluence_search	使用 CQL 搜索 Confluence 内容
confluence_get_page	获取特定页面内容
confluence_get_page_children	获取页面子页面
confluence_get_page_ancestors	获取页面父级页面
confluence_get_comments	获取页面评论
confluence_create_page	创建新页面
confluence_update_page	更新现有页面
confluence_delete_page	删除页面
confluence_get_labels	获取标签
confluence_add_label	添加标签

Jira 工具

工具名称	功能描述
jira_get_issue	获取特定问题详情
jira_search	使用 JQL 搜索问题
jira_get_project_issues	获取项目问题
jira_get_epic_issues	获取史诗问题
jira_create_issue	创建新问题
jira_batch_create_issues	批量创建问题
jira_update_issue	更新现有问题
jira_delete_issue	删除问题
jira_get_transitions	获取问题状态转换
jira_transition_issue	转换问题状态
jira_add_comment	添加评论
jira_add_worklog	添加工作日志
jira_get_worklog	获取工作日志
jira_download_attachments	下载附件
jira_link_to_epic	链接到史诗
jira_get_agile_boards	获取看板
jira_get_board_issues	获取看板问题
jira_get_sprints_from_board	获取看板冲刺
jira_get_sprint_issues	获取冲刺问题
jira_create_sprint	创建冲刺
jira_update_sprint	更新冲刺
jira_get_issue_link_types	获取问题链接类型
jira_create_issue_link	创建问题链接
jira_remove_issue_link	移除问题链接

注：标记为 * 的工具仅在 Jira Cloud 上可用

访问控制

工具过滤

使用 --enabled-tools 标志或 ENABLED_TOOLS 环境变量指定可用工具：

# 通过环境变量
ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"

# 或通过命令行标志
docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...

读写控制

工具分为读取和写入操作。启用 READ_ONLY_MODE 时，无论 ENABLED_TOOLS 设置如何，仅读取操作可用。

故障排除

常见问题解决

认证失败:

• Cloud版：检查 API 令牌（不是账户密码）
• Server/Data Center版：验证个人访问令牌有效且未过期
• 旧版 Confluence 服务器：可能需要使用 CONFLUENCE_USERNAME 和 CONFLUENCE_API_TOKEN（令牌为密码）

SSL 证书问题: Server/Data Center 部署如遇 SSL 错误，设置 CONFLUENCE_SSL_VERIFY=false 或 JIRA_SSL_VERIFY=false

权限错误: 确保 Atlassian 账户有足够权限访问相关空间/项目

调试方法

使用 MCP Inspector 测试:

npx @modelcontextprotocol/inspector uvx mcp-atlassian ...

查看日志:

# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Windows  
type %APPDATA%\Claude\logs\mcp*.log | more

使用 SSE 传输

除了标准的 stdio 传输，还支持 Server-Sent Events (SSE)：

1. 在终端手动启动服务器：

docker run --rm -p 9000:9000 \
  --env-file /path/to/your/.env \
  ghcr.io/sooperset/mcp-atlassian:latest \
  --transport sse --port 9000 -vv

2. 配置 IDE 连接到运行中的服务器：

{
  "mcpServers": {
    "mcp-atlassian-sse": {
      "url": "http://localhost:9000/sse"
    }
  }
}

安全考虑

• 永远不要分享 API 令牌
• 保持 .env 文件安全和私密
• 查看 SECURITY.md 了解最佳实践

技术架构

该项目采用 Docker 容器化部署，通过 Model Context Protocol 与 AI 助手进行通信。支持多种传输方式（stdio 和 SSE），能够灵活适应不同的部署环境和使用场景。

项目设计考虑了企业级应用的需求，支持 Atlassian 的云版和私有部署版本，提供了完整的认证、权限控制和安全机制。

---

注意: 这不是 Atlassian 官方产品，而是由社区开发者 sooperset 维护的开源项目。