MCP Atlassian

用于Atlassian产品（Confluence和Jira）的模型上下文协议（MCP）服务器。此集成支持Confluence & Jira Cloud以及Server/Data Center部署。

示例用法

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

• 📝 自动Jira更新 - "根据我们的会议记录更新Jira"
• 🔍 基于AI的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

兼容性

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

快速入门指南

🔐 1. 身份验证设置

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

A. API令牌身份验证（Cloud）- 推荐

1. 访问 https://id.atlassian.com/manage-profile/security/api-tokens
2. 点击 创建API令牌，为其命名
3. 立即复制令牌

B. 个人访问令牌（Server/Data Center）

1. 进入您的个人资料（头像）→ 个人资料 → 个人访问令牌
2. 点击 创建令牌，为其命名，设置过期时间
3. 立即复制令牌

C. OAuth 2.0身份验证（Cloud）- 高级

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

1. 访问 Atlassian开发者控制台

2. 创建一个"OAuth 2.0 (3LO)集成"应用

3. 配置Jira/Confluence的权限（范围）

4. 设置回调URL（例如，http://localhost:8080/callback）

5. 运行设置向导：
   bash
   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）。这允许服务器自动刷新访问令牌。

要求：

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

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

• 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 凭证管理集中化或由其他基础设施组件处理时，此选项非常有用。

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

📦 2. 安装

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

bash

拉取预构建镜像

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（直接传递变量）：
json
{
"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"
}
}
}
}

json
{
"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 部署，请使用直接变量传递：

json
{
"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"。

这些示例展示了如何在您的 IDE（如 Cursor 或 Claude Desktop）中配置 mcp-atlassian 以使用 OAuth 2.0 进行 Atlassian Cloud 认证。

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

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

json
{
"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。

自带访问令牌 (BYOT - Bring Your Own Token) 的示例：

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

json
{
"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 令牌。

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

• 支持标准 HTTP_PROXY、HTTPS_PROXY、NO_PROXY、SOCKS_PROXY。
• 可以使用特定服务的覆盖（例如 JIRA_HTTPS_PROXY、CONFLUENCE_NO_PROXY）。
• 特定服务的变量会覆盖该服务的全局变量。

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

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

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

MCP Atlassian 支持为所有 API 请求添加自定义 HTTP 头。此功能在需要额外头用于安全、身份验证或路由目的的企业环境中特别有用。

自定义头通过逗号分隔的键值对环境变量进行配置：

json
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "CONFLUENCE_URL",
"-e", "CONFLUENCE_USERNAME",
"-e", "CONFLUENCE_API_TOKEN",
"-e", "CONFLUENCE_CUSTOM_HEADERS",
"-e", "JIRA_URL",
"-e", "JIRA_USERNAME",
"-e", "JIRA_API_TOKEN",
"-e", "JIRA_CUSTOM_HEADERS",
"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",
"CONFLUENCE_CUSTOM_HEADERS": "X-Confluence-Service=mcp-integration,X-Custom-Auth=confluence-token,X-ALB-Token=secret-token",
"JIRA_URL": "https://your-company.atlassian.net",
"JIRA_USERNAME": "your.email@company.com",
"JIRA_API_TOKEN": "your_jira_api_token",
"JIRA_CUSTOM_HEADERS": "X-Forwarded-User=service-account,X-Company-Service=mcp-atlassian,X-Jira-Client=mcp-integration"
}
}
}
}安全性注意事项：

• 自定义头部值在调试日志中被屏蔽，以保护敏感信息
• 确保自定义头部不与标准HTTP或Atlassian API头部冲突
• 如果已经使用了基本认证或OAuth，请避免在自定义头部中包含敏感的认证令牌
• 头部会随每个API请求发送 - 请验证它们不会干扰API的功能

MCP Atlassian 支持多云 OAuth 场景，其中每个用户连接到他们自己的 Atlassian 云实例。这对于多租户应用、聊天机器人或用户提供自己 OAuth 令牌的服务非常有用。

最小化 OAuth 配置：

1. 启用最小化 OAuth 模式（不需要客户端凭证）：
   bash
   docker run -e ATLASSIAN_OAUTH_ENABLE=true -p 9000:9000
   ghcr.io/sooperset/mcp-atlassian:latest
   --transport streamable-http --port 9000

2. 用户通过 HTTP 头提供认证：

   • Authorization: Bearer <user_oauth_token>
   • X-Atlassian-Cloud-Id: <user_cloud_id>

集成示例 (Python):
python
import asyncio
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

user_token = "user-specific-oauth-token"
user_cloud_id = "user-specific-cloud-id"

async def main():
# 使用自定义头部连接到可流式传输的 HTTP 服务器
async with streamablehttp_client(
"http://localhost:9000/mcp",
headers={
"Authorization": f"Bearer {user_token}",
"X-Atlassian-Cloud-Id": user_cloud_id
}
) as (read_stream, write_stream, _):
# 使用客户端流创建会话
async with ClientSession(read_stream, write_stream) as session:
# 初始化连接
await session.initialize()

        # 示例：获取 Jira 问题
        result = await session.call_tool(
            "jira_get_issue",
            {"issue_key": "PROJ-123"}
        )
        print(result)

asyncio.run(main())

配置说明：

• 每个请求可以通过 X-Atlassian-Cloud-Id 头使用不同的云实例
• 用户令牌按请求隔离 - 不会发生跨租户数据泄露
• 如果未提供头，则回退到全局 ATLASSIAN_OAUTH_CLOUD_ID
• 兼容标准 OAuth 2.0 承载令牌认证

仅适用于 Confluence Cloud：

json
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CONFLUENCE_URL",
"-e", "CONFLUENCE_USERNAME",
"-e", "CONFLUENCE_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_api_token"
}
}
}
}

对于 Confluence Server/DC，请使用：
json
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "CONFLUENCE_URL",
"-e", "CONFLUENCE_PERSONAL_TOKEN",
"ghcr.io/sooperset/mcp-atlassian:latest"
],
"env": {
"CONFLUENCE_URL": "https://confluence.your-company.com",
"CONFLUENCE_PERSONAL_TOKEN": "your_personal_token"
}
}
}
}

仅适用于 Jira Cloud：

json
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "JIRA_URL",
"-e", "JIRA_USERNAME",
"-e", "JIRA_API_TOKEN",
"ghcr.io/sooperset/mcp-atlassian:latest"
],
"env": {
"JIRA_URL": "https://your-company.atlassian.net",
"JIRA_USERNAME": "your.email@company.com",
"JIRA_API_TOKEN": "your_api_token"
}
}
}
}对于 Jira Server/DC，请使用：
json
{
"mcpServers": {
"mcp-atlassian": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "JIRA_URL",
"-e", "JIRA_PERSONAL_TOKEN",
"ghcr.io/sooperset/mcp-atlassian:latest"
],
"env": {
"JIRA_URL": "https://jira.your-company.com",
"JIRA_PERSONAL_TOKEN": "your_personal_token"
}
}
}
}

👥 HTTP 传输配置

除了使用 stdio，您还可以通过以下方式将服务器作为持久的 HTTP 服务运行：

• 在 /sse 端点上使用 sse（Server-Sent Events）传输
• 在 /mcp 端点上使用 streamable-http 传输

这两种传输类型都支持单用户和多用户认证：

认证选项：

• 单用户：通过环境变量配置服务器级认证
• 多用户：每个用户提供自己的认证：
  • 云：OAuth 2.0 Bearer 令牌
  • 服务器/数据中心：个人访问令牌 (PATs)

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

   bash

   对于 SSE 传输

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

   或者对于 streamable-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

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

   SSE 传输示例：
   json
   {
   "mcpServers": {
   "mcp-atlassian-http": {
   "url": "http://localhost:9000/sse"
   }
   }
   }

   Streamable-HTTP 传输示例：
   json
   {
   "mcpServers": {
   "mcp-atlassian-service": {
   "url": "http://localhost:9000/mcp"
   }
   }
   }

这里是一个完整的示例，展示如何使用 streamable-HTTP 传输设置多用户认证：

1. 首先，运行 OAuth 设置向导以配置服务器的 OAuth 凭据：
   bash
   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. 使用 streamable-HTTP 传输启动服务器：
   bash
   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 云上，并且每个用户都有一个 OAuth 访问令牌，请使用此方法。
• 服务器/数据中心（PAT）：如果您在 Atlassian 服务器或数据中心上，并且每个用户都有一个个人访问令牌 (PAT)，请使用此方法。

云（OAuth 2.0）示例：
json
{
"mcpServers": {
"mcp-atlassian-service": {
"url": "http://localhost:9000/mcp",
"headers": {
"Authorization": "Bearer <USER_OAUTH_ACCESS_TOKEN>"
}
}
}
}

服务器/数据中心（PAT）示例：
json
{
"mcpServers": {
"mcp-atlassian-service": {
"url": "http://localhost:9000/mcp",
"headers": {
"Authorization": "Token <USER_PERSONAL_ACCESS_TOKEN>"
}
}
}
}

1. .env 文件中所需的环境变量：
   bash
   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

工具

关键工具

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 工具	Confluence 工具
读取	jira_search	confluence_search
	jira_get_issue	confluence_get_page
	jira_get_all_projects	confluence_get_page_children
	jira_get_project_issues	confluence_get_comments
	jira_get_worklog	confluence_get_labels
	jira_get_transitions	confluence_search_user
	jira_search_fields
	jira_get_agile_boards
	jira_get_board_issues
	jira_get_sprints_from_board
	jira_get_sprint_issues
	jira_get_issue_link_types
	jira_batch_get_changelogs*
	jira_get_user_profile
	jira_download_attachments
	jira_get_project_versions
写入	jira_create_issue	confluence_create_page
	jira_update_issue	confluence_update_page
	jira_delete_issue	confluence_delete_page
	jira_batch_create_issues	confluence_add_label
	jira_add_comment	confluence_add_comment
	jira_transition_issue
	jira_add_worklog
	jira_link_to_epic
	jira_create_sprint
	jira_update_sprint
	jira_create_issue_link
	jira_remove_issue_link
	jira_create_version

*此工具仅在 Jira Cloud 上可用

工具过滤和访问控制

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

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

   bash

   通过环境变量

   ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"

   或者通过命令行标志

   docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...

2. 读/写控制：工具被分类为读操作或写操作。当启用 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 帐户具有足够的权限来访问空间/项目
• 自定义标头问题：请参阅下面的 "调试自定义标头" 部分以分析和解决自定义标头的问题

调试自定义标头

要验证自定义标头是否正确应用：

1. 启用调试日志：设置 MCP_VERY_VERBOSE=true 以查看详细的请求日志
   bash

   在您的 .env 文件或环境中

   MCP_VERY_VERBOSE=true
   MCP_LOGGING_STDOUT=true

2. 检查标头解析：出于安全考虑，自定义标头在日志中显示为掩码值：

   DEBUG 自定义标头已应用: {'X-Forwarded-User': '', 'X-ALB-Token': ''}

3. 验证特定服务的标头：检查日志以确认使用了正确的标头：

   DEBUG Jira 请求标头：已应用特定服务的标头
   DEBUG Confluence 请求标头：已应用特定服务的标头

4. 测试标头格式：确保您的标头字符串格式正确：
   bash

   正确格式

   JIRA_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2
   CONFLUENCE_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2

   错误格式（将被忽略）

   JIRA_CUSTOM_HEADERS="X-Custom=value1,X-Other=value2" # 多余的引号
   JIRA_CUSTOM_HEADERS=X-Custom: value1,X-Other: value2 # 使用冒号而不是等号
   JIRA_CUSTOM_HEADERS=X-Custom = value1 # 等号周围有空格

安全提示：包含敏感信息（如令牌、密码）的标头值在日志中会自动被掩码，以防止意外暴露。

调试工具

bash

使用 MCP Inspector 进行测试

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

对于本地开发版本

npx @modelcontextprotocol/inspector uv --directory /path/to/your/mcp-atlassian run mcp-atlassian ...

查看日志

macOS

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

Windows

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

安全性

• 永远不要共享 API 令牌
• 保持 .env 文件的安全性和私密性
• 有关最佳实践，请参阅 SECURITY.md

贡献

我们欢迎对 MCP Atlassian 的贡献！如果您希望贡献：

1. 请查阅我们的 CONTRIBUTING.md 指南，获取详细的开发设置说明。
2. 进行更改并提交拉取请求。

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

许可证

本软件根据 MIT 许可证授权 - 请参阅 LICENSE 文件。这不是 Atlassian 的官方产品。