Jira Weekly Reporter MCP Server

Jira 每周报告 MCP 服务

此项目提供一个 FastMCP 服务，可连接到你的 Jira 实例（Cloud 或 Server/Data Center），根据问题活动生成每周报告。它使用 pycontribs-jira 库与 Jira 交互，还可以选择使用已连接客户端的大模型来总结生成的报告。

✨ 功能

• 连接 Jira： 使用存储在 .env 文件中的 API 令牌安全地连接到 Jira。
• MCP 工具： 提供可通过模型上下文协议访问的 generate_jira_report 工具。
• 灵活的报告：
  • 默认报告过去 7 天内更新的问题。
  • 允许指定自定义 JQL 查询。
  • 可以按特定 Jira 项目键筛选报告。
  • 限制返回结果的数量（可配置）。
• （可选）大模型总结： 可以使用客户端的大模型（通过 ctx.sample()）简要总结报告。
• 异步处理： 通过 asyncio.to_thread，在异步 FastMCP 服务中正确处理同步 Jira 库调用。

📋 前提条件

• Python 3.10 或更高版本。
• uv（推荐）或用于包管理的 pip。
• 可访问 Jira 实例（Cloud、Server 或 Data Center）。
• Jira API 令牌（Server/DC 使用个人访问令牌）。
• 已安装并可在系统 PATH 中使用的 FastMCP CLI。

⚙️ 设置

1. 克隆仓库（如适用）：

   git clone https://github.com/Jongryong/jira_reporter.git
   cd jira_reporter
   

2. 安装依赖项： 建议使用 uv：

   uv pip install fastmcp "jira[cli]" python-dotenv httpx anyio
   

   也可以使用 pip：

   pip install fastmcp "jira[cli]" python-dotenv httpx anyio
   

3. 创建 .env 文件： 在与 jira_reporter_server.py 相同的目录中创建名为 .env 的文件。添加 Jira 连接信息：

   # .env
   JIRA_URL=https://your-domain.atlassian.net  # Your Jira Cloud URL or Self-Hosted URL
   [email protected]       # Your Jira login email
   JIRA_API_TOKEN=your_api_token_or_pat       # Your generated API Token or PAT
   

   • 安全：
     • 切勿将 .env 文件提交到版本控制中！ 将 .env 添加到 .gitignore 文件中。
     • Jira Cloud： 在 Atlassian 帐户设置中生成 API 令牌：管理 API 令牌。
     • Jira Server/Data Center： 在 Jira 用户个人资料设置中生成个人访问令牌（PAT）：使用个人访问令牌。

▶️ 运行服务（独立运行）

你可以独立运行此服务，以进行测试或用于其他目的：

1. 直接使用 Python：

   python jira_reporter_server.py
   

2. 使用 FastMCP CLI：

   fastmcp run jira_reporter_server.py
   

   使用 SSE 运行（例如，用于远程访问）：

   fastmcp run jira_reporter_server.py --transport sse --port 8001
   

🖥️ 在 Claude Desktop 中使用

若要在 Claude Desktop 应用程序中将此服务作为工具使用：

1. **确认前置条件：**确保已安装 fastmcp，且可通过系统 PATH 访问，因为以下配置使用了 fastmcp 命令。

2. **找到 Claude 配置文件：**找到 claude_desktop_config.json 文件。其位置取决于你的操作系统：

   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows： %APPDATA%\Claude\claude_desktop_config.json（通常为 C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json）
   • Linux： ~/.config/Claude/claude_desktop_config.json（或 $XDG_CONFIG_HOME/Claude/）

3. **编辑配置文件：**在文本编辑器中打开 claude_desktop_config.json。

4. 添加服务配置：在 JSON 中找到 "mcpServers" 对象（如果不存在，则创建一个空对象 {}）。在 mcpServers 中添加以下条目，并将 "path/to/your/jira_reporter_server.py" 替换为脚本的绝对路径：

   {
     "mcpServers": {
       // ... 这里可能有其他服务 ...
   
       "jira_report": {
         "command": "fastmcp",
         "args": [
           "run",
           "/path/to/your/jira_reporter_server.py" // <-- IMPORTANT: Use the full, absolute path here
         ]
       }
   
       // ... 这里可能有其他服务 ...
     }
     // ... 其余 Claude 配置 ...
   }
   

   • "jira_report"：这是 Claude 使用的内部名称。如有需要，可以更改。
   • "command": "fastmcp"：告知 Claude 使用 fastmcp 命令行工具。
   • "args": [...]：告知 Claude 运行 fastmcp run /path/to/your/jira_reporter_server.py。

5. **保存并重启：**保存 claude_desktop_config.json 文件，然后重启 Claude Desktop 应用程序。

6. **调用工具：**现在，你可以在 Claude 中通过提及 Python 脚本中定义的服务名称（Jira Weekly Reporter）来使用此工具。例如： @Jira Weekly Reporter generate jira report for project MYPROJ and summarize it

🛠️ MCP 工具详情

• 工具名称：generate_jira_report
• **描述：**根据 JQL 查询（默认为最近更新的事项）生成 Jira 事项报告。还可以选择使用客户端的大模型对报告进行摘要。

参数：

参数	类型	必填	默认值	描述
jql_query	string	否	updated >= -7d ORDER BY updated DESC	可选的 JQL 查询。如果省略，则使用默认值。
project_key	string	否	None	可选的 Jira 项目键（例如，“PROJ”），用于限制搜索范围（添加为 project = 'KEY' AND ...）。
max_results	integer	否	50	原始报告数据中包含的事项数量上限。
summarize	boolean	否	false	如果为 true，服务将通过 ctx.sample() 请求客户端的大模型生成摘要。

📦 服务依赖项

FastMCP 构造函数包含 dependencies=["jira"]。这会告知 fastmcp install 等工具，在创建隔离环境时，该服务需要 jira 库才能正常运行。

🤝 贡献

欢迎贡献！欢迎提交问题或拉取请求。

📄 许可证

MIT 许可证