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 设置文档。
Docker 通过 ghcr.io/aarondpn/redmine-mcp 镜像运行 MCP 服务器，完全无需安装 redmine。参见使用 Docker 运行。

代理 Skill

该 skill 教给代理的是 --help 无法传达的内容：输出格式、分页、过滤、名称解析以及常用工作流。安装后，代理便知道用 --jq 提取字段、检查退出码而不是从 stdout 解析错误、查看附件，并在不确定时查阅 --help 而不是猜测标志。

完整的 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 中。如需传输层的双重保障，可启用只读模式（在配置文件中设置 read_only: true 或设置 REDMINE_READ_ONLY=1）——它会在 HTTP 层阻止所有写入，即使已传入 --enable-writes。
API 密钥不会经过 MCP。 任何工具或资源都不会返回 Redmine API 密钥。get_my_account、me、get_user、list_users、create_user 和 redmine://user/... 会在用户记录到达客户端之前移除 api_key，即使 Redmine 的响应中包含该字段；这些工具的输出 schema 也不声明该字段。CLI 不受影响：redmine my-account get 仍会显示你自己的密钥。
可配置暴露范围。 --enable-groups / --disable-groups 可将注册的工具限制到特定类别（issues、wiki、time 等）。若需更细粒度的控制，可使用 --enable-tools / --disable-tools 对单个工具做 allow-list 或 deny-list。运行 redmine mcp tools 可打印完整工具目录。

使用 Docker 运行

ghcr.io/aarondpn/redmine-mcp 镜像（linux/amd64 与 linux/arm64）直接运行 redmine mcp serve。无需本地安装、配置档或密钥环，只需通过环境变量传入服务器 URL 与 API 密钥。所有 REDMINE_* 变量和 redmine mcp serve 的所有标志在容器内的用法完全相同；标志写在镜像名之后。

标签	对应版本
`latest`	最新稳定版本
`2`、`2.13`、`2.13.0`	主版本、次版本或精确版本

本地：stdio

MCP 宿主为每个会话启动一个新容器，并通过 stdin/stdout 通信。-i 必不可少；--rm 负责事后清理。-e NAME（不带 =value）会从宿主环境转发该变量，因此密钥不会出现在参数列表中。

Claude Code：

claude mcp add redmine \
  -e REDMINE_SERVER=https://redmine.example.com \
  -e REDMINE_API_KEY=your-api-key \
  -- docker run -i --rm -e REDMINE_SERVER -e REDMINE_API_KEY ghcr.io/aarondpn/redmine-mcp

Claude Desktop、Cursor、Windsurf 及其他使用 mcpServers JSON 结构的宿主：

{
  "mcpServers": {
    "redmine": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "REDMINE_SERVER", "-e", "REDMINE_API_KEY", "ghcr.io/aarondpn/redmine-mcp"],
      "env": {
        "REDMINE_SERVER": "https://redmine.example.com",
        "REDMINE_API_KEY": "your-api-key"
      }
    }
  }
}

一键安装：

VS Code 会提示输入 URL 与 API 密钥，并将密钥作为机密保存。Cursor 会写入占位值：安装后请在 Cursor 的 MCP 设置中打开该服务器，替换 REDMINE_SERVER 与 REDMINE_API_KEY。

如需启用写入或收窄工具范围，可在镜像名之后添加标志（... ghcr.io/aarondpn/redmine-mcp --enable-writes --enable-groups issues,time），或转发对应的 REDMINE_MCP_* 变量。

已有包含配置档的 ~/.redmine-cli.yaml？以只读方式挂载并选择配置档。redmine auth login 以 0600 权限写入该文件，--user 可确保容器内仍能读取。将密钥保存在系统密钥环中的配置档无法在容器内读取，请为其提供 REDMINE_API_KEY。

docker run -i --rm --user "$(id -u):$(id -g)" \
  -v "$HOME/.redmine-cli.yaml:/config.yaml:ro" \
  ghcr.io/aarondpn/redmine-mcp --config /config.yaml --profile work

共享：使用 Docker Compose 运行 HTTP 服务器

若要为整个团队运行一个服务器，请使用 HTTP 传输。仓库提供了现成的 compose.yaml 与 .env.example：

curl -fsSLO https://raw.githubusercontent.com/aarondpn/redmine-cli/main/docker/compose.yaml
curl -fsSL https://raw.githubusercontent.com/aarondpn/redmine-cli/main/docker/.env.example -o .env
# 在 .env 中设置 REDMINE_SERVER、REDMINE_API_KEY 与 REDMINE_MCP_AUTH_TOKEN（openssl rand -hex 32）
docker compose up -d

然后让客户端携带令牌连接到服务器：

claude mcp add --transport http redmine http://localhost:8080/ \
  --header "Authorization: Bearer $REDMINE_MCP_AUTH_TOKEN"

Compose 文件默认只在 127.0.0.1 上发布端口。在 .env 中设置 REDMINE_MCP_PUBLISH=0.0.0.0:8080 即可从其他机器访问；此时请在前面放置一个终止 TLS 的反向代理，避免以明文发送 bearer 令牌。

不使用 Compose 时，同样的服务器只需一条命令。REDMINE_MCP_HTTP 替代 --http 标志：

docker run -d --name redmine-mcp -p 127.0.0.1:8080:8080 \
  -e REDMINE_SERVER -e REDMINE_API_KEY -e REDMINE_MCP_AUTH_TOKEN \
  -e REDMINE_MCP_HTTP=0.0.0.0:8080 \
  ghcr.io/aarondpn/redmine-mcp

如果省略 REDMINE_MCP_AUTH_TOKEN，服务器会在启动时生成一个令牌并输出到容器日志（docker logs redmine-mcp）。该令牌每次重启都会变化，因此长期运行时请自行设置。

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

# 在所有网卡上监听 -- 务必同时设置令牌。
# umask 077 让令牌文件从创建起就只有你本人可读。
(umask 077; openssl rand -hex 32 > ~/.redmine-mcp-token)
redmine mcp serve --http 0.0.0.0:8080 --auth-token-file ~/.redmine-mcp-token

umask 只在创建文件时生效。如果令牌文件已经存在，请先运行 chmod 600 ~/.redmine-mcp-token，再向其中写入新令牌。

当检测到非回环绑定但未设置令牌时，服务器会为本次运行生成一个随机令牌并输出到 stderr。仅当服务器前方已有组件（例如带认证的反向代理）校验客户端时，才传入 --no-auth（或 REDMINE_MCP_NO_AUTH=1）；此时 CLI 会输出警告，并在没有令牌的情况下提供服务。

未设置令牌的回环绑定仍然可以工作，但能访问这台机器的任何人都可以连接它：每个本地用户和进程都能以你的 Redmine 用户身份调用工具。服务器会在启动时输出警告；设置令牌即可关闭这一入口。在回环绑定上显式传入 --no-auth 时，服务器会在没有令牌、也没有警告的情况下提供服务。无论绑定到哪里，到达回环监听器但 Host 头不是回环地址的请求都会被以 403 拒绝，从而阻止本地浏览器中打开的网页发起 DNS 重绑定攻击。

服务器会应用 ReadHeaderTimeout=10s、ReadTimeout=30s、IdleTimeout=120s；为避免缓慢的 Redmine 实例中断进行中的工具调用，WriteTimeout 保持不限。

HTTP 传输是无状态的，因此使用 MCP 2026-07-28 版本（无会话，用 server/discover 取代 initialize 握手）。每次工具调用都是一次自包含的 Redmine API 请求，无需维护会话。实际影响：仅提供 POST（GET 和 DELETE 返回 405），并且不支持通过 Last-Event-ID 恢复流。较旧的客户端会协商降级到 2025-11-25，行为保持不变。

设置了令牌时，客户端必须在每个请求上发送 Bearer 令牌：

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

通过 --auth-token-file <path> 传入令牌，或用 --auth-token-file - 从标准输入读取（pass show redmine-mcp | redmine mcp serve --http :8080 --auth-token-file -）。首尾的空白（例如末尾换行）会被忽略。令牌也可以放在配置块（mcp.auth_token）或 REDMINE_MCP_AUTH_TOKEN 中，监听地址可以放在 mcp.http 或 REDMINE_MCP_HTTP 中。命令行标志会覆盖二者。

对于 credential_store: keyring 的配置档，mcp.auth_token 会像 API 密钥一样，在下次保存时移入系统密钥环。之后如果 redmine mcp serve --http 无法读取密钥环（例如通过 SSH 登录时钥匙串被锁定，或设置了 REDMINE_NO_KEYRING=1），它会拒绝启动，而不是在没有令牌的情况下提供服务；请通过 REDMINE_MCP_AUTH_TOKEN 或 --auth-token-file 提供令牌，或有意传入 --no-auth 以不带认证地提供服务。

--auth-token <token> 同样可用，但令牌会出现在 ps 输出和 shell 历史中。请优先使用 --auth-token-file、REDMINE_MCP_AUTH_TOKEN 或 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_MCP_HTTP、REDMINE_MCP_NO_AUTH）会覆盖该配置块。

前置条件

redmine 必须位于宿主的 PATH，并且已有配置文件完成登录（redmine auth login）。无需 Node.js。使用 Docker 时，只需要 Docker 和一个 API 密钥。

故障排查

宿主报告 “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 进行确认。