redmine-mcp-connector

Redmine MCP 服务

基于 stdio 的 Model Context Protocol 服务，通过 REST API（*.json 端点）封装 Redmine 实例。它作为独立的 Node.js 进程运行；无需修改 Redmine Rails 应用。

要求

• Node.js 20+
• 拥有API 访问密钥的 Redmine 用户（我的账号 → 显示 API 访问密钥）
• 此进程能够通过网络访问 Redmine 的 REDMINE_BASE_URL

安装

正常使用无需安装——编码 Agent 会按需通过 npx 启动它：

npx -y redmine-mcp-connector

有关 Claude Desktop、Claude Code、Cursor、Windsurf、Cline、VS Code、Zed 及其他任何 MCP 客户端的详细设置说明，以及本地构建和 Docker 替代方案，请参阅 CONNECTING.md。

若要开发此服务，请改为克隆此仓库：

npm install
npm run build

配置

环境变量（参见 .env.example）：

变量	必需	描述
REDMINE_BASE_URL	是	基础 URL，例如 https://redmine.example.com（末尾不带斜杠）
REDMINE_API_KEY	是	X-Redmine-API-Key 的值
REDMINE_IMPERSONATE_USER	否	设置 X-Redmine-Switch-User（在 Redmine 中仅管理员可用）
REDMINE_READONLY	否	若为 true / 1，则阻止所有会修改数据的 HTTP 方法
REDMINE_ALLOW_RAW_REQUEST	否	若为 true / 1，则注册 redmine_request 备用工具
REDMINE_HTTP_TIMEOUT_MS	否	默认值为 15000
REDMINE_MAX_PAGES	否	列表工具使用 fetch_all 时的最大页数（默认值为 20）
REDMINE_MAX_DOWNLOAD_BYTES	否	redmine_attachment_download 的大小上限（默认值为 5 MiB）

运行

REDMINE_BASE_URL=https://your-redmine.example.com REDMINE_API_KEY=secret npm start
# or during development:
REDMINE_BASE_URL=... REDMINE_API_KEY=... npm run dev

连接到编码 Agent

各客户端的完整说明（Claude Desktop、Claude Code、Cursor、Windsurf、Cline、VS Code、Zed 及通用 MCP 客户端）见 CONNECTING.md。快速示例（Claude Desktop / Cursor / Windsurf 使用相同格式）：

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "redmine-mcp-connector"],
      "env": {
        "REDMINE_BASE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

MCP 资源（只读）

URI	描述
redmine://projects	GET /projects.json（前 100 个）
redmine://me	GET /users/current.json
redmine://me/issues	GET /issues.json?assigned_to_id=me（上限 100）
redmine://projects/{id}	GET /projects/:id.json

工具概览

命名格式：redmine_<resource>_<action>。

问题： redmine_issues_list、redmine_issue_get、redmine_issue_create、redmine_issue_update、redmine_issue_add_comment、redmine_issue_delete（需要 confirm: true）、添加/移除关注者、列出/添加/移除关联。

项目： redmine_projects_list、redmine_project_get、创建/更新/归档/取消归档/删除（删除需要 confirm）。

用户： redmine_current_user、redmine_users_list、redmine_user_get、创建/更新/删除（删除需要 confirm）。

工时记录： 列出/获取/创建/更新/删除（删除需要 confirm）。

新闻： 列出/获取/创建/更新/删除（删除需要 confirm）。

Wiki： 列出页面、获取页面、创建/更新（PUT）、删除（需要 confirm）。

版本和类别： 版本 CRUD（删除需要 confirm）、问题类别 CRUD（删除需要 confirm）。

查询和元数据： redmine_queries_list、redmine_enumerations_list、redmine_trackers_list、redmine_issue_statuses_list、redmine_roles_list、redmine_role_get、redmine_custom_fields_list。

用户组（只读）： redmine_groups_list、redmine_group_get。

成员关系： 列出/创建/更新/删除（删除需要 confirm）。

附件和搜索： redmine_search、获取/更新/删除/上传/下载附件（下载以 base64 返回，并受大小限制）。

代码仓库（标准 Redmine 中 REST 支持有限）： redmine_repository_revision_link_issue、redmine_repository_revision_unlink_issue（需要 confirm）。核心 Redmine 不支持通过 JSON 列出代码仓库/修订版本；若启用 redmine_request，请使用该工具或安装插件。

备用入口： redmine_request——仅在 REDMINE_ALLOW_RAW_REQUEST=true 时可用；DELETE 需要 confirm: true。

安全

• 如有说明，破坏性工具需要明确设置 confirm: true。
• 在只读部署中设置 REDMINE_READONLY=true。
• 此服务不会记录 API 密钥。

Docker

构建本地映像：

docker build -t redmine-mcp-server:local .

运行（stdio MCP 服务）：

docker run --rm -i   -e REDMINE_BASE_URL="https://redmine.example.com"   -e REDMINE_API_KEY="your_api_key_here"   redmine-mcp-server:local

在 MCP 配置中使用此映像：

{
  "mcpServers": {
    "redmine": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "REDMINE_BASE_URL",
        "-e", "REDMINE_API_KEY",
        "docker.io/<docker-user>/redmine-mcp-server:latest"
      ],
      "env": {
        "REDMINE_BASE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

发布到 Docker Hub Catalog

1. 登录：

docker login

2. 创建并使用 buildx 构建器（仅需执行一次）：

docker buildx create --name redmine-mcp-builder --use --bootstrap

3. 构建并推送多架构映像：

export IMAGE=docker.io/<docker-user>/redmine-mcp-server
export TAG=1.0.0

docker buildx build   --platform linux/amd64,linux/arm64   -t $IMAGE:$TAG   -t $IMAGE:latest   --push .

4. 在 Docker Hub 中，将仓库描述设置为此 README 的内容，并将其设为公开，以便在 Catalog 中发现。

开发

npm run lint
npm test

贡献

欢迎贡献。

• 查看 CONNECTING.md，了解客户端设置的详细说明。
• 阅读 CONTRIBUTING.md，了解本地设置、编码规范和 PR 工作流。
• 遵循 CODE_OF_CONDUCT.md，保持协作友善且包容。
• 查看 SUPPORT.md，了解求助渠道以及需要提供哪些详细信息。
• 按照 SECURITY.md 中的说明，私下报告漏洞。
• 有关公开分发模板（Docker + MCP 目录），请参阅 REGISTRY_PUBLISHING.md。

许可证

GPL-2.0-or-later（与 Redmine 属于同一系列）。