使用说明

MCP Atlassian

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

示例用法

让你的AI助手：

📝 Jira自动更新 -“从我们的会议记录中更新Jira”
🔍 AI驱动的汇流搜索 -“在Confluence中找到我们的OKR指南并对其进行总结”
🐛 智能Jira问题过滤 -“显示上周PROJ项目中的紧急错误”
📄 内容创建和管理 -“为XYZ功能创建技术设计文档”

功能演示

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

Confluence Demo

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

兼容性

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

快速入门指南

1.身份验证设置

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

A.API令牌认证（云）

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

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

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

C.OAuth 2.0身份验证（仅限云）

首选 Atlassian开发人员控制台
创建“OAuth 2.0集成”
配置必要权限 Jira/Confluence的（范围）
集 回调URL （例如。， http://localhost:8080/callback 对于安装向导）

运行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

按照提示输入您的 Client ID, Client Secret, Redirect URI 和 Scope.
在打开的浏览器窗口中完成授权
添加 ATLASSIAN_OAUTH_CLOUD_ID （从向导输出中获得）以及OAuth应用程序的 CLIENT_ID, SECRET, REDIRECT_URI，以及 SCOPE 你的 .env 文件或IDE的MCP服务器配置。请参阅 OAuth 2.0配置示例在IDE集成的“配置示例”部分。

[！重要] 包含 offline_access 在你的 ATLASSIAN_OAUTH_SCOPE 用于持久认证（例如。， read:jira-work write:jira-work offline_access).

2.安装

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

# Pull Pre-built Image
docker pull ghcr.io/sooperset/mcp-atlassian:latest

IDE集成

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

[！提示] 适用于克劳德桌面：直接查找并编辑配置文件：

视窗: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

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

配置方法

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

直接传递变量 （如下例所示）
使用环境文件 随着 --env-file 旗帜（以可折叠部分显示）

[！注意] 常见的环境变量包括：

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

JIRA_PROJECTS_FILTER：按项目键筛选（例如“PROJ、DEV、SUPPORT”）

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

MCP_VERBOSE：设置为“true”以进行更详细的日志记录

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

请参阅 .env.示例所有可用选项的文件。

配置示例

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

Alternative: Using Environment File

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

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

{
  "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_SSL_VERIFY 和 JIRA_SSL_VERIFY 仅当您拥有自签名证书时，才会显示为“false”。

OAuth 2.0 Configuration (Cloud Only)

此示例显示了如何配置 mcp-atlassian 在您的IDE（如Cursor或Claude Desktop）中使用OAuth 2.0 for Atlassian Cloud时。确保您已完成 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"
      }
    }
  }
}

[！注意]

ATLASSIAN_OAUTH_CLOUD_ID 从 --oauth-setup 向导输出。

其他 ATLASSIAN_OAUTH_* 变量是您在Atlassian开发人员控制台中为OAuth应用程序配置的变量（并用作设置向导的输入）。

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

Proxy Configuration

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

支持标准 HTTP_PROXY, HTTPS_PROXY, NO_PROXY, SOCKS_PROXY.
服务特定的覆盖是可用的（例如。， JIRA_HTTPS_PROXY, CONFLUENCE_NO_PROXY).
特定于服务的变量会覆盖该服务的全局变量。

将相关代理变量添加到 args （使用 -e)以及 env MCP配置的各个部分：

{
  "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，对匹配主机的请求将得到尊重。

Single Service Configurations

仅适用于Confluence Cloud：

{
  "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服务器/DC，使用：

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

{
  "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服务器/DC，使用：

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

SSE传输配置

Using SSE Instead of stdio

在终端中手动启动服务器：

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

配置IDE以通过其URL连接到正在运行的服务器：

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

工具

关键工具

Jira工具

jira_get_issue：获取特定问题的详细信息
jira_search：使用JQL搜索问题
jira_create_issue：创建新问题
jira_update_issue：更新现有问题
jira_transition_issue：将问题转变为新的状态
jira_add_comment：向问题添加评论

汇流工具

confluence_search：使用CQL搜索Confluence内容
confluence_get_page：获取特定页面的内容
confluence_create_page：创建新页面
confluence_update_page：更新现有页面

View All Tools

操作	Jira工具	汇流工具
阅读	`jira_search`	`confluence_search`
	`jira_get_issue`	`confluence_get_page`
	`jira_get_project_issues`	`confluence_get_page_children`
	`jira_get_worklog`	`confluence_get_comments`
	`jira_get_transitions`	`confluence_get_labels`
	`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_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`
	`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 Cloud上可用

工具过滤和访问控制

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

工具筛选：使用 --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" ...

读/写控制：工具分为读取或写入操作。当 READ_ONLY_MODE 启用后，无论是否启用，只有读取操作可用 ENABLED_TOOLS 设置。

故障排除与调试

常见问题

身份验证失败:
- 对于云：检查您的API令牌（而不是您的帐户密码）
- 对于服务器/数据中心：验证您的个人访问令牌是否有效且未过期
- 对于较旧的Confluence服务器：一些较旧的版本需要基本的身份验证 CONFLUENCE_USERNAME 和 CONFLUENCE_API_TOKEN （其中token是您的密码）
SSL证书问题：如果使用服务器/数据中心时遇到SSL错误，请设置 CONFLUENCE_SSL_VERIFY=false 或 JIRA_SSL_VERIFY=false
权限错误：确保您的Atlassian帐户有足够的权限访问空间/项目

调试工具

# Using MCP Inspector for testing
npx @modelcontextprotocol/inspector uvx mcp-atlassian ...

# For local development version
npx @modelcontextprotocol/inspector uv --directory /path/to/your/mcp-atlassian run mcp-atlassian ...

# View logs
# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
# Windows
type %APPDATA%\Claude\logs\mcp*.log | more

安全

永远不要共享API令牌
确保.env文件的安全性和私密性
看安全.md 最佳实践

贡献

我们欢迎为MCP Atlassian做出贡献！如果你想贡献：

查看我们的贡献.md 详细的开发设置说明指南。
进行更改并提交拉取请求。

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

许可证

麻省理工学院授权-见许可证文件。这不是Atlassian的官方产品。