redmine-mcp

一个用于 Redmine 的无状态 Model Context Protocol 服务器。将其部署在任何 Redmine 实例前端，即可让 Claude（或任何支持 MCP 的 LLM 客户端）代表用户读取和创建工单、记录时间、浏览 Wiki 以及搜索项目，且每个用户均使用其自己的 API 密钥。

• 零状态：无数据库、无会话、无共享密钥。服务器使用随请求附带的 API 密钥将每个请求转发给 Redmine。

• 一机多用户：操作员唯一需要配置的就是上游 REDMINE_URL。每个 MCP 客户端提供自己的 X-Redmine-API-Key。权限完全遵循 Redmine 的设置。

• 覆盖范围：工单（CRUD + 备注）、项目、成员资格、用户、时间记录、Wiki（PUT-upsert）、附件（上传 + 下载）、全文搜索、状态、跟踪器、类别、自定义字段、枚举。

快速开始

本地 (uv)

uv sync
REDMINE_URL=https://redmine.example.com uv run redmine-mcp

MCP 端点现位于 http://127.0.0.1:8080/mcp。

容器 (GHCR)

docker run --rm -p 8080:8080 \
  -e REDMINE_URL=https://redmine.example.com \
  ghcr.io/kalvadtech/redmine-mcp:latest

该镜像为多阶段 Alpine 构建，以非 root 用户身份运行，并暴露 8080 端口。

Related MCP server: Redmine MCP Server

连接到您的 MCP 客户端

在 我的账号 > API 访问密钥 中找到您的 Redmine API 密钥。以下两个客户端均通过流式 HTTP 与同一个 MCP 端点通信；无需其他客户端配置。

Claude Code

项目根目录下的 .mcp.json：

{
  "mcpServers": {
    "redmine": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "X-Redmine-API-Key": "your-40-char-key"
      }
    }
  }
}

opencode

项目根目录（或您的 opencode 配置目录）下的 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "redmine": {
      "type": "remote",
      "url": "http://127.0.0.1:8080/mcp",
      "enabled": true,
      "headers": {
        "X-Redmine-API-Key": "{env:REDMINE_API_KEY}"
      }
    }
  }
}

opencode 支持在 headers 中进行 {env:VAR} 插值，因此 API 密钥不会出现在配置文件中：REDMINE_API_KEY=... opencode。

配置

redmine-mcp 的 CLI 标志：

--host        bind address (default 127.0.0.1)
--port        port (default 8080)
--log-level   uvicorn log level (default info)

如果缺少 REDMINE_URL 或其不是 http(s) 协议，服务器将在启动时快速失败。

认证模型

Redmine URL 不是由用户提供的；它通过 REDMINE_URL 在部署时固定。这消除了 SSRF 风险：客户端无法将服务器指向任意主机。

客户端发送的唯一凭据是其在 X-Redmine-API-Key 请求头中的 Redmine API 密钥。服务器将其作为相同的请求头转发给 Redmine（因此它不会作为查询字符串出现在 Redmine 访问日志中），使用它发起一次请求，然后将其丢弃。不存在缓存、共享服务账号或模拟行为。

工具

59 个工具涵盖了 Redmine 通过其 REST API 暴露的所有资源系列。列表工具返回 {items, total_count, limit, offset} 以方便分页。

工单

• list_issues (项目、状态、指派人、跟踪器、类别、版本、保存的查询、自由文本查询、排序、包含项)

• get_issue (包含项：日志、附件、关联、子任务、关注者)

• create_issue (包含 uploads 令牌、custom_fields、watcher_user_ids)

• update_issue (包含 notes、private_notes)

• add_issue_note (轻量封装)

• delete_issue

工单关联

• list_issue_relations, get_relation, create_issue_relation (关联 / 阻塞 / 前置 / 等，前置/后置带有 delay)， delete_relation

日志 (工单备注)

• update_journal_note - 编辑现有备注的文本或隐私设置。使用 add_issue_note 添加新备注。

项目和版本

• list_projects, get_project

• list_versions, get_version, create_version, update_version, delete_version

成员资格

• list_memberships, get_membership, add_project_member (用户或 组), update_membership, remove_membership

用户、我的账号、组、角色

• list_users, get_user (接受字面字符串 "current")

• get_my_account, update_my_account

• list_groups, get_group, create_group, update_group, delete_group, add_user_to_group, remove_user_from_group

• list_roles, get_role (包含权限)

时间记录

• list_time_entries (日期范围、用户、项目、工单)

• create_time_entry (工单或项目、工时、活动、spent_on、备注)

• update_time_entry, delete_time_entry

Wiki

• list_wiki_pages, get_wiki_page (带版本)

• create_or_update_wiki_page (PUT-upsert)

• delete_wiki_page

附件和文件

• get_attachment, download_attachment (上限 25 MiB，base64 输出)

• upload_attachment (返回一个令牌，用于在 create_issue / update_issue 时通过 uploads 附加)

• list_files, upload_file (一次性上传 + 附加到项目的“文件”区域，带有可选的 version_id 和描述)

新闻、查询、搜索和元数据

• list_news (跨项目或单个项目)

• list_queries (保存的查询；将 id 作为 query_id 传递给 list_issues)

• search (跨工单、新闻、文档、Wiki 等的全文搜索)

• list_issue_statuses, list_trackers, list_issue_categories, list_custom_fields

• list_issue_priorities, list_time_entry_activities, list_document_categories

部署

对于单个 Redmine 实例，每个环境运行一个容器：

docker run -d --name redmine-mcp \
  --restart unless-stopped \
  -p 8080:8080 \
  -e REDMINE_URL=https://redmine.example.com \
  ghcr.io/kalvadtech/redmine-mcp:latest

将其放置在您常用的反向代理和 TLS 终止服务之后。MCP 协议在服务器端仅支持 HTTP；用户通过您的代理获得 TLS。

对于多个 Redmine 实例，每个实例运行一个容器，配置各自的 REDMINE_URL，并在代理处按主机名/路径进行路由。

开发

uv sync
uv run pytest
uv run ruff check .
uv run mypy src

测试套件完全离线，并使用 respx 来模拟 Redmine HTTP API。没有针对实时 Redmine 的集成测试；请自行准备。

贡献

欢迎提交 Pull Request。请：

• 遵循 Conventional Commits，

• 保持更改简洁且范围明确（每个提交一个逻辑更改），

• 为任何行为更改添加或更新测试，

• 在打开 PR 之前运行 pytest、ruff 和 mypy 并确保通过。

许可证

MIT (c) 2026 Kalvad。