atlassian-mcp

Atlassian MCP 专家

何时使用此技能

• 使用 JQL 筛选条件查询 Jira 工单
• 搜索或创建 Confluence 页面
• 自动化冲刺工作流和待办事项管理
• 设置 MCP 服务身份验证（OAuth/API 令牌）
• 将会议记录同步到 Jira 工单
• 根据工单数据生成文档
• 调试 Atlassian API 集成问题
• 在官方与开源 MCP 服务之间进行选择

核心工作流

1. 选择服务 - 选择官方云端、开源或可自托管的 MCP 服务
2. 身份验证 - 配置 OAuth 2.1、API 令牌或 PAT 凭据
3. 设计查询 - 为 Jira 编写 JQL，为 Confluence 编写 CQL；先使用 maxResults=1 验证，再完整执行
4. 实现工作流 - 构建工具调用、处理分页并恢复错误
5. 验证权限 - 在任何写入或批量操作前，通过只读探测确认所需权限范围
6. 部署 - 配置 IDE 集成、测试权限并监控速率限制

参考指南

根据上下文加载详细指南：

主题	参考文档	加载时机
服务设置	references/mcp-server-setup.md	安装、选择服务、配置
Jira 操作	references/jira-queries.md	JQL 语法、工单 CRUD、冲刺、看板、工单关联
Confluence 操作	references/confluence-operations.md	CQL 搜索、页面创建、空间、评论
身份验证	references/authentication-patterns.md	OAuth 2.0、API 令牌、权限范围
常见工作流	references/common-workflows.md	工单分诊、文档同步、冲刺自动化

快速入门示例

JQL 查询示例

# Open issues assigned to current user in a sprint
project = PROJ AND status = "In Progress" AND assignee = currentUser() ORDER BY priority DESC

# Unresolved bugs created in the last 7 days
project = PROJ AND issuetype = Bug AND status != Done AND created >= -7d ORDER BY created DESC

# Validate before bulk: test with maxResults=1 first
project = PROJ AND sprint in openSprints() AND status = Open ORDER BY created DESC

CQL 查询示例

# Find pages updated in a specific space recently
space = "ENG" AND type = page AND lastModified >= "2024-01-01" ORDER BY lastModified DESC

# Search page text for a keyword
space = "ENG" AND type = page AND text ~ "deployment runbook"

最简 MCP 服务配置

Atlassian Cloud：连接到托管的 Atlassian Rovo MCP Server，然后运行 /mcp 并使用 OAuth 登录。

claude mcp add --transport http atlassian https://mcp.atlassian.com/v2/mcp

Server/Data Center：使用个人访问令牌运行社区维护的 mcp-atlassian 服务（sooperset）。

{
  "mcpServers": {
    "atlassian": {
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://jira.internal.example.com",
        "JIRA_PERSONAL_TOKEN": "${JIRA_PERSONAL_TOKEN}",
        "CONFLUENCE_URL": "https://confluence.internal.example.com",
        "CONFLUENCE_PERSONAL_TOKEN": "${CONFLUENCE_PERSONAL_TOKEN}"
      }
    }
  }
}

注意： 始终从环境变量或密钥管理器加载令牌；切勿将凭据硬编码。不同服务的工具名称有所不同，请参阅 references/mcp-server-setup.md。

限制

必须做到

• 遵守用户权限和工作区访问控制
• 执行前验证 JQL/CQL 查询（先使用 maxResults=1 进行探测）
• 使用指数退避处理速率限制
• 对大型结果集使用分页（每页 50-100 项）
• 为网络故障实现错误恢复
• 记录 API 调用以便调试和审计
• 先使用只读操作进行测试
• 记录所需的权限范围
• 对生产数据执行任何写入或批量操作前进行确认

禁止事项

• 在代码中硬编码 API 令牌或 OAuth 密钥
• 忽略 Atlassian API 返回的速率限制标头
• 未验证必填字段就创建工单
• 跳过对用户提供的查询字符串进行输入清理
• 未测试权限边界就部署
• 未经确认提示就更新生产数据
• 在同一会话中混用不同的身份验证方式
• 在日志或错误消息中暴露敏感工单数据

输出模板

实现 Atlassian MCP 功能时，请提供：

1. MCP 服务配置（JSON/环境变量）
2. 查询示例（附说明的 JQL/CQL）
3. 带错误处理的工具调用实现
4. 身份验证设置说明
5. 权限要求简要说明

由 @jeffallan 维护；@jeffallan 是 Synergetic Solutions 的首席顾问。

文档