MCP服务器--Atlassian

作者：arseni-konakhau0 星标更新：2025-08-15

安装使用来源：spider==github.com

项目介绍

MCP Atlassian

PyPI 版本 PyPI 下载量许可证

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 认证（云）- 推荐

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

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

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

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

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

转到 Atlassian 开发者控制台
创建一个 "OAuth 2.0 (3LO) 集成" 应用
配置权限（范围）以供 Jira/Confluence 使用
设置 回调 URL（例如，http://localhost:8080/callback）

运行设置向导：

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

根据提示输入 Client ID、Secret、URI 和 Scope
完成浏览器授权
将获得的凭据添加到 .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 的重要考虑事项：

令牌生命周期管理： 当使用 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 容器：

直接传递变量（如下面示例所示）
使用环境文件 并带有 --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>

这些示例展示了如何在使用 OAuth 2.0 进行 Atlassian 云时，在您的 IDE（如 Cursor 或 Claude Desktop）中配置 mcp-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 向导输出中获得的，或者您实例中已知的。

其他 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>