Redmine MCP 服务器插件

Redmine MCP服务器插件

一个Redmine插件，它公开了一个模型上下文协议（MCP）服务器，使AI助手能够与您的Redmine安装进行交互。该插件允许人工智能工具通过标准化协议读取和管理问题、项目、维基页面、时间条目等。

概述

Redmine MCP Server插件将您的Redmine实例转换为MCP兼容服务器，允许AI助手：

• 浏览和搜索问题、项目和wiki页面
• 在全面的现场支持下创建和更新问题
• 记录问题和项目的时间条目
• 访问用户配置文件和项目元数据
• 使用实时Redmine数据生成结构化报告
• 使用预构建的提示模板进行常见工作流

所有操作都尊重Redmine的权限系统，确保AI助手只访问经过身份验证的用户可以看到的数据。

特性

• 49综合工具 用于问题管理、项目导航、时间跟踪、wiki编辑、附件、元数据查询和管理员配置
• 5个智能提示 内嵌实时数据，用于错误报告、状态报告、冲刺摘要和发布说明
• 6资源模板 通过URI模式实现高效的数据访问
• HTTP+SSE传输 完全符合MCP协议
• API密钥验证 使用标准Redmine API密钥
• 基于权限的访问 -尊重所有Redmine权限和可见性规则
• 速率限制 防止AI循环失控
• 写保护 -可选地将AI限制为只读操作
• 无外部依赖关系 -仅使用Ruby标准库

需求

• 雷德明： 5.0或更高
• 红宝石： 2.7或更高
• MCP客户端： 任何兼容MCP的客户端

安装

1. 下载插件：

   复制

   cd /path/to/redmine/plugins
   git clone https://github.com/Toblias/redmine_mcp.git
   

2. 重新启动Redmine：

   复制

   # For Passenger
   touch /path/to/redmine/tmp/restart.txt
   
   # For Puma/Unicorn
   systemctl restart redmine
   

3. 配置插件：

   • 引导到 管理>插件>Redmine MCP服务器>配置
   • 启用MCP服务器
   • 根据需要配置速率限制和超时
   • 可选地启用写入操作（默认情况下为安全起见禁用）

配置

管理设置

访问插件设置 管理>插件>Redmine MCP服务器>配置:

安全注意事项

1. 写入操作： 默认情况下禁用。启用后，AI助手可以创建/修改数据。仅对受信任的用户启用。
2. API密钥： 为MCP客户端使用专用的API密钥。定期旋转按键。
3. 速率限制： 防止AI发出过多请求。根据您的服务器容量进行调整。
4. 权限： 所有操作都尊重Redmine权限。用户只能访问他们有权查看的数据。

初始设置检查表

在使用MCP插件创建问题之前，请确保您的Redmine实例已配置以下内容：

所需配置

这些项目是创建问题所必需的：

• [ ] 问题状态 -至少一个状态（例如，新建、进行中、已关闭）
• [ ] 问题跟踪 -至少一个跟踪器（例如，Bug、功能、任务）
• [ ] 问题优先级 -至少一个优先级（例如，低、正常、高）
• [ ] 时间输入活动 -至少一项用于时间跟踪的活动（例如，开发、设计）

可选配置

• [ ] 问题类别 -按项目分类
• [ ] 版本/里程碑 -按项目发布跟踪

通过MCP快速设置（仅限管理员）

如果你的Redmine是新安装的，你可以使用管理工具来设置基础知识：

1. create_status   - Create "New", "In Progress", "Closed" statuses
2. create_tracker  - Create "Bug", "Feature", "Task" trackers (requires statuses first)
3. create_priority - Create "Low", "Normal", "High", "Urgent" priorities
4. create_activity - Create "Development", "Design", "Testing" activities

工作流程示例：

# First, create statuses (required for trackers)
create_status(name: "New", is_closed: false)
create_status(name: "In Progress", is_closed: false)
create_status(name: "Closed", is_closed: true)

# Then create trackers (requires a default status)
create_tracker(name: "Bug", default_status_id: 1)
create_tracker(name: "Feature", default_status_id: 1)

# Create priorities
create_priority(name: "Low")
create_priority(name: "Normal", is_default: true)
create_priority(name: "High")

# Create activities for time tracking
create_activity(name: "Development", is_default: true)
create_activity(name: "Design")

MCP端点

该插件在您的Redmine基本URL上公开了一个MCP端点：

端点

认证

所有请求（除 /mcp/health)需要通过身份验证 X-Redmine-API-Key 头球

# Health check (no authentication required)
curl https://redmine.example.com/mcp/health

# MCP requests require API key
curl -X POST \
     -H "X-Redmine-API-Key: your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"ping","id":1}' \
     https://redmine.example.com/mcp

生成API密钥：

1. 登录Redmine
2. 首选 我的账户 （右上）
3. 点击 展示 在“API访问密钥”下（如果不存在，则生成）
4. 复制密钥以在MCP客户端配置中使用

工具

该插件提供49个工具，按类别组织：

问题工具（8）

项目工具（5）

时间输入工具（4）

维基工具（3）

用户工具（3）

附件工具（2）

实用工具（6）

管理工具-跟踪器（3）

管理工具-状态（3）

管理工具-优先级（3）

管理工具-活动（3）

分类工具（3）

版本工具（3）

有关详细的参数文档和示例，请参阅 docs/TOOLS.md.

提示

该插件包括5个嵌入实时Redmine数据的智能提示模板：

例子： 这 status_report prompt查询您的实际问题数据并生成如下消息：

为项目“我的项目”生成一份涵盖过去2周的状态报告。

数据摘要：

• 已结束的问题：12
• 已打开的问题：8
• 活跃问题：45

然后，人工智能将其格式化为专业状态更新。

资源模板

该插件使用AI助手可以按需构建的URI模板，而不是枚举数千个单独的资源：

MCP客户端配置

有关详细的客户端设置说明，包括桌面、游标IDE和故障排除，请参阅 docs/MCP_CLIENT_SETUP.md.

快速入门-通用MCP客户端

添加到MCP客户端配置中：

{
  "mcpServers": {
    "redmine": {
      "transport": "sse",
      "url": "https://redmine.example.com/mcp",
      "headers": {
        "X-Redmine-API-Key": "your_api_key_here"
      }
    }
  }
}

快速入门-桌面

添加到 ~/Library/Application Support/Desktop/config.json （macOS）或 %APPDATA%/Desktop/config.json （Windows）：

{
  "mcpServers": {
    "redmine": {
      "transport": "sse",
      "url": "https://your-redmine.example.com/mcp",
      "headers": {
        "X-Redmine-API-Key": "your_api_key_here"
      }
    }
  }
}

配置后，重新启动应用程序。AI助手现在将能够访问您的Redmine实例。

有关详细的设置说明、故障排除和其他MCP客户端，请参阅 docs/MCP_CLIENT_SETUP.md.

服务器配置

对于生产部署，您可能需要配置web服务器以正确处理SSE连接。看 docs/CONFIGURATION.md 用于：

• SSE代理的Nginx配置
• Apache配置
• 彪马/乘客注意事项
• web服务器级别的速率限制

分页

全部 list_* 工具返回分页元数据，以帮助AI助手理解结果集：

{
  "content": [{"type": "text", "text": "[... results ...]"}],
  "isError": false,
  "_meta": {
    "total": 142,
    "limit": 25,
    "offset": 0,
    "has_more": true
  }
}

这 _meta 字段使用下划线前缀（非MCP扩展名）来提供分页上下文。AI助手可以检查 has_more 以确定是否存在其他页面。

故障排除

MCP端点返回404

• 验证插件是否安装在 plugins/redmine_mcp
• 安装后重新启动Redmine
• 查看Rails日志 log/production.log 路由错误

身份验证失败

• 验证您的API密钥是否正确（检查我的帐户>API访问密钥）
• 确保密钥已发送至 X-Redmine-API-Key 头球
• 检查用户帐户是否处于活动状态且未锁定

SSE连接立即关闭

• 检查您的web服务器配置（Nginx可能需要 X-Accel-Buffering: no)
• 验证防火墙/代理是否允许长期连接
• 审查 sse_timeout 设置（默认值：3600秒）
• 检查Redmine日志中的连接错误

速率限制错误

• 增加插件设置中的速率限制（管理>插件）
• 检查多个MCP客户端是否使用相同的API密钥
• 查看Rails日志中最近的请求模式

写入操作失败

• 验证插件设置中是否选中了“启用写入操作”
• 确认用户具有适当的权限（例如。， add_issues, edit_issues)
• 检查项目是否启用了所需的模块（wiki、时间跟踪）

工具返回空结果

• 验证用户是否有权查看请求的数据
• 检查项目可见性设置
• 确保项目模块已启用（维基、时间跟踪等）
• 查看用户角色的Redmine权限

性能问题

• 减少 default_limit 和 max_limit 在设置中减小页面大小
• 使用特定的过滤器（project_id、日期范围）来缩小查询范围
• 如果搜索速度较慢，请考虑添加数据库索引
• 在人工智能操作期间监控服务器资源

发展

运行测试

cd /path/to/redmine
bundle exec rake redmine:plugins:test NAME=redmine_mcp

添加自定义工具

1. 在中创建新的工具类 lib/redmine_mcp/tools/
2. 从……继承…… RedmineMcp::Tools::Base
3. 实施所需方法： tool_name, description, execute
4. 注册 RedmineMcp::Registry.register_tool(YourTool)
5. 重新启动Redmine

有关示例，请参阅现有工具。

添加自定义提示

1. 在中创建新的提示类 lib/redmine_mcp/prompts/
2. 从……继承…… RedmineMcp::Prompts::Base
3. 实施所需方法： prompt_name, description, execute
4. 注册 RedmineMcp::Registry.register_prompt(YourPrompt)
5. 重新启动Redmine

版本历史

看 更改日志.md 查看详细的版本历史。

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 提交拉取请求

许可证

此插件根据MIT许可证获得许可。

MIT License

Copyright (c) 2025 Redmine MCP Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

支持

• 文档： docs/
• 问题： 通过GitHub Issues报告错误和功能请求
• 讨论： 通过GitHub讨论提供社区支持

相关资源

• 模型上下文协议规范
• Redmine插件开发
• Redmine API文档