jira-admin-mcp

Jira Admin MCP 服务

一个 Model Context Protocol 服务，可为 AI 助手（Claude、Cursor、VS Code 或任何 MCP 客户端）提供 78 个专用工具，用于管理 Jira Cloud 站点——不仅可以读取和创建工单，还能处理幕后管理工作：自定义字段及其显示位置、权限方案、工作流、屏幕、问题类型方案、群组、项目角色、已保存的筛选器以及批量操作。

大多数 Jira MCP 服务都涵盖日常使用场景。这个服务专注于管理工作，并加入了安全保障措施（试运行模式、共享方案检测、修改群组前进行身份检查、提供可操作的错误信息），让 Agent 能够端到端地执行实际管理任务。

基于 FastMCP 构建。使用你自己的 Atlassian 邮箱和 API 令牌调用 Jira Cloud REST API v3。

---

快速开始

需要满足两个前提条件，均只需设置一次，而且很快就能完成：

1. 一个 Atlassian API 令牌（它继承你的 Jira 权限，因此请使用具备所需访问权限的账户）：在此创建。
2. 已安装 uv（一行命令即可；它会为你管理 Python 和依赖项，无需虚拟环境）。

然后，使用一键按钮或适用于你的工具的一行命令添加此服务，并填写三个 JIRA_* 值。

Cursor

点击按钮，在 Cursor 中确认，然后打开 ~/.cursor/mcp.json（或 Cursor Settings -> MCP），并在 jira-admin 条目中设置 JIRA_BASE_URL、JIRA_EMAIL 和 JIRA_API_TOKEN。

Claude Code

一条命令（替换为你自己的三个值）：

claude mcp add --scope user \
  --env JIRA_BASE_URL=https://your-company.atlassian.net \
  --env [email protected] \
  --env JIRA_API_TOKEN=your_api_token_here \
  --transport stdio jira-admin \
  -- uvx jira-admin-mcp

--scope user 会让它在每个项目中都可用；移除该参数即可仅添加到当前项目。使用 claude mcp list 检查。

VS Code

安装后，在 .vscode/mcp.json（或你的用户级 mcp.json）中的 jira-admin 条目里设置 JIRA_* 值。

其他 MCP 客户端（手动）

将此代码块添加到客户端的 MCP 配置中：

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

想使用尚未发布的 main，而不是 PyPI 版本？将 "args": ["jira-admin-mcp"] 替换为 "args": ["--from", "git+https://github.com/its-qusai-nasr/jira-admin-mcp", "jira-mcp"]。

配置文件位置：Claude Desktop claude_desktop_config.json（macOS ~/Library/Application Support/Claude/，Windows %APPDATA%\Claude\）；Cursor ~/.cursor/mcp.json；VS Code .vscode/mcp.json（注意：VS Code 使用顶层 "servers" 键，而不是 "mcpServers"）。编辑后重启客户端；服务将显示为 jira-admin，并提供全部 78 个工具。

本地克隆（用于开发）

git clone https://github.com/its-qusai-nasr/jira-admin-mcp
cd jira-admin-mcp
uv sync                 # creates .venv and installs deps from uv.lock
cp .env.example .env    # then edit .env with your Jira credentials
uv run jira-mcp         # starts the server over stdio

---

配置

服务从环境变量中读取设置（通过上方的 env 块传入；或者在运行本地克隆时，从项目目录中的 .env 文件读取）。

变量	必填	描述
JIRA_BASE_URL	是	你的 Jira Cloud 基础 URL，例如 https://your-company.atlassian.net
JIRA_EMAIL	是	拥有 API 令牌的 Atlassian 账户邮箱
JIRA_API_TOKEN	是	从 https://id.atlassian.com/manage-profile/security/api-tokens 获取的 API 令牌
JIRA_DRY_RUN	否	true 会模拟所有写入操作（POST/PUT/DELETE），并返回将要发送的载荷，而不会调用 Jira。默认为 false。

提示： 首次使用时，可设置 JIRA_DRY_RUN=true。每个写入工具都会返回 {"dry_run": true, "would_call": ...} 预览，让你在允许 Agent 操作实时数据之前，先查看它打算执行的操作。

---

你可以提出的请求

连接后，助手可以执行以下操作：

• “将 [email protected] 添加到 jira-developers 组。”
• “将 Team 自定义字段的范围限制为仅限 ENG 和 OPS 项目，并应用于 Story 和 Bug 问题类型。”
• “哪些项目共用权限方案 10789？我想编辑它，但不影响其他项目。”
• “将 OPS 项目中的每个 Internal Task 都改为 Task 类型，然后将未完成的问题转换为 In Progress。”
• “为分配给我的未解决 Bug 创建一个已保存的筛选器，并与开发者组共享。”
• “显示 PROJ-123 的变更历史，并告诉我是谁重新打开了它。”

---

工具（共 78 个）

问题（12）

工具	描述
jira_issues_search	使用 JQL 搜索问题，支持分页
jira_issues_get	根据键获取单个问题（摘要或完整详情）
jira_issues_create	创建问题并指定项目、类型和字段
jira_issues_update	更新现有问题的字段
jira_issues_transition	转换为新状态（自动解析转换 ID）
jira_issues_assign	分配或取消分配问题
jira_issues_get_transitions	列出可用的工作流转换
jira_issues_get_createmeta	获取创建问题所需的字段
jira_issues_delete	永久删除问题
jira_issues_link	创建两个问题之间的链接
jira_issues_get_changelog	获取审计历史记录（谁更改了什么）
jira_issues_bulk_create	批量创建最多 50 个问题

评论（2）

工具	描述
jira_comments_list	列出问题上的评论
jira_comments_add	添加评论（纯文本会自动转换为 ADF）

用户（2）

工具	描述
jira_users_search	按邮箱或显示名称搜索
jira_users_get	根据账户 ID 获取用户详情和所属组

组（6）

工具	描述
jira_groups_list	列出组及其成员数量
jira_groups_get_members	获取组成员
jira_groups_add_user	将用户添加到组
jira_groups_remove_user	从组中移除用户
jira_groups_create	创建新组
jira_groups_delete	删除组

项目（10）

工具	描述
jira_projects_list	按名称/键筛选项目
jira_projects_get	获取项目详情和问题类型
jira_projects_get_statuses	按问题类型分组的所有状态
jira_projects_get_roles	获取包含执行者（用户/组）的角色
jira_projects_update_role	在项目角色中添加/移除执行者
jira_projects_get_versions	列出项目中的版本/发行版
jira_projects_create_version	创建新版本/发行版
jira_projects_get_features	获取已启用/禁用的功能
jira_projects_get_notification_scheme	获取通知方案
jira_projects_get_categories	列出项目类别

权限（4）

工具	描述
jira_permissions_list_schemes	列出所有权限方案
jira_permissions_get_scheme	获取包含所有授权的方案
jira_permissions_add_grant	向方案添加权限授权
jira_permissions_assign_scheme	为项目分配方案

自定义字段（12）

工具	描述
jira_fields_search	搜索字段名称，查找字段 ID
jira_fields_get_contexts	获取自定义字段的上下文
jira_fields_get_options	获取选择/下拉字段的选项
jira_fields_manage_options	添加、更新或重新排序字段选项
jira_fields_create_context	创建上下文，可选择限定到项目/问题类型
jira_fields_update_context	重命名上下文或修改其描述
jira_fields_delete_context	删除上下文及其选项
jira_fields_assign_context_projects	将上下文限定到特定项目
jira_fields_remove_context_projects	移除上下文的项目限定
jira_fields_add_context_issuetypes	将上下文限定到特定问题类型
jira_fields_remove_context_issuetypes	从上下文中移除问题类型
jira_fields_get_project_mapping	审查每个上下文涵盖的项目

筛选器（10）

工具	描述
jira_filters_search	搜索已保存的 JQL 筛选器
jira_filters_create	创建新的已保存 JQL 筛选器
jira_filters_get	获取包含所有者和共享权限的筛选器
jira_filters_update	更新名称/JQL/描述
jira_filters_delete	永久删除筛选器
jira_filters_change_owner	更改筛选器的所有者
jira_filters_get_shares	列出筛选器的共享权限
jira_filters_add_share	添加共享（需要拥有该筛选器）
jira_filters_remove_share	移除共享权限
jira_filters_force_add_share	为非本人所有的筛选器添加共享（通过交换所有者绕过限制）

问题链接、状态（2）

工具	描述
jira_issue_link_types_list	列出可用的链接类型（Blocks、Relates 等）
jira_statuses_search	搜索此实例中的状态

工作流（8）

工具	描述
jira_workflows_search	按名称搜索工作流
jira_workflows_get_schemes	列出工作流方案
jira_workflows_get_scheme_mappings	问题类型到工作流的映射
jira_workflows_get_scheme_project_usages	列出使用某方案的项目（共享方案安全检查）
jira_workflows_set_scheme_issuetype	将问题类型映射到工作流
jira_workflows_delete_scheme_issuetype	移除问题类型的工作流映射
jira_workflows_create_scheme_draft	创建可编辑的方案草稿
jira_workflows_publish_scheme_draft	发布方案草稿，使其生效

问题类型、屏幕（6）

| 工具 | 描述 | |---|---| | `jira_issuetypes_list` | 列出问题类型（可按项目筛选） | | `jira_issuetypes_get_schemes` | 列出问题类型方案 | | `jira_issuetypes_get_scheme_mappings` | 列出方案中的问题类型 | | `jira_screens_list` | 列出屏幕 | | `jira_screens_get_fields` | 获取屏幕标签页上的字段 | | `jira_screens_get_schemes` | 列出屏幕方案 |

批量操作、任务（4）

工具	描述
jira_bulk_edit_issues	批量编辑多个问题的字段
jira_bulk_transition_issues	批量将问题转换为新状态
jira_tasks_get_status	按 ID 查询通用任务或批量队列任务的状态
jira_tasks_cancel	请求取消通用异步任务

---

设计说明

• 整合，而非封装 - 提供 78 个面向工作流的工具，而非逐一镜像每个 REST 端点。
• 试运行 - JIRA_DRY_RUN=true 会让所有写入操作返回模拟数据。
• 响应过滤 - 移除 self、_links、avatarUrls 等冗余内容，让 Agent 只看到有用字段。
• 详情级别 - 读取工具接受 detail="summary"（默认值）或 detail="full"。
• 自动包装 ADF - 注释和描述中的纯文本会自动转换为 Atlassian Document Format。
• 转换解析 - jira_issues_transition 会自动将状态名称解析为转换 ID。
• 可操作的错误 - 错误消息会说明问题所在以及接下来可以尝试什么。
• 令牌认证范围 - 有意不封装 webhook 端点（/webhook）；Atlassian 将其限制为 Connect / OAuth 2.0 应用，而令牌认证无法满足这一要求。

---

本地测试

使用 MCP Inspector 交互式检查并调用工具：

npx @modelcontextprotocol/inspector uvx --from . jira-mcp

运行单元测试（不会进行网络调用）：

uv sync --extra dev
uv run pytest
uv run ruff check .

---

安全

• 切勿提交凭据。 .env 已加入 git 忽略；请使用客户端配置中的 env 块或操作系统的密钥管理器。
• 遵循最小权限原则。 API 令牌以你的 Jira 用户身份运行。请使用权限范围仅包含所需内容的账户，尤其是用于写入/管理工具时。
• 从试运行开始。 JIRA_DRY_RUN=true 可让你在正式执行前检查每项预期写入操作。
• 请参阅官方的 MCP 安全最佳实践。

---

贡献

欢迎提交问题和 PR。请参阅 CONTRIBUTING.md。

许可证

MIT