MCP Redmine

MCP Redmine

状态：持续维护，日常使用中。

让 Claude 成为你的 Redmine 助手！MCP Redmine 将 Claude Desktop 连接到你的 Redmine 实例，使其能够：

• 搜索和浏览项目与问题
• 创建和更新问题，全面支持 Markdown
• 上传和下载文件附件
• 管理和跟踪工时记录
• 更新问题状态和字段
• 使用全面的 Redmine API 功能

使用 httpx 发起 API 请求，并集成 Redmine OpenAPI 规范，全面覆盖 API 功能。

在 Claude Desktop 中使用

1. 使用 uv 安装

确保已安装 uv。

uv --version

如果尚未安装 uv，请先安装。

• Linux

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• macOS

  brew install uv
  

• windows

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

添加到你的 claude_desktop_config.json：

  {
    "mcpServers": {
      "redmine": {
        "command": "uvx",
        "args": ["--from", "mcp-redmine==2026.10.15.204909",
                "--refresh-package", "mcp-redmine", "mcp-redmine"],
        "env": {
          "REDMINE_URL": "https://your-redmine-instance.example.com",
          "REDMINE_API_KEY": "your-api-key",
          "REDMINE_REQUEST_INSTRUCTIONS": "/path/to/instructions.md",
          "REDMINE_ALLOWED_DIRECTORIES": "/tmp,/home/user/uploads"
        }
      }
    }
  }

2. 使用 docker 安装

确保已安装 docker。

docker --version

从 GitHub Container Registry 拉取已发布的镜像：

docker pull ghcr.io/runekaagaard/mcp-redmine:latest

或者自行构建镜像：

git clone [email protected]:runekaagaard/mcp-redmine.git
cd mcp-redmine
docker build -t ghcr.io/runekaagaard/mcp-redmine .

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "redmine": {
      "command": "docker",
      "args":  [
          "run",
          "-i",
          "--rm",
          "-e", "REDMINE_URL",
          "-e", "REDMINE_API_KEY",
          "-e", "REDMINE_REQUEST_INSTRUCTIONS",
          "-e", "REDMINE_ALLOWED_DIRECTORIES",
          "-v", "/path/to/instructions.md:/app/INSTRUCTIONS.md",
          "-v", "/path/to/uploads:/app/uploads",
          "ghcr.io/runekaagaard/mcp-redmine:latest"
      ],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.example.com",
        "REDMINE_API_KEY": "your-api-key",
        "REDMINE_REQUEST_INSTRUCTIONS": "/app/INSTRUCTIONS.md",
        "REDMINE_ALLOWED_DIRECTORIES": "/app/uploads"
      }
    }
  }
}

3. 其他 MCP 客户端和传输方式

MCP Redmine 可与任何 MCP 客户端（Claude Code、Cursor、基于 IntelliJ 的 IDE、n8n 等）配合使用——按照客户端文档注册 MCP 服务，并将客户端指向上述相同的命令和环境变量。

默认情况下，服务使用 stdio 通信。对于通过 HTTP 连接的客户端或部署方式，请使用以下某种 HTTP 传输方式启动服务：

# Recommended HTTP transport (serves on http://HOST:PORT/mcp)
mcp-redmine --transport streamable-http --host 0.0.0.0 --port 8000

# Legacy SSE transport, for older clients (serves on http://HOST:PORT/sse)
mcp-redmine --transport sse --host 0.0.0.0 --port 8000

多用户 HTTP 部署

作为共享 HTTP 服务运行时，每个客户端都可以在请求头中发送自己的 Redmine API 密钥：X-Redmine-API-Key。这样，操作会归属于发起请求的用户，而不是某个共享服务账号。此请求头优先级更高；REDMINE_API_KEY 仍可作为后备方案（且是 stdio 模式下的唯一选项）。以下是使用 Claude Code 的示例：

claude mcp add --transport http --header "X-Redmine-API-Key: <your-personal-key>" \
  redmine http://shared-server:8000/mcp

仅在可信网络或 TLS 环境中使用此方式——请求头中包含凭据。

环境变量

变量	必需	默认值	说明
REDMINE_URL	是	-	Redmine 实例的 URL。支持子路径（例如，http://localhost/redmine/）
REDMINE_API_KEY	是*	-	Redmine API 密钥（获取方法见下文）。*如果每个客户端都发送 X-Redmine-API-Key，则此项为可选（见下文“多用户”）
REDMINE_REQUEST_INSTRUCTIONS	否	-	包含 redmine_request 工具附加说明的文件路径。我发现让大模型在会话结束后生成该文件效果很好。（示例 1 示例 2）
REDMINE_HEADERS	否	（空）	所有请求中都包含的自定义 HTTP 标头。格式："Header1: Value1, Header2: Value2"。适用于需要额外身份验证的代理（例如，X-Redmine-Username）
REDMINE_RESPONSE_FORMAT	否	yaml	响应格式：yaml 或 json。控制 API 响应的格式
REDMINE_ALLOWED_DIRECTORIES	用于上传/下载	（已禁用）	**文件操作必需。**允许上传/下载的目录列表，以逗号分隔（例如，/tmp,/home/user/uploads）。出于安全考虑，未设置时将禁用上传/下载
REDMINE_DANGEROUSLY_ACCEPT_INVALID_CERTS	否	（已禁用）	设置为 1 可禁用 SSL 证书验证。仅在可信环境中用于自签名证书
REDMINE_CA_BUNDLE	否	（系统 CA）	使用私有证书链的 Redmine 实例所用自定义 CA 证书包的路径（例如，/path/to/ca.crt）。建议使用此选项，而不是禁用验证
REDMINE_READ_ONLY	否	（已禁用）	设置为 1 仅允许 GET 请求。所有写入操作（POST/PUT/DELETE，包括上传）都会被拒绝

注意：通过 Docker 运行时，REDMINE_REQUEST_INSTRUCTIONS 环境变量必须指向容器内的路径，而不是主机上的路径。 因此，如果要使用本地文件，需要将其挂载到容器内的正确位置。

安全提示：REDMINE_ALLOWED_DIRECTORIES 设置可防止路径遍历攻击。包含 ../ 的路径会在验证前进行解析，确保只能访问允许目录中的文件。

获取 Redmine API 密钥

1. 登录 Redmine 实例
2. 前往“My account”（通常位于右上角菜单中）
3. 在页面右侧，找到“API access key”
4. 点击“Show”查看现有密钥，或点击“Generate”创建新密钥
5. 复制该密钥，以便在配置中使用

API

工具

• redmine_paths_list

  • 返回 OpenAPI 规范中的可用 API 路径列表
  • 无需输入
  • 返回包含路径模板列表的 YAML 字符串：

  - /issues.json
  - /projects.json
  - /time_entries.json
  ...
  

• redmine_paths_info

  • 获取给定路径模板的完整路径信息
  • 输入：path_templates（字符串列表）
  • 返回包含所请求路径的 API 规范的 YAML 字符串：

  /issues.json:
    get:
      operationId: getIssues
      parameters:
        - $ref: '#/components/parameters/format'
      ...
  

• redmine_request

  • 向 Redmine API 发送请求
  • 输入：
    • path（字符串）：API 端点路径（例如，'/issues.json'）
    • method（字符串，可选）：使用的 HTTP 方法（默认：'get'）
    • data（对象，可选）：请求正文的字典（用于 POST/PUT）
    • params（对象，可选）：查询参数的字典
  • 返回包含响应状态码、正文和错误消息的 YAML 字符串：

  status_code: 200
  body:
    issues:
      - id: 1
        subject: "Fix login page"
        ...
  error: ""
  

• redmine_upload

  • 将文件上传到 Redmine 并获取用于附件的令牌
  • 需要设置 REDMINE_ALLOWED_DIRECTORIES
  • 输入：
    • file_path（字符串）：要上传文件的完整路径（必须位于允许的目录中）
    • description（字符串，可选）：文件的可选说明
  • 返回与 redmine_request 格式相同的 YAML 字符串，其中包含上传令牌：

  status_code: 201
  body:
    upload:
      id: 7
      token: "7.ed32257a2ab0f7526c0d72c32994c58b131bb2c0775f7aa84aae01ea8397ea54"
  error: ""
  

• redmine_attachment_image

  • 获取图像附件（例如，在问题描述中以 !screenshot.png! 引用的内嵌截图），并将其作为可查看的图像内容返回，让大模型能够实际查看
  • 输入：attachment_id（整数）
  • 成功时返回图像内容（最大 5 MB，仅限图像），失败时返回 YAML 错误字符串

• redmine_download

  • 从 Redmine 下载附件并保存到本地文件
  • 需要设置 REDMINE_ALLOWED_DIRECTORIES
  • 输入：
    • attachment_id（整数）：要下载的附件 ID
    • save_path（字符串）：用于保存文件的完整文件路径（不是目录，且必须位于允许的目录中）
    • filename（字符串，可选）：Redmine 下载 URL 的可选文件名（若未提供，则根据附件元数据自动确定）
  • 返回包含下载结果的 YAML 字符串：

  status_code: 200
  body:
    saved_to: "/path/to/downloaded/file.pdf"
    filename: "file.pdf"
  error: ""
  

示例

创建新问题

Let's create a new bug report in the "Website" project:

1. Title: "Homepage not loading on mobile devices"
2. Description: "When accessing the homepage from iOS or Android devices, the loading spinner appears but the content never loads. This issue started after the last deployment."
3. Priority: High
4. Assign to: John Smith

搜索问题

Can you find all high priority issues in the "Website" project that are currently unassigned?

更新问题状态

Please mark issue #123 as "In Progress" and add a comment: "I've started working on this issue. Expect it to be completed by Friday."

记录工时

Log 3.5 hours against issue #456 for "Implementing user authentication" done today.

MCP 目录收录

MCP Redmine 已收录于以下 MCP 目录网站和代码仓库：

• MCP.so
• Glama

开发

首先克隆 GitHub 代码仓库并安装依赖项：

git clone [email protected]:runekaagaard/mcp-redmine.git
cd mcp-redmine
uv sync

然后在 claude_desktop_config.json 中设置：

...
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-redmine", "-m", "mcp_redmine.server"],
...

我的其他大模型项目

• MCP Alchemy - 将 Claude Desktop 连接到数据库，以探索架构并运行 SQL。
• MCP Notmuch Sendmail - 使用 notmuch 为 Claude Desktop 提供邮件助手。
• MCP Show-on-Kindle - 将文件复制到运行 KOReader 的 Kindle 并在屏幕上打开。
• Diffpilot - 支持文件分组和标记的多列 git 差异查看器。
• Claude Local Files - 在 Claude Desktop 作品中访问本地文件。

贡献

欢迎踊跃贡献！无论是错误报告、功能请求、文档改进还是代码贡献，所有意见都很有价值。欢迎：

• 提交问题以报告错误或建议功能
• 提交包含改进内容的拉取请求
• 改进文档或分享使用示例
• 提问并分享体验

我们的目标是让 Claude 的 Redmine 项目管理体验更出色，你的见解和贡献将助力实现这一目标。

致谢

本项目基于其他优秀项目的成果构建：

• httpx - 用于处理 HTTP 请求
• Redmine OpenAPI Specification - 提供全面的 API 规范
• Redmine - 灵活的项目管理 Web 应用程序

许可证

Mozilla Public License Version 2.0