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:

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

Server/Data Center:

前往个人资料 → 个人访问令牌
点击 "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": "[email protected]",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "[email protected]", 
        "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)：

在终端手动启动服务器：

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

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

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

安全考虑

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

技术架构

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

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

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