mcp-atlassian

你是否在一家使用Confluence和Jira的公司工作？每天你需要去Confluence查找文档，去Jira查看任务状态，在不同的系统之间切换，有时候甚至要打开几十个标签页。如果能让AI助手直接帮你搜索文档、汇总任务状态，甚至根据Jira工单的内容生成报告，那会节省很多时间。

现在有一个工具可以实现这个想法。mcp-atlassian是一个MCP服务器，它连接了Atlassian的两大核心产品：Confluence（知识管理）和Jira（项目管理）。配置好之后，你可以在AI助手中直接用自然语言查询，比如“找出我这周分配的所有未完成Jira工单”，或者“搜索主题包含‘API设计’的Confluence页面”。AI会自动调用Atlassian的API，把结果呈现在你面前。

项目基本信息

一、项目介绍

mcp-atlassian是一个基于Node.js的MCP服务器，它为Atlassian产品提供了标准化的访问接口。通过这个服务器，AI可以连接到你的Confluence和Jira实例，执行搜索、检索内容等操作。这对于集成内部知识库和项目管理工具来说，是一个很实用的解决方案。

这个服务器提供了两个核心工具：

confluence_search（Confluence搜索工具）

这个工具让你能够使用CQL（Confluence Query Language）来搜索Confluence中的内容。CQL是Confluence自己的查询语言，类似于SQL，但专门用于搜索页面、附件、评论等。你可以指定空间（space）、内容类型、创建日期等条件。支持限制返回结果的数量（默认为10，最大50）。这对于在庞大的公司知识库中快速找到相关信息很有帮助。

jira_search（Jira搜索工具）

这个工具使用JQL（Jira Query Language）来搜索Jira工单（issues）。JQL是Jira的查询语言，功能强大，支持按项目、状态、分配人、优先级、创建时间等多种条件过滤。你可以指定要返回的字段（比如summary、status、assignee），以及结果数量（默认为10，最大50）。

这个服务器还定义了两个资源模板（Resource Templates），遵循MCP的资源协议：

• confluence://{space_key}/pages/{title}：用于访问特定Confluence空间中的特定标题页面。
• jira://{project_key}/issues/{issue_key}：用于访问特定Jira项目中的特定工单。

不过，根据最新的提交记录，项目似乎正在简化，移除了部分Jira功能（从提交信息“Refaktor: Odstranění funkcionality pro Jira”可以看出）。在配置时，你可能需要根据自己的实际需求来决定启用哪些模块。

二、核心优势

与公司内部工具的深度集成

这是mcp-atlassian最核心的价值。它不是通用的互联网搜索，而是专门针对你公司的Confluence和Jira实例。这意味着AI可以访问你内部的、可能敏感的、非公开的信息。这对于提高内部工作效率来说，意义很大。

使用标准的查询语言

CQL和JQL是Atlassian生态中的标准查询语言。如果你已经熟悉它们，可以直接写出复杂的查询条件。即使不熟悉，AI也可以帮助你生成这些查询。这种标准化的接口确保了查询的精确性和灵活性。

资源模板支持

通过资源模板，AI可以以统一的方式访问特定的Confluence页面或Jira工单。这符合MCP协议的设计理念，让AI能够像访问本地文件一样访问Atlassian中的资源。

多种安装方式

项目支持通过Smithery一键安装到Claude Desktop，也支持手动克隆、构建和配置。这为不同技术背景的用户提供了选择。

轻量级实现

项目代码量不大，依赖简单，因此响应速度快，资源占用低。对于只需要基本搜索和检索功能的场景来说，这是一个务实的选择。

支持自托管Atlassian实例

虽然示例中使用的是Atlassian Cloud的URL格式（your-domain.atlassian.net），但理论上，通过配置CONFLUENCE_URL和JIRA_URL环境变量，它也可以连接到自托管的Confluence和Jira实例。

三、适用场景

项目状态快速查询

项目经理或开发者可以快速问AI：“显示我这周分配的所有未关闭的Jira工单，按优先级排序。” AI会生成相应的JQL查询，调用jira_search工具，并返回格式化的结果。

知识库的智能检索

当需要查找某个技术方案的文档时，你可以问：“在Confluence的‘Engineering’空间中，搜索主题包含‘microservices’的页面，只显示最近一个月更新的。” AI会用CQL构建查询，返回相关页面的列表和摘要。

日常工作总结

在写日报或周报时，你可以让AI：“找出我昨天解决的所有Jira工单，并列出它们的标题和链接。” 或者 “找出Confluence中我最新创建或编辑的页面。” 这可以节省手动整理的时间。

新员工入职辅助

新人可以问AI：“帮我找到关于‘开发环境搭建’的所有Confluence页面。” 或者 “列出本月分配给新员工的所有培训相关Jira任务。” AI可以快速检索相关知识，帮助他们更快融入团队。

会议准备

在参加项目会议之前，你可以让AI：“检索与‘v2.0发布’相关的所有Jira工单，按状态分组，并找出Confluence中关于该版本的发布计划页面。” 这样你就可以在会前全面了解情况。

交叉系统信息关联

有些信息可能分散在两个系统中。例如，你可以在一个查询中让AI：“找出Confluence中关于‘认证服务’的设计文档，然后找出该文档中提到的Jira工单的实现状态。” 虽然目前工具是分开的，但AI可以组合使用两个工具的结果。

四、安装教程

前置准备

在使用之前，你需要满足以下条件：

• 一个Atlassian Cloud账户（或者能访问自托管的Confluence/Jira实例）。
• Confluence和/或Jira的API令牌。你可以在Atlassian账户管理中找到“API令牌”选项来生成。
• Node.js环境（版本14或更高）。

获取Atlassian API令牌

Atlassian Cloud API使用基本认证（用户名+API令牌）。你需要：

1. 登录到 https://id.atlassian.com/manage-profile/security/api-tokens 。
2. 点击“创建API令牌”。
3. 给你的令牌起一个名字（例如“MCP-Server”），然后点击“创建”。
4. 复制生成的令牌字符串。注意： 这个令牌只会显示一次，请妥善保管。

安装方式一：通过Smithery一键安装（推荐Claude Desktop用户）

如果你使用Claude Desktop，这是最简单的方式。在终端中运行：

npx -y @smithery/cli install @petrsovadina/mcp-atlassian --client claude

这个命令会处理安装和配置的大部分步骤。你可能仍然需要手动在配置文件中添加环境变量（API令牌、URL等），具体取决于Smithery的实现。请检查生成的配置文件。

安装方式二：手动安装

第一步，克隆项目到本地：

git clone https://github.com/petrsovadina/mcp-atlassian.git
cd mcp-atlassian

第二步，安装依赖：

npm install

第三步，构建项目：

npm run build

配置MCP客户端

找到你的MCP客户端配置文件。以Claude Desktop为例，配置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

用文本编辑器打开，添加以下配置。请务必将占位符替换为你自己的信息。

{
  "mcpServers": {
    "atlassian": {
      "command": "node",
      "args": ["/绝对路径/to/mcp-atlassian/build/index.js"],
      "env": {
        "CONFLUENCE_URL": "https://你的域名.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "你的邮箱@公司.com",
        "CONFLUENCE_API_TOKEN": "你的API令牌",
        "JIRA_URL": "https://你的域名.atlassian.net",
        "JIRA_USERNAME": "你的邮箱@公司.com",
        "JIRA_API_TOKEN": "你的API令牌"
      }
    }
  }
}

注意：

• /绝对路径/to/ 需要替换为项目所在的实际路径。例如 /Users/yourname/Documents/mcp-atlassian/build/index.js。
• 如果你只需要Confluence或只需要Jira，可以只配置对应的那部分环境变量。但从实现看，两个产品的认证是分开配置的。
• 如果你使用的是自托管的Atlassian实例，将URL替换为你的内部地址。

保存文件后，完全退出并重启你的AI客户端（如Claude Desktop）。

验证安装

重启后，在AI助手中输入：

“Use the Atlassian MCP to search for 'test' in my Confluence.”

如果配置成功，AI应该会调用confluence_search工具。由于你的实例中可能没有“test”页面，它可能会返回空结果，但不会报错。你也可以尝试一个更可预测的查询：“Search for Jira issues assigned to me.”

五、使用示例

配置完成后，你可以在AI助手中用自然语言来查询Atlassian数据。以下是一些典型的用法。

示例一：Confluence基础搜索

你可以直接使用自然语言，AI会帮你转换成CQL。

“Search Confluence for pages that contain the word 'API' in the 'Engineering' space. Show me the top 5 results.”

AI会调用confluence_search，构造一个类似type=page AND space='Engineering' AND text~'API'的查询，并返回结果列表。

示例二：使用CQL进行高级搜索

如果你熟悉CQL，可以更精确地指定查询。

“Use confluence_search with the query 'type=page AND created > '2025-01-01' ORDER BY created DESC', limit 3.”

这会让AI直接执行这个CQL，返回今年创建的最新的3个页面。

示例三：Jira基础搜索

“Show me all open Jira issues in project 'MOBILE', assigned to me.”

AI会调用jira_search，生成JQL：project = MOBILE AND status = Open AND assignee = currentUser()。然后返回工单的摘要、状态等信息。

示例四：带字段筛选的Jira搜索

为了控制返回的内容量，你可以指定需要的字段。

“Search Jira with jql 'project = BACKEND AND status in (Open, 'In Progress')', and only return the fields 'summary', 'assignee', and 'priority'.”

AI会只请求你指定的字段，这可以帮助节省上下文token。

示例五：组合使用两个工具进行“关联分析”

假设你有一个Convention规定，每个设计文档对应的实现Jira工单号会写在文档里。你可以让AI：

“First, find the Confluence page titled 'User Authentication Design' in the 'ARCH' space. Then, look for an issue key mentioned in that page, and use jira_search to get the status of that issue.”

AI会先调用confluence_search找到页面，读取内容，提取出工单号，然后调用jira_search查询该工单的状态。

示例六：使用资源模板（如果客户端支持）

如果MCP客户端支持资源发现，AI可以直接访问资源URI。例如：

“Access the resource confluence://ENG/pages/My Project Overview and summarize the content.”

AI会通过MCP的资源协议来获取内容。

六、常见问题

认证失败（401 Unauthorized）

这是最常见的问题。请确保：

• USERNAME 使用的是你的电子邮件地址，而不是用户昵称。
• API_TOKEN 是从Atlassian账户安全页面生成的有效令牌，而不是你的登录密码。
• 对于自托管实例，你可能需要创建Personal Access Token (PAT)而不是Cloud API Token。

搜索没有返回任何结果

可能的原因：

• CQL或JQL语法错误。可以先在Confluence或Jira的高级搜索中验证你的查询。
• 搜索范围不正确。检查你是否指定了正确的空间（space）或项目（project）。对于Confluence，如果不指定空间，它会搜索所有你有权限访问的空间。
• 权限问题。确保你的API令牌关联的账户有权限访问你要搜索的内容。

连接错误或超时

• 检查CONFLUENCE_URL和JIRA_URL配置是否正确。对于Cloud版本，Confluence的URL以/wiki结尾，Jira的URL不加/wiki。
• 确认你的网络可以访问Atlassian服务（atlassian.net域名）。如果你在公司网络内，可能需要配置HTTP代理。
• 对于自托管实例，确保提供的URL是服务器可访问的。

项目构建失败

• 确保Node.js版本足够新（建议16+）。
• 删除node_modules和package-lock.json，重新运行npm install。
• 检查是否有TypeScript错误。虽然项目大部分是JavaScript，但使用了TypeScript编译器来构建。

工具调用成功但AI不理解返回结果

返回的数据结构可能很复杂（包含作者、时间戳、内容片段等）。AI通常能理解，但你可以明确要求它：“Format the search results as a simple list with title, last updated, and a link.”。AI会基于返回的数据进行格式化。

我只想使用Confluence或只使用Jira

你可以在环境变量中只配置对应的那一部分。但是请注意，根据代码提交记录，项目正在进行重构，未来的版本可能会将两者拆分为独立的服务器。

七、总结

mcp-atlassian是一个非常具体的工具，专注于解决一个明确的问题：让AI能访问公司内部的Confluence和Jira数据。对于那些严重依赖Atlassian产品的团队来说，这个工具可以将AI无缝地集成到日常工作流中。

项目目前还比较新（只有2个star），代码量不大，功能也相对基础（主要是搜索）。但它的潜力很明显。想象一下，结合了内部知识和AI的理解能力，你可以做很多事情：自动化的文档助手、智能的工单分拣、基于历史数据的需求预测等等。

我比较欣赏的是项目使用了标准的CQL和JQL。这意味着任何熟悉Atlassian产品的人都可以直接上手编写复杂查询，而且AI也可以学习和生成这些查询。资源模板的设计也符合MCP的最佳实践。

当然，这个项目还有一些地方可以改进。目前的版本似乎正在进行重构，可能会移除部分Jira功能（根据提交信息）。另外，目前只支持搜索，还不支持创建、更新工单或页面。这些写入操作会大大扩展它的应用场景。安全方面也需要特别注意，毕竟API令牌给予了很大的访问权限。

如果你所在的公司使用Atlassian产品，并且你希望让AI助手能够利用内部的知识库和项目数据，mcp-atlassian是一个值得关注的项目。虽然它还不够完善，但提供了一个很好的起点。