redmine-mcp-server

当 REDMINE_AUTOFILL_REQUIRED_CUSTOM_FIELDS=true 时，create_redmine_issue 会在遇到相关自定义字段验证错误时重试一次（例如 <Field Name> cannot be blank 或 <Field Name> is not included in the list），并且只从以下来源填充值：

• Redmine 自定义字段的 default_value，或
• REDMINE_REQUIRED_CUSTOM_FIELD_DEFAULTS

实际上只有第二种来源会生效。服务会通过 GET /projects/{id}.json?include=issue_custom_fields 读取项目自定义字段，而 Redmine 返回的内容只有 id 和名称，因此服务永远无法获取 default_value——详见 list_project_issue_custom_fields。如果希望自动填充能发挥作用，请设置环境变量映射。

示例：

REDMINE_AUTOFILL_REQUIRED_CUSTOM_FIELDS=true
REDMINE_REQUIRED_CUSTOM_FIELD_DEFAULTS='{"Required Field A":"Value A","Required Field B":"Value B"}'

如果 Redmine 服务使用自签名证书或内部 CA：

# In .env file
REDMINE_URL=https://redmine.company.com
REDMINE_API_KEY=your_api_key
REDMINE_SSL_CERT=/path/to/ca-certificate.crt

支持的证书格式：.pem、.crt、.cer

对于需要客户端证书身份验证的环境：

# In .env file
REDMINE_URL=https://secure.redmine.com
REDMINE_API_KEY=your_api_key
REDMINE_SSL_CERT=/path/to/ca-bundle.pem
REDMINE_SSL_CLIENT_CERT=/path/to/cert.pem,/path/to/key.pem

注意：私钥必须未加密（Python requests 库的要求）。

⚠️ 警告：仅在开发/测试环境中使用！

# In .env file
REDMINE_SSL_VERIFY=false

禁用 SSL 验证会使连接容易受到中间人攻击。

每个 MCP 请求都携带自己的 Authorization: Bearer <token>，因此每位用户都使用自己的 Redmine 账户进行身份验证。服务会先通过 Doorkeeper 的 introspection 端点验证每个令牌，再转发请求，并提供客户端所需的 OAuth2 发现端点和 /revoke 端点。

REDMINE_AUTH_MODE=oauth
REDMINE_URL=https://redmine.example.com
REDMINE_MCP_BASE_URL=https://redmine-mcp.example.com   # public URL of this server

# Confidential OAuth app registered in Redmine admin (see setup guide)
REDMINE_INTROSPECT_CLIENT_ID=...
REDMINE_INTROSPECT_CLIENT_SECRET=...

你需要在 Redmine 管理后台 → Applications 中手动注册 OAuth 应用（不支持 Dynamic Client Registration）。完整操作步骤、端点参考和故障排查指南，请参阅：OAuth2 Setup Guide。

FastMCP 充当面向 MCP 的授权服务器：为 MCP 客户端处理 DCR，然后将用户重定向至 Redmine，由其作为上游 OAuth 提供方处理授权。适用于期望自行注册的客户端（例如 Claude Desktop、VS Code）。

REDMINE_AUTH_MODE=oauth-proxy
REDMINE_URL=https://redmine.example.com
REDMINE_MCP_BASE_URL=https://redmine-mcp.example.com   # public URL of this server

# Confidential OAuth app registered in Redmine admin (see setup guide)
REDMINE_INTROSPECT_CLIENT_ID=...
REDMINE_INTROSPECT_CLIENT_SECRET=...
REDMINE_MCP_JWT_SIGNING_KEY=...

上游 Redmine 应用必须将 ${REDMINE_MCP_BASE_URL}/auth/callback 注册为其重定向 URI。有关存储、扩展和凭据复用的说明，请参阅 OAuth2 Setup Guide。

服务充当自己的 OAuth 授权服务器，因此 MCP 客户端只需使用服务 URL 即可连接。首次使用时，客户端会打开浏览器，用户将自己的 Redmine API 密钥粘贴到此服务提供的页面中；此后每次工具调用都会以该用户的身份运行。客户端配置中无需填写任何密钥，也不会要求输入密码。

REDMINE_AUTH_MODE=api-key-login
REDMINE_URL=https://redmine.example.com
REDMINE_MCP_BASE_URL=https://redmine-mcp.example.com   # public https URL of this server
REDMINE_MCP_JWT_SIGNING_KEY=...                        # encrypts the stored keys

服务会将每位用户的密钥加密后存储在 FASTMCP_HOME/api-key-login/ 下，因此该目录需要持久化卷，并且此模式只能运行单个副本。此处的 OAuth 作用域用于缩小客户端请求的权限范围，并非 Redmine 权限；权限边界仍由 Redmine 自身的权限决定。启用此模式前，请阅读 api-key-login guide，了解安全模型、会话规则和客户端设置。

对于不支持 OAuth 的旧版 Redmine，每位用户的 MCP 客户端都会在 X-Redmine-API-Key 标头中发送自己的 Redmine API 密钥。每个请求都以该用户的身份及其权限运行。

这是高级的可选模式。 此模式要求端到端使用 TLS，并正确配置反向代理。启用前，请阅读 docs/legacy-per-user-auth.md，了解威胁模型、防火墙指南和密钥撤销操作手册。

mcp-remote（推荐）：

{ "mcpServers": { "redmine": {
  "command": "npx",
  "args": ["mcp-remote", "https://your-host/mcp",
           "--header", "X-Redmine-API-Key:${RM_KEY}"],
  "env": { "RM_KEY": "<your redmine api key>" }
}}}

注意，X-Redmine-API-Key:${RM_KEY} 中的冒号两侧没有空格。这样可以避免 Cursor 和 Claude Desktop 在 Windows 上的参数转义错误。

VS Code（mcp.json）：

使用 .vscode/mcp.json（工作区文件）或用户配置文件中的 mcp.json。工作区的 .mcp.json 会静默丢弃 headers（参见 microsoft/vscode#319528），因此请勿使用该文件。VS Code 版本请使用 1.102 或更高版本。

{
  "servers": {
    "redmine": {
      "type": "http",
      "url": "https://your-host/mcp",
      "headers": { "X-Redmine-API-Key": "${input:rmKey}" },
      "inputs": [{ "id": "rmKey", "type": "promptString",
                   "description": "Redmine API key", "password": true }]
    }
  }
}

**不支持：**无法设置自定义请求标头的客户端，或将 Authorization 标头保留给自身 OAuth 流程使用的客户端。

VS Code 通过 GitHub Copilot 内置了 MCP 支持（需要 VS Code 1.102+）。

使用 CLI（最快）：

code --add-mcp '{"name":"redmine","type":"http","url":"http://127.0.0.1:8000/mcp"}'

使用命令面板：

1. 打开命令面板（Cmd/Ctrl+Shift+P）
2. 运行 MCP: Open User Configuration（用于全局配置）或 MCP: Open Workspace Folder Configuration（用于项目专属配置）
3. 添加以下配置：

   {
     "servers": {
       "redmine": {
         "type": "http",
         "url": "http://127.0.0.1:8000/mcp"
       }
     }
   }
   

4. 保存文件。VS Code 将自动加载 MCP 服务。

手动配置： 在工作区中创建 .vscode/mcp.json（或在用户配置文件目录中创建 mcp.json）：

{
  "servers": {
    "redmine": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

使用 CLI 命令将其添加到 Claude Code：

claude mcp add --transport http redmine http://127.0.0.1:8000/mcp

或者在 Claude Code 设置文件（~/.claude.json）中手动配置：

{
  "mcpServers": {
    "redmine": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Claude Desktop 的配置文件仅支持 stdio 传输。使用 FastMCP 的代理通过 uv 连接到此 HTTP 服务。

设置：

1. 打开 Claude Desktop
2. 点击 Claude 菜单（macOS 菜单栏 / Windows 标题栏）> Settings...
3. 点击 Developer 选项卡 > Edit Config
4. 添加以下配置：

{
  "mcpServers": {
    "redmine": {
      "command": "uv",
      "args": [
        "run",
        "--with", "fastmcp",
        "fastmcp",
        "run",
        "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}

5. 保存文件，然后完全退出并重启 Claude Desktop
6. 查看输入区域中的工具图标，以确认连接成功

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

注意： 启动 Claude Desktop 前，Redmine MCP 服务必须处于运行状态。

Cursor 可直接连接 HTTP MCP 服务，无需桥接。

1. 创建 ~/.cursor/mcp.json（在每个项目中均可使用），或在项目根目录中创建 .cursor/mcp.json（仅适用于该项目）：

   {
     "mcpServers": {
       "redmine": {
         "url": "http://127.0.0.1:8000/mcp"
       }
     }
   }
   

2. 保存文件。Cursor 会自动加载该服务；其 MCP 设置会列出该服务及其加载的工具。

注意： 与上面的 VS Code 和 Claude Code 配置不同，Cursor 使用不带其他字段的 url 来标识远程服务，并且没有 type 字段。

在 legacy-per-user 模式下，添加 API 密钥标头：

{
  "mcpServers": {
    "redmine": {
      "url": "https://your-host/mcp",
      "headers": { "X-Redmine-API-Key": "<your redmine api key>" }
    }
  }
}

在 oauth 模式下，在 MCP 服务上设置 REDMINE_OAUTH_DISCOVERY_AS=self。Cursor 会在其自身的规范 well-known 位置查找授权服务元数据，而默认的 redmine 发现配置不提供该元数据，因此如果不设置此项，授权流程会停滞（#188）。请参阅 Cursor 和 self-AS 发现。

使用以下命令将其添加到 Codex CLI：

codex mcp add redmine -- npx -y mcp-client-http http://127.0.0.1:8000/mcp

或者在 ~/.codex/config.toml 中手动配置：

[mcp_servers.redmine]
command = "npx"
args = ["-y", "mcp-client-http", "http://127.0.0.1:8000/mcp"]

注意： Codex CLI 主要支持基于 stdio 的 MCP 服务。上述配置使用 mcp-client-http 作为 HTTP 传输的桥接工具。

Kiro 主要支持基于 stdio 的 MCP 服务。对于 HTTP 服务，请使用 HTTP 到 stdio 的桥接工具：

1. 在工作区中创建或编辑 .kiro/settings/mcp.json：

   {
     "mcpServers": {
       "redmine": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-client-http",
           "http://127.0.0.1:8000/mcp"
         ],
         "disabled": false
       }
     }
   }
   

2. 保存文件并重启 Kiro。Redmine 工具将显示在 MCP 面板中。

注意： Kiro 对直接 HTTP 传输的支持有限。上述配置使用 mcp-client-http 作为桥接工具来连接 HTTP MCP 服务。

大多数 MCP 客户端都使用标准配置格式。对于 HTTP 服务：

{
  "mcpServers": {
    "redmine": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

对于需要通过 HTTP 桥接工具使用命令方式的客户端：

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "mcp-client-http", "http://127.0.0.1:8000/mcp"]
    }
  }
}

核心工具（53 个，始终可用）

这些工具只需要 Redmine 实例和凭据，无需额外插件或功能标志。

• 项目管理（10 个工具）

  • list_redmine_projects - 列出可访问的项目（除非 filters 要求查看更多，否则仅列出活动项目）；在服务端缩小范围，并可选择分页
  • list_project_issue_custom_fields - 列出为项目配置的问题自定义字段
  • list_redmine_versions - 列出项目的版本 / 里程碑
  • manage_redmine_version - 创建、更新或删除版本 / 里程碑
  • manage_redmine_project - 创建项目、编辑其设置，或关闭并重新打开项目
  • list_project_members - 列出项目成员及其角色
  • summarize_project_status - 获取全面的项目状态摘要
  • list_redmine_roles - 列出 Redmine 实例中定义的所有角色（用于查找有效的 role_ids）
  • get_project_modules - 获取项目已启用的模块
  • manage_project_member - 添加、更新或移除项目成员

• 问题操作（13 个工具）

  • get_redmine_issue - 获取详细的问题信息（支持日志分页、关注者、关联关系和子问题）
  • list_redmine_issues - 使用灵活的筛选条件列出问题（项目、状态、指派人等）
  • search_redmine_issues - 按文本查询搜索问题
  • create_redmine_issue - 创建新问题，可通过 uploads 参数选择性地附加文件
  • update_redmine_issue - 更新现有问题，可通过 uploads 参数选择性地附加文件（与 notes 结合使用可将文件附加到日志备注）
  • delete_redmine_issue - 永久删除问题；不可撤销地删除前，必须提供确认标记并预览级联影响。
  • copy_issue - 复制现有问题，可选择性地覆盖字段
  • list_subtasks - 列出指定父问题的子任务（子问题）
  • get_private_notes - 获取问题的私人备注
  • manage_issue_relation - 列出、创建或删除问题关联关系
  • manage_issue_watcher - 添加或移除问题的关注者
  • manage_issue_note - 编辑日志备注文本或切换其隐私设置
  • manage_issue_category - 列出、创建、更新或删除问题类别
  • 注意：get_redmine_issue 可包含 custom_fields，而 update_redmine_issue 可按名称更新自定义字段（例如 {"size": "S"}）。

• 时间跟踪（4 个工具）

  • list_time_entries - 按项目、问题、用户和日期范围筛选并列出工时记录
  • manage_time_entry - 创建或更新工时记录（使用 user_id 可代其他用户记录工时）
  • list_time_entry_activities - 查询工时记录可用的活动类型
  • import_time_entries - 通过顺序调用 API 批量导入工时记录，并逐条报告错误

• 发现 / 枚举（7 个工具）：帮助 LLM 在调用创建 / 更新工具前查找有效 ID

  • list_redmine_trackers - 列出所有跟踪器（Bug、Feature、Support 等）
  • list_project_trackers - 列出特定项目启用的跟踪器
  • list_redmine_issue_statuses - 列出所有问题状态及其 is_closed 标记
  • list_redmine_issue_priorities - 列出所有优先级
  • list_redmine_users - 筛选 / 列出用户（仅限管理员；支持按名称和用户组筛选）
  • get_current_user - 获取已认证用户的个人资料（非管理员也可使用）
  • list_redmine_queries - 列出已保存的自定义查询（只读）

• 搜索与 Wiki（2 个工具）

  • search_entire_redmine - 全局搜索问题和 Wiki 页面（Redmine 3.3.0+）
  • manage_redmine_wiki_page - 列出、获取、创建、更新、删除或重命名 Wiki 页面

• 新闻（4 个工具）：项目公告——发布说明、维护时段

  • list_redmine_news - 列出新闻，可选择指定项目
  • get_redmine_news - 查看一条新闻及其评论和附件
  • manage_redmine_news - 创建或更新新闻（Redmine 4.1+）
  • delete_redmine_news - 删除新闻，需要确认（Redmine 4.1+）

• 文件操作（5 个工具）

  • list_files - 列出上传到项目“文件”版块的文件
  • create_upload_ticket - 预留上传位置并返回一次性 URL，使调用方机器上的文件能够传到服务端，而无需将文件字节传经模型
  • upload_file - 将新文件上传到项目（来源可以是暂存的 upload_id、URL、base64 内容或服务端的 file_path），也可选择关联到某个版本
  • delete_file - 从项目中删除文件
  • get_redmine_attachment - 下载附件（HTTP 和 stdio 模式均可使用）

• 甘特图（1 个工具）

  • get_gantt_chart - 获取项目时间线数据：包含日期、依赖关系和里程碑的事项

• 交互式应用（4 个工具）：通过 MCP Apps 扩展在聊天中呈现实时 UI（需要客户端支持）

  • show_triage_board - 将项目事项呈现为按状态分组的交互式看板，并支持拖动以更改状态并回写
  • get_triage_board_data - 为看板的刷新操作提供数据源
  • show_project_dashboard - 将项目实时快照（未关闭/已关闭、逾期、本周到期、按优先级统计的未关闭事项、近期活动）呈现为交互式仪表板，并可点击深入查看匹配的事项列表
  • get_project_dashboard_data - 仅供应用使用的数据源，为仪表板的刷新操作提供数据
  • show_project_timeline - 将项目计划呈现为交互式时间线：按版本显示事项条形图、里程碑菱形图标和“今天”标线
  • get_project_timeline_data - 仅供应用使用的数据源，为时间线的刷新操作提供数据

• 元信息（1 个工具）

  • get_mcp_server_info - 报告服务版本、认证模式、只读状态、已认证用户（current_user），以及已启用的插件门控工具类别。可用于在依赖近期发布的修复前检测部署是否滞后，或确认 assigned_to_id="me" 对应的用户。

插件门控工具（15 个，通过环境变量启用）

这些工具要求服务端安装相应的 Redmine 插件，并且在 MCP 服务上将对应的环境变量设为 true。只有设置了标志时，它们才会列在 tools/list 中；关闭标志后，它们不会注册到 MCP 接口上（直接调用仍会返回功能未启用错误）。

• 检查清单（3 个工具）：设置 REDMINE_CHECKLISTS_ENABLED=true；需要安装 RedmineUP Checklists Pro 插件

  • get_checklist - 获取问题的所有检查清单项
  • create_checklist_item - 为问题添加新的检查清单项
  • update_checklist_item - 更新检查清单项的文本、完成状态或位置

• 产品（1 个工具）：设置 REDMINE_PRODUCTS_ENABLED=true；需要安装 RedmineUP Products 插件

  • manage_product - 列出、获取、创建或更新产品

• 联系人（CRM）（2 个工具）：设置 REDMINE_CRM_ENABLED=true；需要安装 RedmineUP CRM 插件。在 OAuth 模式下，此标志还会将 CRM 权限添加到公布的作用域中，因此请在 OAuth 应用程序中授予这些权限，并让用户重新授权。在 Pro 安装中设置 REDMINE_CRM_EDITION=pro，以允许联系人 list 筛选器；Light 版本不会注册这些筛选器

  • manage_contact - 列出、获取、创建、更新、删除联系人，或分配/移除联系人与项目的关联
  • list_contact_tags - 获取联系人正在使用的标签及其颜色，供 tags 筛选器和 tag_list 使用

• 交易（CRM）（3 个工具）：设置 REDMINE_DEALS_ENABLED=true；需要安装同一 CRM 插件的 Pro 版本，并在项目中启用 deals 项目模块。交易使用独立标志，因为 Light 版本未定义任何交易权限，公布这些权限会导致 Light 部署无法完成授权

  • manage_deal - 列出、获取、创建、更新或删除交易
  • list_deal_statuses - 获取交易状态（仅限插件端管理员）及项目的交易类别，供创建交易前使用
  • manage_deal_category - 列出、创建、重命名或删除项目的交易类别

• CRM 备注和已保存查询（2 个共享工具）：设置 REDMINE_CRM_ENABLED 或 REDMINE_DEALS_ENABLED 后即可使用；每次调用都会根据备注或查询的来源检查对应标志

  • manage_crm_note - 获取、创建、更新或删除联系人和交易上的 CRM 备注
  • list_crm_queries - 获取已保存的联系人或交易查询

• 交易产品条目（1 个工具）：需要同时设置 REDMINE_DEALS_ENABLED=true 和 REDMINE_PRODUCTS_ENABLED=true；只有在 CRM 旁安装了 Products 插件时，该端点才存在

  • add_deal_product - 向交易添加目录产品或自定义产品条目

• 文档（DMSF）（1 个工具）：设置 REDMINE_DMSF_ENABLED=true；需要安装 redmine_dmsf 插件

  • manage_document - 列出、获取、创建（上传）或更新（新修订版）DMSF 文档

• Helpdesk（1 个工具）：设置 REDMINE_HELPDESK_ENABLED=true；需要安装 RedmineUP Helpdesk 插件

  • send_helpdesk_email_reply - 向 Helpdesk 工单的客户发送电子邮件回复，可选择同时更改工单状态

• Helpdesk 工单（1 个工具）：设置 REDMINE_HELPDESK_TICKETS_ENABLED=true；需要安装 RedmineUP Helpdesk 插件和 RedmineUP CRM 插件

  • manage_helpdesk_ticket - 读取工单的 Helpdesk 数据，或将其移至另一个现有联系人

运维工具（1 个，需管理员权限）

默认情况下不会显示在 tools/list 中。设置 REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true 可在 MCP 接口中注册这些工具。无论此标志如何设置，底层后台任务都会运行；公开这些工具只会增加通过 MCP 驱动这些任务的选项。

• cleanup_attachment_files - 手动触发清理过期附件文件（无论如何，后台清理任务都会自动运行）