## 使用说明 ### 项目简介该项目是一个基于 Model Context Protocol (MCP) 协议实现的服务器，旨在作为 AI 助手与 Atlassian Jira 之间的桥梁。通过此服务器，AI 助手可以安全、实时地访问和操作您的 Jira 云实例中的项目、事务等资源，从而更好地理解您的工作上下文，并辅助您完成 Jira 相关任务。 ### 主要功能点 - **Jira 数据访问**: 提供对 Jira 项目、事务、评论等资源的标准化访问接口，使 AI 助手能够获取 Jira 中的上下文信息。 - **Jira 工具集成**: 内置一系列用于操作 Jira 的 MCP 工具，允许 AI 助手调用这些工具来执行 Jira 相关操作，例如： - `list_projects`: 列出用户可访问的 Jira 项目。 - `get_project`: 获取指定 Jira 项目的详细信息。 - `list_issues`: 根据 JQL 查询列出 Jira 事务。 - `get_issue`: 获取指定 Jira 事务的详细信息。 - `search`: 使用 JQL 查询在 Jira 中进行高级搜索。 - **安全本地认证**: 用户的 Jira API Token 等凭据仅在本地配置和使用，不会被服务器存储，保障数据安全。 - **Markdown 格式响应**: 服务器返回的所有数据都以易于阅读的 Markdown 格式呈现，方便 AI 助手理解和展示。 ### 安装步骤 1. **安装 Node.js**: 确保您的系统已安装 Node.js (>= 18.x)。您可以从 [Node.js 官网](https://nodejs.org/) 下载并安装。 2. **获取 Jira API Token**: - 访问 [Atlassian API Token 管理页面](https://id.atlassian.com/manage-profile/security/api-tokens)。 - 点击 "Create API token" (创建 API 令牌)。 - 输入令牌的 "Label" (标签)，例如 `mcp-jira-access`。 - 点击 "Create" (创建) 并 **立即复制生成的 API 令牌**，因为之后将无法再次查看。 3. **配置 Jira 凭据**: 您可以通过以下两种方法配置 Jira 连接凭据： - **方法 A (推荐): MCP 配置文件** - 创建或编辑 `~/.mcp/configs.json` 文件 (如果 `.mcp` 目录不存在，请先创建)。 - 在 `configs.json` 文件中添加以下 JSON 配置，替换 ``、`` 和 `` 为您的 Jira 站点名称、Atlassian 账户邮箱和 API 令牌。 ```json { "@aashari/mcp-server-atlassian-jira": { "environments": { "ATLASSIAN_SITE_NAME": "", "ATLASSIAN_USER_EMAIL": "", "ATLASSIAN_API_TOKEN": "" } } } ``` - ``: 您的 Jira 站点名称 (例如，如果您的 Jira 地址是 `mycompany.atlassian.net`，则站点名称为 `mycompany`)。 - ``: 您的 Atlassian 账户邮箱地址。 - ``: 步骤 2 中复制的 API 令牌。 - **方法 B: 环境变量** - 您可以在运行服务器命令时直接通过环境变量传递凭据，例如： ```bash ATLASSIAN_SITE_NAME="" \ ATLASSIAN_USER_EMAIL="" \ ATLASSIAN_API_TOKEN="" \ npx -y @aashari/mcp-server-atlassian-jira ``` 4. **配置 MCP 客户端**: 在您的 MCP 客户端 (例如 Claude 或 Cursor) 中，配置启动此 MCP 服务器。以下是一个 Claude / Cursor 的配置示例，您需要将此 JSON 配置添加到您的客户端配置中。 ```json { "mcpServers": { "aashari/mcp-server-atlassian-jira": { "command": "npx", "args": ["-y", "@aashari/mcp-server-atlassian-jira"] } } } ``` - `server name`: `aashari/mcp-server-atlassian-jira` (服务器名称，可以自定义，用于在客户端中标识) - `command`: `npx` (命令，用于执行 Node.js 包) - `args`: `["-y", "@aashari/mcp-server-atlassian-jira"]` (命令参数，`-y` 表示自动确认安装，`@aashari/mcp-server-atlassian-jira` 是要执行的 npm 包名) **注意:** 请确保您已在 **步骤 3: 配置 Jira 凭据** 中正确配置了 `ATLASSIAN_SITE_NAME`, `ATLASSIAN_USER_EMAIL`, 和 `ATLASSIAN_API_TOKEN`，否则服务器将无法连接到 Jira。 ### 基本使用方法完成配置后，您的 AI 助手即可通过 MCP 协议与 Jira 服务器进行交互。以下是一些基本工具的使用示例： - **列出所有 Jira 项目**: 使用 `list_projects` 工具，无需任何参数即可列出您在 Jira 中可访问的所有项目。 ```json {} ``` 在 AI 助手中，您可以这样提问： "列出我所有的 Jira 项目"。 - **获取指定 Jira 项目的详细信息**: 使用 `get_project` 工具，并提供 `projectKeyOrId` 参数 (项目 Key 或 ID) 来获取特定项目的详细信息。 ```json { "projectKeyOrId": "DEV" } ``` 在 AI 助手中，您可以这样提问： "告诉我 Jira 中 DEV 项目的详细信息"。 - **使用 JQL 搜索 Jira 事务**: 使用 `search` 工具，通过 `jql` 参数 (Jira Query Language 查询语句) 进行高级搜索。 ```json { "jql": "text ~ 'login issue'" } ``` 在 AI 助手中，您可以这样提问： "在 Jira 中搜索包含 'login issue' 文本的事务"。更多工具的详细信息和参数说明，请参考仓库 README.md 文件中的 [Tools](https://github.com/aashari/mcp-server-atlassian-jira#tools) 章节。

"事务跟踪" 标签

Jira MCP 服务器

Linear