Redmine MCP 服务器

用于 Redmine 集成的 模型上下文协议 (MCP) 服务器，使 Claude Code 能够直接与 Redmine 项目管理系统进行交互。

🚀 功能

✅ 问题管理

• 查询问题：获取详细的问题信息和列表
• 创建问题：创建新问题并设置相关属性
• 更新问题：修改问题内容、状态、优先级等
• 分配问题：将问题分配给特定用户或取消分配
• 添加备注：向问题中添加公开或私有备注
• 关闭问题：自动将问题设置为完成状态

✅ 项目管理

• 项目列表：获取可访问的项目列表
• 项目问题：按状态过滤并列出项目中的所有问题

✅ 搜索功能

• 关键词搜索：在问题标题和描述中搜索关键词
• 我的问题：快速查看分配给当前用户的问题

✅ 系统工具

• 健康检查：验证 MCP 服务器和 Redmine 的连接状态
• 状态查询：获取可用的问题状态列表

📋 系统需求

• Python：3.12 或更高版本
• Redmine：支持 REST API 的版本（推荐 4.0+）
• 包管理器：uv 或 pip

🔧 安装与配置

1. 克隆项目

git clone https://github.com/snowild/redmine-mcp.git
cd redmine-mcp

2. 安装依赖

使用 uv（推荐）：

uv sync

或者使用 pip：

pip install -e .

3. 环境配置

创建一个 .env 文件：

cp .env.example .env

编辑 .env 文件并设置以下环境变量：

REDMINE_DOMAIN=https://your-redmine-domain.com
REDMINE_API_KEY=your_api_key_here

# 项目特定变量（避免与其他项目冲突）
REDMINE_MCP_LOG_LEVEL=INFO
REDMINE_MCP_TIMEOUT=30

# 向后兼容变量（备用）
REDMINE_TIMEOUT=30
LOG_LEVEL=info

环境变量参考

变量	描述	默认值	示例
REDMINE_DOMAIN	Redmine 服务器 URL	必填	https://redmine.example.com
REDMINE_API_KEY	您的 Redmine API 密钥	必填	abc1_23...
REDMINE_MCP_LOG_LEVEL	此 MCP 服务器的日志级别	INFO	DEBUG, INFO, WARNING, ERROR
REDMINE_MCP_TIMEOUT	请求超时时间（秒）	30	60
LOG_LEVEL	遗留日志级别（向后兼容）	-	debug, info
REDMINE_TIMEOUT	遗留超时时间（向后兼容）	-	30

日志级别优先级：

1. REDMINE_MCP_LOG_LEVEL（最高优先级 - 项目特定）
2. LOG_LEVEL（向后兼容）
3. INFO（如果两者均未设置的默认值）

注意：系统会自动处理大小写转换，并确保与 FastMCP 兼容。

4. Redmine API 设置

4.1 启用 REST API

1. 以管理员身份登录 Redmine
2. 前往 管理 → 设置 → API
3. 勾选 “启用 REST Web 服务”
4. 点击 保存

4.2 配置 Redmine 基本数据（管理员）

在使用 MCP 工具之前，需要配置 Redmine 的基本数据：

配置角色和权限

1. 前往 管理 → 角色和权限
2. 创建或编辑角色（例如：开发者、测试员、项目经理）
3. 为角色分配适当的权限（建议至少包括：查看问题、添加问题、编辑问题）

配置跟踪器

1. 前往 管理 → 跟踪器
2. 创建跟踪器类型（例如：Bug、Feature、Support）
3. 为每个跟踪器设置默认状态和工作流

配置问题状态

1. 前往 管理 → 问题状态
2. 创建状态（例如：新建、进行中、已解决、关闭、拒绝）
3. 设置状态属性（是否为关闭状态等）

配置工作流

1. 前往 管理 → 工作流
2. 为每个角色和跟踪器组合设置允许的状态转换
3. 确保基本状态转换路径（新建 → 进行中 → 已解决 → 关闭）

创建项目

1. 前往 项目 → 新建项目
2. 设置项目名称、标识符、描述
3. 选择启用的模块（至少启用“问题跟踪”）
4. 分配成员并设置角色

4.3 获取 API 密钥

1. 登录您的 Redmine 系统（可以是管理员或普通用户）
2. 前往 我的账户 → API 访问密钥
3. 点击 显示 或 重置 来获取 API 密钥
4. 将密钥复制到 .env 文件中的 REDMINE_API_KEY

⚠️ 重要提示：

• 如果找不到 API 密钥选项，请确保已完成步骤 4.1（启用 REST API）
• 在正确创建和管理问题之前，请完成基本设置

📚 详细设置指南：有关完整的 Redmine 设置步骤，请参阅 Redmine 完整设置指南

🔗 Claude Code 集成

安装到 Claude Code

# 从本地安装
uv tool install .

# 或使用 pip
pip install .

# 添加到 Claude Code MCP 配置
claude mcp add redmine "redmine-mcp" \
  -e REDMINE_DOMAIN="https://your-redmine-domain.com" \
  -e REDMINE_API_KEY="your_api_key_here"

验证安装

# 测试 MCP 服务器
uv run python -m redmine_mcp.server

# 测试 Claude Code 集成
uv run python tests/scripts/claude_integration.py

🔄 更新/重新安装 MCP

如果您需要更新到最新版本的 MCP 服务器或重新安装：

1. 移除之前的安装

# 从 Claude Code 移除
claude mcp remove redmine

# 卸载包（如果使用 uv tool 安装）
uv tool uninstall redmine-mcp

# 或者如果使用 pip 安装
pip uninstall redmine-mcp

2. 安装最新版本

# 导航到项目目录
cd /path/to/redmine-mcp

# 拉取最新更改（如果来自 git）
git pull origin main

# 安装最新版本
uv tool install .

# 或使用 pip
pip install .

3. 重新注册到 Claude Code

claude mcp add redmine "redmine-mcp" \
  -e REDMINE_DOMAIN="https://your-redmine-domain.com" \
  -e REDMINE_API_KEY="your_api_key_here" \
  -e REDMINE_MCP_LOG_LEVEL="INFO" \
  -e REDMINE_MCP_TIMEOUT="30"

4. 验证更新安装

# 验证 MCP 注册
claude mcp list

# 或通过 Claude Code 使用斜杠命令检查
# /mcp

# 或直接测试
uv run python -m redmine_mcp.server --help

重要提示：

• 环境变量名称已更新，以实现更好的项目隔离
• 现在同时支持 REDMINE_MCP_LOG_LEVEL（首选）和 LOG_LEVEL（向后兼容）
• 日志级别处理现在更加健壮，具有自动大小写转换和 FastMCP 兼容性

🛠️ 可用的 MCP 工具

基础工具

工具名称	描述
server_info	显示服务器信息和配置状态
health_check	检查服务器和 Redmine 的连接健康状况

问题操作

工具名称	描述
get_issue	获取指定问题的详细信息
create_new_issue	创建新问题
update_issue_status	更新问题状态
update_issue_content	更新问题内容（标题、描述等）
add_issue_note	向问题添加备注
assign_issue	分配或取消分配问题
close_issue	关闭问题并设置完成率

查询工具

工具名称	描述
list_project_issues	列出项目中的问题
get_my_issues	获取分配给我的问题列表
search_issues	搜索包含关键词的问题
get_projects	获取可访问项目的列表
get_issue_statuses	获取所有可用的问题状态
get_trackers	获取所有可用的跟踪器列表
get_priorities	获取所有可用的问题优先级
get_time_entry_activities	获取所有可用的时间跟踪活动
get_document_categories	获取所有可用的文档类别

💡 使用示例

在 Claude Code 中使用

# 检查服务器状态
请运行健康检查

# 获取项目列表
显示所有可访问的项目

# 查看系统设置
获取所有可用的问题状态
获取所有可用的跟踪器列表
获取所有可用的问题优先级
获取所有可用的时间跟踪活动
获取所有可用的文档类别

# 查看特定问题
获取问题 #123 的详细信息

# 创建新问题
在项目 ID 1 中创建一个问题：
- 标题：修复登录错误
- 描述：用户无法正常登录系统
- 优先级：高

# 搜索问题
搜索包含“登录”关键词的问题

# 更新问题状态
将问题 #123 的状态更新为“进行中”，附带备注“开始处理此问题”

🧪 测试

运行测试套件

# 运行所有测试
uv run python -m pytest

# 运行 MCP 集成测试
uv run python tests/scripts/mcp_integration.py

# 运行 Claude Code 集成测试
uv run python tests/scripts/claude_integration.py

Docker 环境测试

如果您想在本地 Docker 环境中测试：

# 启动 Redmine 测试环境
docker-compose up -d

# 快速启动完整测试环境
./quick_start.sh

🔍 故障排除

常见问题

1. API 认证失败（401/403 错误）

• 验证 API 密钥是否正确
• 检查 Redmine 是否启用了 REST API：前往 管理 → 设置 → API，勾选“启用 REST Web 服务”
• 验证用户权限是否足够
• 检查 URL 是否正确（包括 http/https 和端口）

2. 连接超时

• 检查网络连接
• 调整 REDMINE_TIMEOUT 环境变量
• 验证 Redmine 服务器状态

3. 创建问题失败

• 验证项目是否存在且具有权限
• 检查是否填写了所需字段
• 验证跟踪器和状态设置
• 检查基本数据配置：确保角色、跟踪器、状态和工作流设置完整
• 验证用户在项目中具有适当的角色和权限

4. 状态更新失败

• 检查工作流是否允许状态转换
• 验证用户角色是否有权限更改状态
• 验证目标状态 ID 是否正确

5. 项目或问题未找到

• 验证 ID 是否正确
• 检查用户是否有权限查看该项目/问题
• 验证项目状态是否处于激活状态

调试模式

启用调试模式以获取更详细的错误信息：

DEBUG_MODE=true

📁 项目结构

redmine-mcp/
├── src/redmine_mcp/          # 主源代码
│   ├── __init__.py           # 包初始化
│   ├── server.py             # MCP 服务器主程序
│   ├── redmine_client.py     # Redmine API 客户端
│   ├── config.py             # 配置管理
│   └── validators.py         # 数据验证
├── tests/                    # 测试文件
├── docs/                     # 文档目录
├── docker-compose.yml        # Docker 测试环境
├── pyproject.toml            # 项目配置
└── README.md                 # 项目文档

🤝 贡献

1. 分叉此项目
2. 创建一个功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m '添加一些神奇的功能')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个拉取请求

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🔗 相关链接

• 模型上下文协议
• Claude Code
• Redmine
• FastMCP

---

如果您有任何问题或建议，请随时打开一个 Issue 或联系项目维护人员。