redmine-mcp-stdio

redmine-mcp-stdio

适用于 Redmine 的本地 Model Context Protocol 服务（stdio）。将 MCP 客户端连接到它（Cursor、VS Code、Claude、Codex、Windsurf、Cline、Zed、JetBrains AI 等），即可直接在编辑器中处理 Redmine 问题、项目和工时记录。

工具

工具	功能	关键参数
list_issues	列出／筛选问题，支持分页	project_id、status_id、assigned_to_id、query、limit、offset、all
get_issue	获取单个问题的完整详情、评论／历史记录及附件	id、include_journals（默认值为 true）
list_projects	列出可访问的项目	limit
get_project	获取项目详情、版本和成员	id
create_issue	创建问题	project_id、subject、description、tracker_id、priority_id、assigned_to_id、status_id
update_issue	更新问题字段	id + 以下任意参数：subject、status_id、priority_id、assigned_to_id、done_ratio、notes
add_comment	为问题添加备注	id、notes
log_time	为问题／项目记录工时	issue_id 或 project_id、hours、activity_id、comments、spent_on
list_time_entries	列出工时记录，支持筛选	issue_id、project_id、user_id、from、to、limit、offset
list_enumerations	获取跟踪器／状态／优先级／活动的 ID	无
search	全文搜索（问题、Wiki、新闻等）	q、project_id、types、titles_only、open_issues、limit、offset
get_current_user	获取 API 密钥对应的账户（ID、登录名、姓名）	无

每个工具都附带 MCP 工具注解（readOnlyHint、destructiveHint 等），因此客户端可以自动批准只读调用。

安装

无需手动安装。客户端会按需通过 npx 启动服务，首次运行时下载，之后会将其缓存。只需在连接部分添加客户端配置。

想从本地克隆运行？请参阅开发。

获取 Redmine API 密钥

我的账户 > API 访问密钥 > 显示。

• 如果没有此部分，管理员必须在管理 > 设置 > API中启用 REST API。
• 密钥必须属于有权限查看问题（若要写入，还需有创建／编辑权限）的用户。

⚠️ 切勿提交 API 密钥。将 .env.example 复制为 .env 以供本地使用；.env 已加入 gitignore。

连接

服务会从环境中读取 REDMINE_URL 和 REDMINE_API_KEY。通过客户端 MCP 配置的 env 块提供这些值。

Cursor

编辑 ~/.cursor/mcp.json（全局配置）或项目根目录中的 .cursor/mcp.json：

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "redmine-mcp-stdio"],
      "env": {
        "REDMINE_URL": "https://redmine.your-company.com",
        "REDMINE_API_KEY": "your_key"
      }
    }
  }
}

重新加载 Cursor，并在设置 > MCP中启用该服务。

VS Code（GitHub Copilot）

编辑工作区中的 .vscode/mcp.json（或用户级 mcp.json）。请注意，顶层键是 servers，而不是 mcpServers：

{
  "servers": {
    "redmine": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "redmine-mcp-stdio"],
      "env": {
        "REDMINE_URL": "https://redmine.your-company.com",
        "REDMINE_API_KEY": "your_key"
      }
    }
  }
}

Claude Code

claude mcp add redmine \
  --env REDMINE_URL=https://redmine.your-company.com \
  --env REDMINE_API_KEY=your_key \
  -- npx -y redmine-mcp-stdio

或者直接编辑 ~/.claude.json／项目中的 .mcp.json（格式与下方 Claude Desktop 相同）。

Claude Desktop

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "redmine-mcp-stdio"],
      "env": {
        "REDMINE_URL": "https://redmine.your-company.com",
        "REDMINE_API_KEY": "your_key"
      }
    }
  }
}

之后重启 Claude Desktop。

Codex CLI

在 ~/.codex/config.toml 中添加一个服务表：

[mcp_servers.redmine]
command = "npx"
args = ["-y", "redmine-mcp-stdio"]
env = { REDMINE_URL = "https://redmine.your-company.com", REDMINE_API_KEY = "your_key" }

如果通过 nvm 安装了 node，请将 which npx 返回的完整路径用作 command。

Windsurf

编辑 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "redmine-mcp-stdio"],
      "env": {
        "REDMINE_URL": "https://redmine.your-company.com",
        "REDMINE_API_KEY": "your_key"
      }
    }
  }
}

在 Cascade 中，打开MCP 服务 > 管理 > 查看原始配置，粘贴后刷新。如果不想直接填写密钥，也支持 ${env:VAR} 插值。

Cline

在 Cline 面板中，点击 MCP Servers 图标并选择 Configure MCP Servers，打开 cline_mcp_settings.json：

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "redmine-mcp-stdio"],
      "env": {
        "REDMINE_URL": "https://redmine.your-company.com",
        "REDMINE_API_KEY": "your_key"
      }
    }
  }
}

Zed

Zed 将 MCP 服务称为上下文服务。打开命令面板并运行 zed: open settings，然后在 settings.json 中添加配置（注意 "source": "custom"）：

{
  "context_servers": {
    "redmine": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "redmine-mcp-stdio"],
      "env": {
        "REDMINE_URL": "https://redmine.your-company.com",
        "REDMINE_API_KEY": "your_key"
      }
    }
  }
}

Zed 会在保存时重启服务，因此无需重新加载编辑器。

JetBrains AI Assistant（2025.2+）

设置 > 工具 > AI Assistant > Model Context Protocol (MCP) > 添加：

• 类型：stdio
• 命令：npx（如果通过 nvm 安装了 node，请使用 which npx 返回的完整路径）
• 参数：-y redmine-mcp-stdio
• 环境：
  • REDMINE_URL=https://redmine.your-company.com
  • REDMINE_API_KEY=your_key

启用 "Automatically enable new and changed MCP servers"，然后点击应用。点击状态图标后，你应能看到 12 个工具。在聊天中使用 / 调用它们。

本地验证（可选）

REDMINE_URL=https://redmine.your-company.com REDMINE_API_KEY=your_key npx -y redmine-mcp-stdio

进程应启动并在 stdio 上静默等待（按 Ctrl+C 退出）。

故障排除

• **Failed to connect／服务无法启动：**客户端环境必须能够解析 command。如果通过 nvm 安装了 node，可能无法找到单独的 npx。请将 which npx 返回的完整路径用作命令。
• **Missing REDMINE_URL or REDMINE_API_KEY：**未传递 env 块。请确认它位于 MCP 配置中，而不是 shell 配置中。
• **Redmine 401／403：**API 密钥无效，或密钥所属用户没有执行该操作的权限。
• **Redmine 404：**问题／项目 ID 不存在，或 REDMINE_URL 指向了错误的主机。

配置

变量	必需	默认值	说明
REDMINE_URL	是	n/a	Redmine 实例的基础 URL（http/https）
REDMINE_API_KEY	是	n/a	个人 API 访问密钥
REDMINE_TIMEOUT_MS	否	10000	每次请求的超时时间，单位为毫秒
REDMINE_MAX_RETRIES	否	2	遇到 429／5xx 时采用指数退避进行重试的次数

架构

代码采用分层组织，并向每个工具组注入一个 HTTP 客户端，因此工具不会直接接触传输层或 process.env：

src/
  index.ts            entry point: load config, build client, register tools, serve stdio
  config.ts           env parsing + validation (Zod) into a typed RedmineConfig
  version.ts          single source of the version string
  redmine/
    client.ts         RedmineClient: auth, timeout, retry, host pinning, secret redaction
    errors.ts         RedmineError / ConfigError + HTTP error normalization
    paths.ts          safe path-segment encoding + project-id validation
    types.ts          Redmine API response types
  tools/
    register.ts       wires every tool group onto the server
    issues.ts         list/get/create/update issues + add_comment
    projects.ts       list/get projects (versions, members)
    time-entries.ts   log_time, list_time_entries
    enumerations.ts   trackers / statuses / priorities / activities
    search.ts         full-text search across issues, wiki, news, ...
    users.ts          get_current_user
    helpers.ts        guard(), ok()/fail(), ToolResult
  format.ts           pure presentation helpers

开发

npm run build       # compile src/ to build/
npm run typecheck   # tsc --noEmit (strict)
npm run lint        # eslint
npm run format      # prettier --write
npm test            # build, then run the vitest suite
npm run check       # typecheck + lint + format:check + test (what CI runs)

有关发行版本，请参阅 CHANGELOG.md。

安全

API 密钥绝不会被记录，并会从错误输出中脱敏；请求固定到配置的主机，路径参数会进行编码，且每次调用都受超时和响应大小上限约束。详情及报告方式请参阅：SECURITY.md。

许可证

MIT。请参阅 LICENSE。