MCP Atlassian

适用于 Atlassian 产品（Confluence 和 Jira）的模型上下文协议 (MCP) 服务器。此集成支持 Confluence & Jira Cloud 以及服务器/数据中心部署。

示例用法

要求你的人工智能助手：

• 📝 自动 Jira 更新- “从我们的会议记录更新 Jira”

• 🔍 人工智能驱动的 Confluence 搜索- “在 Confluence 中查找我们的 OKR 指南并进行总结”

• 🐛 智能 Jira 问题过滤- “显示上周 PROJ 项目中的紧急错误”

• 📄 内容创建和管理- “为 XYZ 功能创建技术设计文档”

功能演示

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

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

兼容性

快速入门指南

🔐 1. 身份验证设置

MCP Atlassian 支持三种身份验证方法：

A. API 令牌认证（云）

1. 前往https://id.atlassian.com/manage-profile/security/api-tokens

2. 点击创建 API 令牌，并命名

3. 立即复制令牌

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

1. 前往您的个人资料（头像）→个人资料→个人访问令牌

2. 单击创建令牌，命名，设置有效期

3. 立即复制令牌

C.OAuth 2.0身份验证（云）

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

📦 2. 安装

MCP Atlassian 以 Docker 镜像的形式分发。这是运行服务器的推荐方式，尤其适用于 IDE 集成。请确保已安装 Docker。

🛠️ IDE 集成

MCP Atlassian 旨在通过 IDE 集成与 AI 助手一起使用。

⚙️ 配置方法

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

1. 直接传递变量（如下例所示）

2. 使用带有--env-file标志的环境文件（显示在可折叠部分）

常见的环境变量包括：

• CONFLUENCE_SPACES_FILTER ：按空格键过滤（例如“DEV、TEAM、DOC”）

• JIRA_PROJECTS_FILTER ：按项目键过滤（例如“PROJ、DEV、SUPPORT”）

• READ_ONLY_MODE ：设置为“true”以禁用写入操作

• MCP_VERBOSE ：设置为“true”以获得更详细的日志记录

• ENABLED_TOOLS ：要启用的工具名称的逗号分隔列表（例如“confluence_search，jira_get_issue”）

请参阅.env.example文件以了解所有可用选项。

📝 配置示例

方法 1（直接传递变量）：

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

本示例展示了如何在您的 IDE（例如 Cursor 或 Claude Desktop）中配置mcp-atlassian并在 Atlassian Cloud 上使用 OAuth 2.0。请确保您已完成OAuth 设置向导。

[！笔记]

• ATLASSIAN_OAUTH_CLOUD_ID是从--oauth-setup向导输出中获得的。

• 其他ATLASSIAN_OAUTH_*变量是您在 Atlassian 开发者控制台中为您的 OAuth 应用配置的变量（并用作安装向导的输入）。

• 您的云实例的JIRA_URL和CONFLUENCE_URL仍然是必需的。

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

• 支持标准HTTP_PROXY 、 HTTPS_PROXY 、 NO_PROXY 、 SOCKS_PROXY 。

• 可以使用特定于服务的覆盖（例如， JIRA_HTTPS_PROXY ， CONFLUENCE_NO_PROXY ）。

• 特定于服务的变量会覆盖该服务的全局变量。

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

代理 URL 中的凭证在日志中会被屏蔽。如果您设置了NO_PROXY ，则对匹配主机的请求将遵循该设置。

仅适用于 Confluence Cloud：

对于 Confluence Server/DC，使用：

仅适用于 Jira Cloud：

对于 Jira Server/DC，使用：

👥 HTTP 传输配置

除了使用stdio之外，您还可以使用以下任一方式将服务器作为持久 HTTP 服务运行：

• /sse端点的sse （���务器发送事件）传输

• /mcp端点上的streamable-http传输

两种传输类型都支持单用户和多用户身份验证：

身份验证选项：

• 单用户：使用通过环境变量配置的服务器级身份验证

• 多用户：每个用户提供自己的身份验证：

  • 云：OAuth 2.0 Bearer 令牌

  • 服务器/数据中心：个人访问令牌（PAT）

1. 使用您选择的传输方式启动服务器：

   # For SSE transport docker run --rm -p 9000:9000 \ --env-file /path/to/your/.env \ ghcr.io/sooperset/mcp-atlassian:latest \ --transport sse --port 9000 -vv # OR for streamable-http transport docker run --rm -p 9000:9000 \ --env-file /path/to/your/.env \ ghcr.io/sooperset/mcp-atlassian:latest \ --transport streamable-http --port 9000 -vv

2. 配置您的 IDE（单用户示例）：

   SSE 传输示例：

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

   Streamable-HTTP 传输示例：

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

以下是使用流式 HTTP 传输设置多用户身份验证的完整示例：

1. 首先，运行 OAuth 设置向导来配置服务器的 OAuth 凭据：

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

2. 使用流式 HTTP 传输启动服务器：

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

3. 配置 IDE 的 MCP 设置：

为您的 Atlassian 部署选择适当的授权方法：

• **云（OAuth 2.0）：**如果您的组织在 Atlassian Cloud 上，并且您为每个用户都有一个 OAuth 访问令牌，请使用此功能。

• **服务器/数据中心（PAT）：**如果您在 Atlassian 服务器或数据中心并且每个用户都有个人访问令牌（PAT），请使用此功能。

云（OAuth 2.0）示例：

服务器/数据中心 (PAT) 示例：

4. .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

[！笔记]

• 服务器应该配置自己的备用身份验证（例如，通过 API 令牌、PAT 的环境变量，或使用 --oauth-setup 设置自己的 OAuth）。如果请求不包含用户特定的身份验证，则使用此选项。

• OAuth ：每个用户都需要从您的 Atlassian OAuth 应用获取自己的 OAuth 访问令牌。

• PAT ：每个用户提供自己的个人访问令牌。

• 如果用户提供令牌，服务器将使用用户令牌进行 API 调用；如果用户未提供令牌，则返回服务器身份验证

• 用户令牌应具有适合其所需操作的范围

工具

关键工具

Jira 工具

• jira_get_issue ：获取特定问题的详细信息

• jira_search ：使用 JQL 搜索问题

• jira_create_issue ：创建新问题

• jira_update_issue ：更新现有问题

• jira_transition_issue ：将问题转换为新状态

• jira_add_comment ：向问题添加评论

Confluence 工具

• confluence_search ：使用 CQL 搜索 Confluence 内容

• confluence_get_page ：获取特定页面的内容

• confluence_create_page ：创建新页面

• confluence_update_page ：更新现有页面

*该工具仅在 Jira Cloud 上可用

工具过滤和访问控制

服务器提供了两种控制工具访问的方式：

1. 工具过滤：使用--enabled-tools标志或ENABLED_TOOLS环境变量来指定哪些工具可用：

   # Via environment variable ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search" # Or via command line flag docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...

2. 读/写控制：工具分为读操作和写操作。启用READ_ONLY_MODE后，无论ENABLED_TOOLS设置如何，都只能进行读操作。

故障排除和调试

常见问题

• 身份验证失败：

  • 对于云：检查您的 API 令牌（而不是您的帐户密码）

  • 对于服务器/数据中心：验证您的个人访问令牌是否有效且未过期

  • 对于较旧的 Confluence 服务器：某些旧版本需要使用CONFLUENCE_USERNAME和CONFLUENCE_API_TOKEN进行基本身份验证（其中 token 是您的密码）

• SSL 证书问题：如果使用服务器/数据中心并遇到 SSL 错误，请设置CONFLUENCE_SSL_VERIFY=false或JIRA_SSL_VERIFY=false

• 权限错误：确保您的 Atlassian 帐户具有足够的权限来访问空间/项目

调试工具

安全

• 切勿共享 API 令牌

• 确保 .env 文件的安全性和私密性

• 请参阅SECURITY.md了解最佳实践

贡献

欢迎为 MCP Atlassian 做出贡献！如果您想贡献：

1. 查看我们的CONTRIBUTING.md指南，了解详细的开发设置说明。

2. 进行更改并提交拉取请求。

我们使用预提交钩子来保证代码质量，并遵循语义版本控制来发布。

执照

采用 MIT 许可 - 请参阅LICENSE文件。本产品非 Atlassian 官方产品。