jira-mini-mcp

jira-mini-mcp

面向编码 Agent 的 Jira Cloud MCP 服务：只读模式提供 6 个工具，启用写入后提供 9 个。

一项任务。一个工具。做好它。

通用 Atlassian MCP 服务会暴露数十到数百个工具。每个工具都会在 Agent 开始执行任何有用工作前占用上下文，而每个功能近似重复的工具都会让 Agent 更难做出选择。此服务为编码 Agent 提供处理工单所需的 Jira 上下文、三种回复方式，仅此而已。

• 提供 6-9 个工具，而不是 98 个——每个工具都值得占用上下文，且工具描述经过测试，确保 Agent 能选对工具；请参阅为何工具如此之少，以及与其他方案的比较。
• 写入操作严格限定为三个工具——评论、转换状态、更新。设置 READ_ONLY_MODE=true 后，这些工具不会注册，甚至不会作为禁用条目显示给 Agent。
• 输出精简且可预测——稳定的 JSON 架构，丰富文本使用 Markdown，不会充斥 null，也不包含 self URL、电子邮件或头像；请参阅工具返回的内容。
• 传输数据量约减少 40%——每个结果只发送一次，以 JSON 形式放在 content 中，而不是再次作为 structuredContent 发送；如果宿主需要类型化副本，可设置 STRUCTURED_OUTPUT=true。请参阅更省的输出。
• 不会悄悄截断内容——评论和变更日志会返回精确总数，搜索支持游标分页，并可通过 limit=0 获取剩余内容。请求失败会返回错误，而不是空列表。
• Agent 可据此采取行动的错误——如果转换状态名称不正确，错误会列出所有有效状态及其去向，因此无需单独的发现工具。错误中绝不会包含你的 Jira URL、凭据或原始响应正文。
• 支持 API token 或 OAuth——使用 API token 只需一分钟即可完成配置；也可以通过你自己的 OAuth 2.0 应用登录浏览器，并自动刷新令牌；请参阅配置。
• 已发布到 PyPI——使用 uvx jira-mini-mcp 或 pip install jira-mini-mcp，无需克隆仓库或使用 git URL。

提示

设置 READ_ONLY_MODE=true 后，只会注册六个 🟢 只读工具—— 三个 🔴 写入工具会被完全禁用，参见配置。

• 安装
• 配置
• 向 Jira 写入数据
• 为何工具这么少
• 与其他方案的比较
• 贡献与安全

更多详情请参阅 docs/：配置、 OAuth 设置，以及工具的返回内容和 示例。

安装

uvx jira-mini-mcp

或

pip install jira-mini-mcp

如需固定功能集，可锁定版本：uvx jira-mini-mcp==1.1.0。

也可以直接从 GitHub 运行尚未发布的提交：

uvx --from git+https://github.com/proprock/jira-mini-mcp jira-mini-mcp

需要 Python 3.12+ 和 uv（或 pip）。

配置

使用 API 令牌时，需要设置以下三个值：

添加 READ_ONLY_MODE=true 以禁用写入工具。所有设置（包括 STRUCTURED_OUTPUT）都列在configuration.md中。

说明

更倾向于使用 OAuth 而非存储令牌？ 设置 JIRA_AUTH_METHOD=oauth，注册一个 免费的 OAuth 2.0 (3LO) 应用，然后运行一次 jira-mini-mcp login，在浏览器中完成授权。 之后，服务会自动刷新令牌。分步说明： oauth.md。

启动时会验证配置；如果设置缺失，错误信息会指出缺少哪项，但不会打印其值或你的 Jira URL。将令牌保存在宿主自己的 配置中，切勿提交令牌。服务会使用你账户的权限：如果账户无法转换某个问题状态，那么无论此服务开放什么功能， 账户仍然无法转换该状态。

claude mcp add --env JIRA_BASE_URL=https://example.atlassian.net --env [email protected] --env JIRA_API_TOKEN=your-token --transport stdio jira-mini -- uvx jira-mini-mcp

{
  "mcpServers": {
    "jira-mini": {
      "command": "uvx",
      "args": ["jira-mini-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://example.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your-token"
      }
    }
  }
}

codex mcp add jira-mini --env JIRA_BASE_URL=https://example.atlassian.net --env [email protected] --env JIRA_API_TOKEN=your-token -- uvx jira-mini-mcp

提供 3 个工具，让 Agent 能为处理过的工单完成闭环：

add_comment(issue_key, body)
transition_issue(issue_key, to, comment=None)
update_issue(issue_key, fields)

工单创建、链接、附件上传、工作日志和删除均不在范围内。创建工单需要按项目和类型发现必填字段，本身就是一项独立功能；相关链接，或对链接的请求，放在评论中即可。

Agent 写入前，有 3 点值得了解：

• transition_issue 接受名称，而非 ID。 可以是转换名称，也可以是要到达的状态名称，匹配时不区分大小写。在实际工作流中，两者可能不同——名为 In Progress 的转换可能会产生名为 In Development 的状态，而名称不同的两个转换也可能到达同一状态——因此优先使用转换名称。若没有匹配项，错误信息会列出所有可用转换及其目标状态。要先查看选项，可请求 get_issue(fields=["transitions"])。因此不需要单独的 get_transitions 工具。
• update_issue 会整体替换 labels 和 components。 没有添加或移除操作，因此如果要添加一个值，请先读取工单。它接受与 get_issue 返回值相同的值：assignee 可以是账户 ID、电子邮件地址、显示名称或字面值 "me"；description 为 Markdown；customfield_* 为原始 Jira JSON。它会拒绝 status 和 comment，并指出负责处理它们的工具。
• Markdown 会被转换，而非靠猜测处理。 标题、列表、围栏代码、行内标记和链接会转换为 Jira 富文本；该范围之外的内容会保持原样，而不会被重新解释。

每个写入工具都标注了 readOnlyHint=false，并如实设置 destructiveHint 和 idempotentHint 的值；READ_ONLY_MODE 会根据这些值进行过滤。

为什么工具这么少

工具定义包含名称、描述、输入架构，以及通常还会有输出约定。根据客户端的不同，在开始任何工作之前，这些内容都可能进入模型的上下文。因此，大型工具集会耗费上下文来描述当前任务用不到的功能，也会增加选错工具、混淆相似工具或传入错误参数的概率。

紧凑的 6 到 9 个架构在整个会话中都能保持成本可控，为源代码、工单描述、堆栈跟踪和推理留出上下文预算。这一设计遵循 Anthropic 针对 Agent 系统的指导：工具集应精简、按角色划分，并明确区分。

这是一项主张，因此仓库会对其进行测试。离线测试与测试套件一同运行，并检查每个工具是否都有实质性描述、是否有描述近乎重复的工具，以及是否在文字中解释了所有无法仅凭名称推断行为的参数。另一部分会将真实工具定义提供给真实模型，并评估模型选择了哪个工具——参见 evals/README.md。

同一原则也影响响应内容。get_issue 不会一次性输出数百条评论、完整变更日志、附件内容或所有自定义字段；只有在提出请求时才会获取大型资源。

与其他方案的比较

需要覆盖多个 Atlassian 产品、无需注册自己的应用即可使用 OAuth、Jira Service Management，或权限组、IP 允许列表和审计日志等组织级控制时，官方服务是更好的选择。 这是 Atlassian 自己的产品，会跟进其 API，而这里的方案并不与之竞争。

需要在 Jira 之外使用 Confluence、支持 Server/Data Center，或只需比 6 到 9 个工具更全面的 Jira 覆盖时，mcp-atlassian 是更好的选择。

在一种特定情况下，本服务是更好的选择：编码 Agent 处理 Jira 工单时，每个工具定义消耗的上下文成本，比它所带来的覆盖范围更重要。

贡献与安全

有关设置、检查、测试和评估命令、分支与提交约定以及发布模式的信息，请参阅 CONTRIBUTING.md。请按照 SECURITY.md 中的说明私下报告漏洞。影响服务运行者的变更会记录在 CHANGELOG.md 中。

许可证

MIT。这不是 Atlassian 官方产品。