AI 代理集成

redmine-cli 提供两种互补的集成方式，二者均与厂商无关：

代理 Skill —— 一份遵循开放 Agent Skills 标准的 SKILL.md 指令集，已被 35 多个代理支持（Claude、Codex、Gemini、Cursor、Copilot、Cline、Goose、Windsurf、Roo、Junie 等）。教代理如何高效驱动 CLI。
MCP 服务器 —— redmine mcp serve 通过 Model Context Protocol 暴露 CLI。适合通过 MCP 发现工具的宿主。

大多数宿主两者都需要。Claude Code、Codex CLI、Gemini CLI 等主流宿主支持一步式插件安装，将两者打包在一起。

快速安装

npx skills add aarondpn/redmine-cli

/plugin marketplace add aarondpn/redmine-cli
/plugin install redmine@redmine-cli

codex plugin marketplace add aarondpn/redmine-cli
/plugins  # install Redmine from the added marketplace

gemini extensions install https://github.com/aarondpn/redmine-cli

redmine mcp serve

任意代理 使用 skills.sh 安装器（npx skills add），它会检测你的代理并将 SKILL.md 写入正确位置（.claude/skills/、.codex/skills/、.gemini/skills/，或跨厂商通用的 .agents/skills/ 兜底路径）。CLI 自带的封装是 redmine install-skill [--global]。
Claude Code / Codex CLI / Gemini CLI 通过单次插件安装同时打包 skill 与 MCP 服务器。安装后运行 /reload-plugins（Claude）或重启 CLI 以激活。
MCP 宿主 是 Cursor、VS Code、Zed、Claude Desktop 以及其他 MCP 兼容宿主的手动接入路径。在你的宿主 MCP 配置中添加 redmine mcp serve（可选 --profile、--enable-writes、--enable-groups 等），具体配置文件路径与 JSON 结构请参阅各宿主的 MCP 设置文档。

代理 Skill

该 skill 教给代理的是 --help 无法传达的内容：输出格式、分页、过滤、名称解析以及常用工作流。安装后，代理便知道使用 -o json、对存在歧义的值先查询再处理，并无需猜测即可选择正确的标志。

完整的 skill 源文件：skills/redmine-cli/SKILL.md。如果不想运行安装器，可直接复制到代理的指令文件中。

MCP 服务器

redmine mcp serve 默认通过 stdio 将 CLI 暴露为一个 Model Context Protocol 服务器；传入 --http 时，则通过 streamable HTTP 暴露同一个服务。支持 MCP 的宿主可通过工具调用驱动 Redmine，复用与其他所有 redmine 命令相同的基于配置文件的身份验证。

工作原理

传输方式： 默认使用 stdio。宿主可生成 redmine mcp serve 进程并通过其标准流使用 JSON-RPC 通信；也可传入 --http :8080 通过 streamable HTTP 暴露同一个服务。
身份验证： 默认使用当前活跃的配置文件。可通过 --profile <name>、--server / --api-key 或 REDMINE_* 环境变量覆盖，与其他子命令完全一致。
默认只读。 修改类工具（创建 / 更新 / 删除、评论、关闭、重新打开及类似写操作）仅在传入 --enable-writes 时才注册。未传入该标志时，这些工具不会出现在 tools/list 中。
可配置暴露范围。 --enable-groups / --disable-groups 可将注册的工具限制到特定类别（issues、wiki、time 等）。若需更细粒度的控制，可使用 --enable-tools / --disable-tools 对单个工具做 allow-list 或 deny-list。运行 redmine mcp tools 可打印完整工具目录。

HTTP 传输

传入 --http <addr> 可以让服务器通过 streamable HTTP 而不是 stdio 暴露。地址简写 :8080（不带主机）会被改写为 127.0.0.1:8080，因此服务器永远不会被意外地暴露到其他机器。要在其他地址监听，请显式指定主机：

# 仅回环 -- 安全的默认值
redmine mcp serve --http :8080

# 显式回环（等价）
redmine mcp serve --http 127.0.0.1:8080

# 在所有网卡上监听 -- 务必同时设置 --auth-token
redmine mcp serve --http 0.0.0.0:8080 --auth-token "$(openssl rand -hex 32)"

当检测到非回环绑定但未设置 --auth-token 时，CLI 会向 stderr 输出警告，但仍然启动。服务器会应用 ReadHeaderTimeout=10s、ReadTimeout=30s、IdleTimeout=120s；为避免缓慢的 Redmine 实例中断进行中的工具调用，WriteTimeout 保持不限。

客户端必须在每个请求上发送 Bearer 令牌：

POST / HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

令牌也可以放在配置块（mcp.auth_token）或 REDMINE_MCP_AUTH_TOKEN 中。命令行标志会覆盖二者。

收窄暴露的工具范围

对于只处理 issue 的助手，仅保留 issues 组：

redmine mcp serve --enable-groups issues

若要全局启用写入但排除破坏性的删除工具，可组合这些标志：

redmine mcp serve --enable-writes --disable-tools delete_issue,delete_project,delete_wiki_page

同样的默认值也可按 profile 写入 ~/.redmine-cli.yaml，CLI 标志会覆盖这些值：

profiles:
  internal:
    server: https://redmine.internal
    api_key: ...
    mcp:
      enable_writes: true
      enable_groups: [issues, wiki]
      disable_tools: [delete_issue]

环境变量（REDMINE_MCP_ENABLE_GROUPS、REDMINE_MCP_DISABLE_GROUPS、REDMINE_MCP_ENABLE_TOOLS、REDMINE_MCP_DISABLE_TOOLS、REDMINE_MCP_ENABLE_WRITES、REDMINE_MCP_AUTH_TOKEN）会覆盖该配置块。

前置条件

redmine 必须位于宿主的 PATH，并且已有配置文件完成登录（redmine auth login）。无需 Node.js。

故障排查

宿主报告 “command not found”。 生成的进程继承宿主的 PATH，这通常与你的 shell 不同。请在 command 字段中使用绝对路径（which redmine）。
工具列表为空或缺少修改类工具。 未传入 --enable-writes，暴露范围被 --enable-groups / --enable-tools 收窄，或宿主缓存了旧的 tools/list。运行 redmine mcp tools 查看完整目录，并在修改参数后重启宿主。
401 / “no profile” 错误。 当前没有登录的配置文件，或 --profile <name> 指向的配置文件不存在。运行 redmine auth list 进行确认。