Redmine MCP服务（zh） - MCP Server 功能介绍与安装配置 - AI导哈

Name: Redmine MCP服务
Author: zh

使用说明

Redmine MCP服务器

模型上下文协议（MCP）服务器，通过其REST API为人工智能助手提供对Redmine项目管理软件的访问。

特性

完全Redmine API访问：与项目、问题、用户、时间条目等进行交互
MCP协议：AI到工具通信的标准协议
独立服务器：独立部署，连接到任何Redmine实例
安全：使用Redmine进行基于API密钥的身份验证
灵活的：可通过环境变量进行配置

先决条件

Ruby 3.1或更高版本
访问启用REST API的Redmine实例（5.0+）
Redmine API密钥（从Redmine的/my/account页面获取）

可选Redmine插件

一些MCP工具需要 Redmine扩展API插件 对于高级功能：

自定义字段CRUD: create_custom_field, update_custom_field, delete_custom_field
CRUD查询: create_query, update_query, delete_query
批量时间条目: bulk_create_time_entries

安装:

cd /path/to/redmine/plugins
git clone https://github.com/zh/redmine_extended_api.git
cd /path/to/redmine
bundle install
bundle exec rake redmine:plugins:migrate RAILS_ENV=production
systemctl restart redmine

看 redmine_扩展api 了解详情。

备注：所有其他MCP工具都可以使用标准Redmine REST API（无需插件）。

安装

克隆或下载此存储库
安装依赖项：
```
bundle install
```
复制示例环境文件并配置：
```
cp .env.example .env
```

编辑 .env 并设置您的Redmine凭据：

REDMINE_URL=https://your-redmine-instance.com
REDMINE_API_KEY=your_api_key_here

配置

所有配置都是通过环境变量完成的 .env 文件：

所需配置

变量	描述	默认值	必填
`REDMINE_URL`	Redmine实例的基本URL	-	是
`REDMINE_API_KEY`	您的Redmine API密钥	-	是

服务器配置

变量	描述	默认值	必填
`MCP_PORT`	MCP服务器的端口	3100	否
`MCP_HOST`	要绑定到	localhost	否
`RACK_ENV`	环境（开发/生产）	开发	否
`LOG_LEVEL`	日志记录级别（调试/信息/警告/错误）	信息	否

性能配置

变量	描述	默认值	必填
`HTTP_TIMEOUT`	HTTP请求超时（秒）	30	否
`HTTP_READ_TIMEOUT`	HTTP读取超时（秒）	60	否
`FALCON_PROCESSES`	服务器工作进程数	1	否
`METRICS_SLOW_THRESHOLD`	慢速请求阈值（秒）	1.0	否

备注：连接池和压缩（gzip/deflate）由异步HTTP客户端自动处理。

获取您的Redmine API密钥

登录您的Redmine实例
导航到“我的帐户”（/My/Account）
在右侧栏中查找“API访问密钥”
点击“显示”以显示您的密钥，或点击“重置”以生成新密钥
将密钥复制到您的 .env 文件

用法

启动服务器

服务器使用猎鹰，高性能异步web服务器。

开发模式 （自动重新加载）：

bundle exec rerun -- falcon serve --bind http://localhost:3100

生产模式:

bundle exec falcon serve --bind http://localhost:3100

服务器将从多个工作进程（默认为8个）开始，以获得最佳性能。您可以通过设置来控制工人的数量 FALCON_PROCESSES 在你的 .env 文件。

从MCP客户端连接

将服务器添加到MCP客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "redmine": {
      "command": "bundle",
      "args": ["exec", "falcon", "serve", "--bind", "http://localhost:3100"],
      "cwd": "/path/to/redmine_mcp_server"
    }
  }
}

或者连接到正在运行的服务器：

{
  "mcpServers": {
    "redmine": {
      "url": "http://localhost:3100/mcp"
    }
  }
}

可用工具

当前状态

53个已完全实施的工具 （项目、成员资格、版本、问题、用户、组、时间条目、自定义字段、查询、批处理操作）
21骨架工具 （结构已定义，准备实施）
74总工具 跨越14个资源类别

已实施的工具✅

项目运营（5个工具）

list_projects -列出所有可访问的项目，并进行分页和筛选
get_project -获取特定项目的详细信息
create_project -创建新项目
update_project -更新现有项目
delete_project -删除项目

会员操作（5个工具）

list_memberships -列出项目的所有成员
get_membership -获取特定会员的详细信息
create_membership -将用户/组添加到具有角色的项目中
update_membership -更新项目成员的角色
delete_membership -从项目中删除用户/组

版本/里程碑操作（5个工具）

list_versions -列出项目的版本/里程碑
get_version -获取特定版本的详细信息
create_version -创建新版本/里程碑
update_version -更新现有版本
delete_version -删除版本

问题操作（13个工具）

list_issues -列出过滤、排序和分页问题（支持已保存查询的query_id）
get_issue -获取特定问题的详细信息
create_issue -在项目中创建新问题
update_issue -更新现有问题
delete_issue -删除问题
add_issue_watcher -向问题添加观察者
remove_issue_watcher -从问题中删除观察者
get_issue_relations -获取问题的所有关系（块、关联等）
create_issue_relation -在两个问题之间建立关系
delete_issue_relation -删除问题关系
get_issue_journals -获取某个问题的变更历史（日志）
copy_issue -将问题复制到另一个项目或同一项目中
move_issue -将问题转移到其他项目

用户操作（5个工具）

list_users -列出所有具有过滤和分页功能的用户
get_user -获取特定用户的详细信息
create_user -创建新用户帐户（需要管理员）
update_user -更新现有用户帐户
delete_user -删除用户帐户

集团运营（5种工具）

list_groups -列出所有组（需要管理员）
get_group -获取特定组（包括成员）的详细信息
create_group -创建一个包含可选初始成员的新组
update_group -更新组详细信息和成员资格
delete_group -删除组

时间输入操作（6个工具）

list_time_entries -按用户、项目、问题或日期范围筛选列出时间条目
get_time_entry -获取特定时间条目的详细信息
create_time_entry -记录问题或项目的时间
update_time_entry -更新现有时间条目
delete_time_entry -删除时间条目
bulk_create_time_entries -在单个请求中创建多个时间条目（需要扩展API插件）

自定义字段操作（4个工具）

list_custom_fields -列出所有自定义字段及其配置
create_custom_field -创建一个新的自定义字段（需要admin，Extended API插件）
update_custom_field -更新现有的自定义字段（需要admin、Extended API插件）
delete_custom_field -删除自定义字段（需要管理员、扩展API插件）

注：可以使用以下命令在问题、项目、用户和其他实体中设置自定义字段值 custom_field_values 或 custom_fields 在各自的创建/更新工具中设置参数。

查询操作（4个工具）

list_queries -列出所有可访问的查询（已保存的筛选器）并分页
create_query -创建具有筛选器、可见性和列的新查询（需要扩展API插件）
update_query -更新现有查询（需要扩展API插件）
delete_query -删除查询（需要扩展API插件）

查询功能：

已保存的筛选器：查询是为问题、时间条目、项目等保存的过滤器。
过滤器操作员：支持所有Redmine操作员(=, !=, >=, <=, ~, !~, o （打开）， c （关闭）， t （今天）， w （周）， m （月）， <t+N, >t-N)
可见性级别：私有（0）、角色（1）、公共（2）
查询类型：IssueQuery、ProjectQuery、TimeEntryQuery
执行：使用 list_issues 随着 query_id 用于执行已保存查询的参数
权限：用户管理自己的私人查询； manage_public_queries 用于项目查询；全局查询管理员

示例-创建并执行查询：

// 1. Create a query for late issues
{
  "name": "create_query",
  "params": {
    "name": "Late Issues Before May",
    "type": "IssueQuery",
    "visibility": 0,
    "filters": {
      "due_date": {"operator": "<=", "values": ["2025-05-01"]},
      "status_id": {"operator": "o"}
    },
    "column_names": ["id", "subject", "status", "due_date"],
    "sort_criteria": [["due_date", "asc"]]
  }
}
// Returns: {"id": 10, "name": "Late Issues Before May", ...}

// 2. Execute the saved query
{
  "name": "list_issues",
  "params": {
    "query_id": 10
  }
}
// Returns filtered and sorted issues based on the saved query

批量操作（1个工具）

batch_execute -同时执行多个MCP工具以提高性能

骨架工具（准备实施）⏳

所有骨架工具都定义了完整的模式，但提高了 NotImplementedError:

wiki页面 （6个工具）：列表、获取、创建、更新、删除、版本
附件（3个工具）：上传、获取、删除
新闻（2个工具）：列表，获取
参考数据 （7个工具）：跟踪器、状态、优先级、活动、角色、搜索

看 TOOLS.md 获取完整的工具文档。

性能与监控

MCP服务器包括内置的性能优化和监控功能。

性能特点

HTTP优化（异步架构）

自动连接池异步HTTP客户端自动管理连接
HTTP保持活动：通过自动管理实现高效的连接重用
响应压缩：自动gzip/deflate压缩（带宽减少70-80%）
基于光纤的并发：使用Ruby光纤的轻量级并发操作
可配置超时：连接和读取操作的单独设置
多进程服务器：Falcon运行多个工作进程（可配置）以实现真正的并行性

批处理执行

使用 batch_execute 同时运行多个操作的工具：

{
  "name": "batch_execute",
  "params": {
    "calls": [
      { "name": "get_issue", "params": { "id": 123 } },
      { "name": "get_issue", "params": { "id": 456 } },
      { "name": "list_time_entries", "params": { "issue_id": 123 } }
    ],
    "max_concurrency": 5
  }
}

性能增益：与顺序执行相比，独立操作的速度快20倍。

指标端点

实时监控服务器性能：

Prometheus格式 （适用于Grafana等监控工具）：

curl http://localhost:3100/metrics

工具指标 （JSON）：

curl http://localhost:3100/metrics/tools

退货：

{
  "tools": [
    {
      "tool": "list_issues",
      "total_calls": 42,
      "success_count": 40,
      "error_count": 2,
      "total_duration_ms": 1250.5,
      "avg_duration_ms": 29.77,
      "errors_by_type": { "NotFoundError": 2 }
    }
  ]
}

API指标 （JSON）：

curl http://localhost:3100/metrics/api

缓慢的请求 （JSON）：

curl http://localhost:3100/metrics/slow

列出超过慢速阈值（默认值：1.0秒）的请求。

性能配置

在中配置性能设置 .env:

# HTTP timeouts in seconds
HTTP_TIMEOUT=30          # Request timeout
HTTP_READ_TIMEOUT=60     # Read timeout

# Server configuration
FALCON_PROCESSES=1       # Number of worker processes (increase for production)

# Metrics
METRICS_SLOW_THRESHOLD=1.0  # Slow request threshold in seconds

备注：异步HTTP客户端自动处理连接池和压缩。这些功能不需要手动配置。

看 docs/PERFORMANCE.md 获取详细的性能调优指南。

发展

运行测试

所有实现的工具都具有全面的RSpec测试覆盖率（330多个测试）。

运行所有测试：

bundle exec rspec

运行特定工具类别：

bundle exec rspec spec/tools/time_entries/
bundle exec rspec spec/tools/custom_fields/
bundle exec rspec spec/tools/queries/

测试覆盖范围包括：

工具元数据验证
具有最小和可选参数的成功案例
必需的参数验证
错误处理（身份验证、验证，未找到）

看 TOOLS.md 获取详细的测试指南。

代码质量

bundle exec rubocop
bundle exec rubocop --autocorrect

项目结构

redmine_mcp_server/
├── lib/
│   ├── redmine_mcp_server.rb    # Main application
│   ├── async_redmine_client.rb  # Async Redmine API client
│   ├── tools/                    # MCP tools (operations)
│   │   ├── base_tool.rb
│   │   ├── projects/             # Project CRUD
│   │   ├── issues/               # Issue operations
│   │   └── ...
│   └── resources/                # MCP resources (data sources)
├── spec/                         # RSpec tests
├── Gemfile                       # Ruby dependencies
├── config.ru                     # Rack configuration
└── .env                          # Environment configuration

建筑

┌─────────────┐         ┌──────────────────┐         ┌─────────────┐
│             │         │                  │         │             │
│  AI Client  │ ◄─MCP──►│  Redmine MCP     │ ◄─HTTP──►│  Redmine    │
│  (Claude)   │         │     Server       │         │   Instance  │
│             │         │                  │         │             │
└─────────────┘         └──────────────────┘         └─────────────┘

AI客户端：Claude或其他与MCP兼容的AI助手
Redmine MCP服务器：此应用程序（将MCP转换为Redmine API）
Redmine实例：您的Redmine安装

故障排除

连接问题

错误：“缺少必需的环境变量：REDMINE_URL”

确保你有一个 .env 项目根目录中的文件
验证是否设置了所有必需的变量

错误：“连接被拒绝”或“超时”

检查你的 REDMINE_URL 正确且可访问
验证Redmine的REST API是否已启用（管理→ 设置→ API)
手动测试API访问： curl -H "X-Redmine-API-Key: YOUR_KEY" https://your-redmine.com/users/current.json

错误：“401未经授权”

验证您的API密钥是否正确
检查与API密钥关联的用户是否具有适当的权限
如有必要，生成新的API密钥

服务器问题

错误：“地址已在使用中”

另一个进程正在使用端口3100
更改端口 .env: MCP_PORT=3101
或者停止另一个进程： lsof -ti:3100 | xargs kill -9

安全考虑

API密钥：从不承诺 .env 文件到版本控制
网络：在生产环境中，使用HTTPS进行Redmine连接
防火墙：仅限制MCP服务器访问受信任的客户端
权限：使用具有适当权限的Redmine API密钥（最低权限原则）

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
为新功能编写测试
确保所有测试通过，代码通过rubocop
提交拉取请求

许可证

该项目可在MIT许可证下使用。

致谢

内置于 mcp_onruby
由...驱动红矿 REST API
用途异步用于高性能并发HTTP通信
由……服务猎鹰，现代异步web服务器

支持

对于问题、疑问或贡献：

GitHub问题：创建问题
文档： Redmine REST API

路线图

[x] 第一阶段：项目结构和配置
[x] 第二阶段：Redmine API客户
[x] 第三阶段：MCP基础设施
[x] 第4阶段：项目CRUD操作
[x] 阶段4.5：项目复制、成员资格和版本管理
[x] 阶段4.6：问题管理工具（13个工具）
[x] 阶段4.7：用户管理工具（5个工具）
[x] 阶段4.8：组管理工具（5个工具）
[x] 第五阶段：时间输入工具（包括批量操作在内的6个工具）
[x] 阶段5.5：自定义字段管理工具（4个工具）
[x] 阶段5.6：性能优化（连接池、压缩、度量、批处理执行）
[x] 阶段5.7：查询管理工具（4个用于保存过滤器的工具）
[]第6阶段：Wiki和附件工具
[]第7阶段：新闻和参考数据工具
[]第8阶段：高级功能（缓存、webhooks）
[]第9阶段：全面测试覆盖
[]第10阶段：生产部署指南

使用说明

Redmine MCP服务器

特性

先决条件

可选Redmine插件

安装

配置

所需配置

服务器配置

性能配置

获取您的Redmine API密钥

用法

启动服务器

从MCP客户端连接

可用工具

当前状态

已实施的工具✅

项目运营（5个工具）

会员操作（5个工具）

版本/里程碑操作（5个工具）

问题操作（13个工具）

用户操作（5个工具）

集团运营（5种工具）

时间输入操作（6个工具）

自定义字段操作（4个工具）

查询操作（4个工具）

批量操作（1个工具）

骨架工具（准备实施）⏳

性能与监控

性能特点

HTTP优化（异步架构）

批处理执行

指标端点

性能配置

发展

运行测试

代码质量

项目结构

建筑

故障排除

连接问题

服务器问题

安全考虑

贡献

许可证

致谢

支持

路线图

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

GitLab项目管理服务器

Unity编辑器AI集成插件