MCP Atlassian

Model Context Protocol (MCP) 服务器用于 Atlassian 产品（Confluence 和 Jira）。此集成支持 Confluence 和 Jira 的云部署以及服务器/数据中心部署。

示例用法

让您的AI助手执行以下操作：

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

功能演示

https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e

<details> <summary>Confluence 演示</summary>

https://github.com/user-attachments/assets/7fe9c488-ad0c-4876-9b54-120b666bb785

</details>

兼容性

产品	部署类型	支持状态
Confluence	云	✅ 完全支持
Confluence	服务器/数据中心	✅ 支持（版本 6.0+）
Jira	云	✅ 完全支持
Jira	服务器/数据中心	✅ 支持（版本 8.14+）

快速入门指南

🔐 1. 认证设置

MCP Atlassian 支持三种认证方法：

A. API Token 认证（云）- 推荐

1. 转到 https://id.atlassian.com/manage-profile/security/api-tokens
2. 点击 创建 API Token，命名它
3. 立即复制该令牌

B. 个人访问令牌（服务器/数据中心）

1. 转到您的个人资料（头像）→ 个人资料 → 个人访问令牌
2. 点击 创建令牌，命名它，设置有效期
3. 立即复制该令牌

C. OAuth 2.0 认证（云）- 高级

[!NOTE] OAuth 2.0 设置较为复杂，但提供了增强的安全功能。对于大多数用户来说，API Token 认证（方法A）更简单且足够使用。

1. 转到 Atlassian 开发者控制台
2. 创建一个“OAuth 2.0 (3LO) 集成”应用
3. 配置 权限（范围）以供 Jira/Confluence 使用
4. 设置 回调URL（例如：http://localhost:8080/callback）
5. 运行设置向导：

   docker run --rm -i \
     -p 8080:8080 \
     -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
     ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v
   

6. 根据提示输入 Client ID、Secret、URI 和 Scope
7. 完成浏览器授权
8. 将获得的凭据添加到 .env 或IDE配置中：
   • ATLASSIAN_OAUTH_CLOUD_ID（来自向导）
   • ATLASSIAN_OAUTH_CLIENT_ID
   • ATLASSIAN_OAUTH_CLIENT_SECRET
   • ATLASSIAN_OAUTH_REDIRECT_URI
   • ATLASSIAN_OAUTH_SCOPE

[!IMPORTANT] 对于上述标准OAuth流程，请在您的范围中包含 offline_access（例如：read:jira-work write:jira-work offline_access）。这允许服务器自动刷新访问令牌。

<details> <summary>替代方案：使用预存在的OAuth访问令牌（BYOT）</summary>

如果您正在运行作为更大系统一部分的mcp-atlassian，该系统外部管理Atlassian OAuth 2.0访问令牌（例如，通过中央身份提供者或另一个应用程序），您可以直接为此MCP服务器提供访问令牌。这种方法绕过了交互式设置向导和服务器内部的令牌管理（包括刷新能力）。

要求：

• 有效的Atlassian OAuth 2.0访问令牌，具有执行预期操作所需的范围。
• 对应的ATLASSIAN_OAUTH_CLOUD_ID用于您的Atlassian实例。

配置： 要使用此方法，请设置以下环境变量（或在启动服务器时使用相应的命令行标志）：

• ATLASSIAN_OAUTH_CLOUD_ID：您的Atlassian Cloud ID。（CLI：--oauth-cloud-id）
• ATLASSIAN_OAUTH_ACCESS_TOKEN：您预存在的OAuth 2.0访问令牌。（CLI：--oauth-access-token）

重要注意事项：

• 令牌生命周期管理： 当使用BYOT时，MCP服务器不处理令牌刷新。获取、刷新（在过期前）和撤销访问令牌的责任完全在于您或提供令牌的外部系统。
• 未使用的变量： 标准OAuth客户端变量（ATLASSIAN_OAUTH_CLIENT_ID，ATLASSIAN_OAUTH_CLIENT_SECRET，ATLASSIAN_OAUTH_REDIRECT_URI，ATLASSIAN_OAUTH_SCOPE）不使用，并且在配置BYOT时可以省略。
• 无设置向导： --oauth-setup向导不适用，不应用于此方法。
• 无令牌缓存卷： 如果仅使用BYOT方法，则不需要Docker卷挂载用于存储令牌（例如，-v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian"），因为没有令牌由该服务器存储或管理。
• 范围： 提供的访问令牌必须已经具有执行Jira/Confluence操作所需的权限（范围）。

此选项在OAuth凭证管理集中化或由其他基础设施组件处理的情况下非常有用。

</details>

[!TIP] 多云OAuth支持：如果您正在构建一个多租户应用程序，其中用户提供自己的OAuth令牌，请参阅多云OAuth支持部分以进行最小配置设置。

📦 2. 安装

MCP Atlassian 作为Docker镜像分发。这是推荐的运行服务器的方式，特别是对于IDE集成。确保已安装Docker。

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

🛠️ IDE 集成

MCP Atlassian 设计为通过IDE集成与AI助手一起使用。

[!TIP] 对于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

对于Cursor：打开设置 → MCP → + 添加新的全局MCP服务器

⚙️ 配置方法

有两种主要方式来配置Docker容器：

1. 直接传递变量（如下面的示例所示）
2. 使用环境文件 并带有 --env-file 标志（如折叠部分所示）

[!NOTE] 常见环境变量包括：

• CONFLUENCE_SPACES_FILTER：按空间键过滤（例如："DEV,TEAM,DOC"）
• JIRA_PROJECTS_FILTER：按项目键过滤（例如："PROJ,DEV,SUPPORT"）
• READ_ONLY_MODE：设置为 "true" 以禁用写操作
• MCP_VERBOSE：设置为 "true" 以获取更详细的日志
• MCP_LOGGING_STDOUT：设置为 "true" 以将日志输出到stdout而不是stderr
• ENABLED_TOOLS：启用工具名称的逗号分隔列表（例如："confluence_search,jira_get_issue"）

查看 .env.example 文件以获取所有可用选项。

📝 配置示例

方法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"
      }
    }
  }
}

<details> <summary>替代方案：使用环境文件</summary>

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

</details> <details> <summary>服务器/数据中心配置</summary>

对于服务器/数据中心部署，使用直接变量传递：

{
  "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"
      }
    }
  }
}

[!NOTE] 只有在使用自签名证书时才将 CONFLUENCE_SSL_VERIFY 和 JIRA_SSL_VERIFY 设置为 "false"。

</details> <details> <summary>OAuth 2.0 配置（仅限云）</summary> <a name="oauth-20-configuration-example-cloud-only"></a>

这些示例展示了如何在IDE（如Cursor或Claude Desktop）中配置 mcp-atlassian，当使用OAuth 2.0进行Atlassian云时。

标准OAuth 2.0 流程示例（使用设置向导）：

此配置适用于使用服务器内置OAuth客户端并已完成OAuth设置向导的情况。

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "<path_to_your_home>/.mcp-atlassian:/home/app/.mcp-atlassian",
        "-e", "JIRA_URL",
        "-e", "CONFLUENCE_URL",
        "-e", "ATLASSIAN_OAUTH_CLIENT_ID",
        "-e", "ATLASSIAN_OAUTH_CLIENT_SECRET",
        "-e", "ATLASSIAN_OAUTH_REDIRECT_URI",
        "-e", "ATLASSIAN_OAUTH_SCOPE",
        "-e", "ATLASSIAN_OAUTH_CLOUD_ID",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "ATLASSIAN_OAUTH_CLIENT_ID": "YOUR_OAUTH_APP_CLIENT_ID",
        "ATLASSIAN_OAUTH_CLIENT_SECRET": "YOUR_OAUTH_APP_CLIENT_SECRET",
        "ATLASSIAN_OAUTH_REDIRECT_URI": "http://localhost:8080/callback",
        "ATLASSIAN_OAUTH_SCOPE": "read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access",
        "ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_CLOUD_ID_FROM_SETUP_WIZARD"
      }
    }
  }
}

[!NOTE]

• 对于标准流程：
  • ATLASSIAN_OAUTH_CLOUD_ID 是从 --oauth-setup 向导输出中获得的，或者您知道的实例ID。
  • 其他 ATLASSIAN_OAUTH_* 客户端变量来自您在Atlassian开发者控制台中的OAuth应用。
  • 您的云实例的 JIRA_URL 和 CONFLUENCE_URL 总是需要的。
  • 卷挂载（-v .../.mcp-atlassian:/home/app/.mcp-atlassian）对于持久保存向导获得的OAuth令牌至关重要，使自动刷新成为可能。

预存在访问令牌示例（BYOT - 自带令牌）：

此配置适用于您提供自己外部管理的OAuth 2.0访问令牌的情况。

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "CONFLUENCE_URL",
        "-e", "ATLASSIAN_OAUTH_CLOUD_ID",
        "-e", "ATLASSIAN_OAUTH_ACCESS_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_KNOWN_CLOUD_ID",
        "ATLASSIAN_OAUTH_ACCESS_TOKEN": "YOUR_PRE_EXISTING_OAUTH_ACCESS_TOKEN"
      }
    }
  }
}

[!NOTE]

• 对于BYOT方法：
  • 您主要需要 JIRA_URL，CONFLUENCE_URL，ATLASSIAN_OAUTH_CLOUD_ID 和 ATLASSIAN_OAUTH_ACCESS_TOKEN。
  • 标准OAuth客户端变量（ATLASSIAN_OAUTH_CLIENT_ID，CLIENT_SECRET，REDIRECT_URI，SCOPE）不使用。
  • 令牌生命周期（例如，在令牌过期前刷新令牌并重新启动mcp-atlassian）是您的责任，因为服务器不会刷新BYOT令牌。

</details> <details> <summary>代理配置</summary>

MCP Atlassian 支持通过标准HTTP/HTTPS/SOCKS代理路由API请求。使用环境变量进行配置：

• 支持标准 HTTP_PROXY，HTTPS_PROXY，NO_PROXY，SOCKS_PROXY。
• 提供服务特定的覆盖（例如，JIRA_HTTPS_PROXY，CONFLUENCE_NO_PROXY）。
• 服务特定变量覆盖该服务的全局变量。

将相关的代理变量添加到您的MCP配置的 args（使用 -e）和 env 部分：

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "... 已存在的Confluence/Jira变量",
        "-e", "HTTP_PROXY",
        "-e", "HTTPS_PROXY",
        "-e", "NO_PROXY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "... 已存在的Confluence/Jira变量": "...",
        "HTTP_PROXY": "http://proxy.internal:8080",
        "HTTPS_PROXY": "http://proxy.internal:8080",
        "NO_PROXY": "localhost,.your-company.com"
      }
    }
  }
}

代理URL中的凭据在日志中被屏蔽。如果设置了 NO_PROXY，则匹配主机的请求将被尊重。

</details> <details> <summary>自定义HTTP头部配置</summary>

MCP Atlassian 支持向所有API请求添加自定义HTTP头部。此功能在企业环境中特别有用，其中需要额外的头部来进行安全、认证或路由目的。

自定义头部使用逗号分隔的键值对