AI Agent Integration

redmine-cli ships two complementary integrations, both vendor-neutral:

• Agent Skill — a SKILL.md instruction set following the open Agent Skills standard, supported by 35+ agents (Claude, Codex, Gemini, Cursor, Copilot, Cline, Goose, Windsurf, Roo, Junie, …). Teaches the agent how to drive the CLI effectively.
• MCP Server — redmine mcp serve exposes the CLI over the Model Context Protocol. Best for hosts that discover tools through MCP.

For most hosts you want both. Several major hosts (Claude Code, Codex CLI, Gemini CLI) support a one-step plugin install that bundles them together.

Quick install

Any agent Claude Code Codex CLI Gemini CLI MCP host

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

• Any agent uses the skills.sh installer (npx skills add), which detects your agent and writes SKILL.md to the right location (.claude/skills/, .codex/skills/, .gemini/skills/, or the cross-vendor .agents/skills/ fallback). The bundled wrapper is redmine install-skill [--global].
• Claude Code / Codex CLI / Gemini CLI bundle the skill and MCP server in a single plugin install. After installing, run /reload-plugins (Claude) or restart the CLI to activate.
• MCP host is the manual route for Cursor, VS Code, Zed, Claude Desktop, and other MCP-aware hosts. Add redmine mcp serve (with optional --profile, --enable-writes, --enable-groups, …) to your host’s MCP config; see your host’s MCP setup docs for the exact file path and JSON shape.

Note

Prerequisite for all paths: redmine must be on the host’s PATH and you must have logged in once via redmine auth login. The skill-only path additionally needs Node.js for npx skills add.

Agent Skill

The skill teaches the agent what --help cannot: output formats, pagination, filtering, name resolution, and common workflows. After installing it the agent knows to use -o json, resolve ambiguous values by querying first, and pick the right flags without guessing.

The full skill source: skills/redmine-cli/SKILL.md. Copy directly into your agent’s instructions if you prefer not to run an installer.

MCP Server

redmine mcp serve exposes the CLI as a Model Context Protocol server over stdio by default, or over streamable HTTP when --http is passed. MCP-aware hosts can then drive Redmine through tool calls, reusing the same profile-backed authentication as every other redmine command.

How it works

• Transport: stdio by default. The host can spawn redmine mcp serve and talk JSON-RPC over its standard streams, or you can pass --http :8080 to expose the same server over streamable HTTP.
• Authentication: the active profile is used by default. Override with --profile <name>, --server / --api-key, or the REDMINE_* environment variables — exactly like every other subcommand.
• Read-only by default. Mutating tools (create / update / delete, comment, close, reopen, and similar write operations) are registered only when --enable-writes is passed. Without the flag they never appear in tools/list.
• Configurable surface. --enable-groups / --disable-groups constrain the registered tools to specific categories (issues, wiki, time, …). For sharper control, --enable-tools / --disable-tools allow- or deny-list individual tool names. Run redmine mcp tools to print the full catalog.

Caution

Write tools are destructive. Prefer leaving them disabled unless the host surfaces a per-call approval UI you trust.

HTTP transport

Pass --http <addr> to expose the server over streamable HTTP instead of stdio. The address shorthand :8080 (no host) is rewritten to 127.0.0.1:8080 so the server is never accidentally reachable from other machines. Pass an explicit host to listen elsewhere:

# Loopback only -- safe default
redmine mcp serve --http :8080

# Explicit loopback (equivalent)
redmine mcp serve --http 127.0.0.1:8080

# Listen on every interface -- always pair with --auth-token
redmine mcp serve --http 0.0.0.0:8080 --auth-token "$(openssl rand -hex 32)"

When a non-loopback bind is detected without --auth-token, the CLI prints a warning to stderr but still starts. The server applies ReadHeaderTimeout=10s, ReadTimeout=30s, and IdleTimeout=120s; WriteTimeout is left unbounded so slow Redmine instances don’t terminate in-flight tool calls.

Clients must send the bearer token on every request:

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

The token can also live in the config block (mcp.auth_token) or REDMINE_MCP_AUTH_TOKEN. Flags override both.

Danger

The bearer token is the only thing standing between any HTTP-reachable client and your Redmine instance through this server. Generate it with a CSPRNG, never reuse it across deployments, and prefer terminating TLS in front of the server (reverse proxy) when binding outside loopback.

Narrowing the exposed tools

For an issue-only assistant, drop everything but the issues group:

redmine mcp serve --enable-groups issues

To enable writes everywhere except destructive deletes, combine the flags:

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

The same defaults can live in ~/.redmine-cli.yaml per profile, and CLI flags override them:

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

Environment variables (REDMINE_MCP_ENABLE_GROUPS, REDMINE_MCP_DISABLE_GROUPS, REDMINE_MCP_ENABLE_TOOLS, REDMINE_MCP_DISABLE_TOOLS, REDMINE_MCP_ENABLE_WRITES, REDMINE_MCP_AUTH_TOKEN) override the config block.

Prerequisite

redmine must be on the host’s PATH and a profile must already be logged in (redmine auth login). No Node.js required.

Troubleshooting

1. Host reports “command not found”. The spawned process inherits the host’s PATH, which often differs from your shell. Use an absolute path (which redmine) in the command field.

2. Tools list is empty or missing mutations. --enable-writes was not passed, the surface was narrowed via --enable-groups / --enable-tools, or the host cached an older tools/list. Run redmine mcp tools to see the full catalog and restart the host after changing args.

3. 401 / “no profile” errors. No profile is logged in, or --profile <name> points at one that does not exist. Run redmine auth list to confirm.

Related

Output formats Why agents lean on -o json and how it behaves.

Quick Start A human-friendly tour of the commands agents wrap.