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

Name: Redmine MCP服务器
Author: snowild

使用说明

Redmine MCP服务器

A. 模型上下文协议（MCP） Redmine集成服务器，使Claude Code能够直接与Redmine项目管理系统交互。

🚀 特性

✅ 问题管理

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

✅ 项目管理

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

✅ 搜索功能

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

✅ 系统工具

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

📋 系统要求

python：3.12或更高
Redmine：支持REST API的版本（推荐使用4.0+版本）
包管理器: 紫外线或pip

🔧 安装和设置

1.克隆项目

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

2.安装依赖项

使用紫外线（推荐）：

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

# Project-specific variables (avoid conflicts with other projects)
REDMINE_MCP_LOG_LEVEL=INFO
REDMINE_MCP_TIMEOUT=30

# Backward compatibility variables (fallback)
REDMINE_TIMEOUT=30
LOG_LEVEL=info

环境变量参考

变量	描述	默认值	示例
`REDMINE_DOMAIN`	Redmine服务器URL	必需的	`https://redmine.example.com`
`REDMINE_API_KEY`	您的Redmine API密钥	必需的	`abc123...`
`REDMINE_MCP_LOG_LEVEL`	此MCP服务器的日志级别	`INFO`	`DEBUG`, `INFO`, `WARNING`, `ERROR`
`REDMINE_MCP_TIMEOUT`	请求超时（秒）	`30`	`60`
`REDMINE_MCP_TRANSPORT`	运输方式	`stdio`	`stdio`, `sse`
`REDMINE_MCP_HOST`	SSE绑定地址	`0.0.0.0`	`127.0.0.1`
`REDMINE_MCP_PORT`	SSE监听端口	`8000`	`3000`
`LOG_LEVEL`	旧日志级别（向后兼容性）	-	`debug`, `info`
`REDMINE_TIMEOUT`	传统超时（向后兼容性）	-	`30`

日志级别优先级：

REDMINE_MCP_LOG_LEVEL （最高优先级-特定项目）
LOG_LEVEL （向后兼容性）
INFO （如果两者都没有设置，则默认）

备注：系统自动处理案例转换，并确保FastMCP兼容性。

4.Redmine API设置

4.1启用REST API

以管理员身份登录Redmine
首选行政 → 设置 → API
检查 “启用REST web服务”
点击保存

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

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

配置角色和权限

首选行政 → 角色和权限
创建或编辑角色（例如：开发人员、测试人员、项目经理）
为角色分配适当的权限（至少建议：查看问题、添加问题、编辑问题）

配置跟踪器

首选行政 → 追踪器
创建跟踪器类型（例如：Bug、功能、支持）
为每个跟踪器设置默认状态和工作流

配置问题状态

首选行政 → 问题状态
创建状态（例如：新建、进行中、已解决、已关闭、已拒绝）
设置状态属性（是否为关闭状态等）

配置工作流

首选行政 → 工作流
为每个角色和跟踪器组合设置允许的状态转换
确保基本状态转换路径（新→ 进行中→ 已解决→ 关闭）

创建项目

首选项目 → 新项目
设置项目名称、标识符、描述
选择已启用的模块（至少启用“问题跟踪”）
分配成员并设置角色

4.3获取API密钥

登录到您的Redmine系统（可以是管理员或普通用户）
首选 我的账户 → API访问密钥
点击展示或重置获取API密钥
将密钥复制到 REDMINE_API_KEY 在 .env 文件

⚠️ 重要说明:

如果找不到API密钥选项，请确保完成步骤4.1（启用REST API）

在正确创建和管理问题之前，请完成基本设置

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

🔗 Claude代码集成

安装到Claude代码

# Install from local
uv tool install .

# Or using pip
pip install .

# Add to Claude Code MCP configuration
claude mcp add redmine "redmine-mcp" \
  -e REDMINE_DOMAIN="https://your-redmine-domain.com" \
  -e REDMINE_API_KEY="your_api_key_here"

验证安装

# Test MCP server
uv run python -m redmine_mcp.server

# Test Claude Code integration
uv run python tests/scripts/claude_integration.py

🌐 SSE模式和Docker部署

运输方式

Redmine MCP支持两种传输模式：

模式	用例	多客户端	部署
标准（默认）	使用Claude Code的本地CLI使用情况	❌ Single	由Claude Code自动启动
SSE	团队共享、远程访问、容器化	✅ 多次	需要手动启动

在SSE模式下运行

快速启动（开发）

# Navigate to project directory (where .env file is located)
cd /path/to/redmine-mcp

# Run with uv (reads .env automatically)
uv run redmine-mcp --transport sse

# Custom host and port
uv run redmine-mcp --transport sse --host 127.0.0.1 --port 3000

全球安装

# Install globally
uv tool install . --force --reinstall

# Set environment variables
export REDMINE_DOMAIN=https://your-redmine.com
export REDMINE_API_KEY=your_api_key_here

# Run from anywhere
redmine-mcp --transport sse

使用.env文件

创建一个 .env 工作目录中的文件：

REDMINE_DOMAIN=https://your-redmine.com
REDMINE_API_KEY=your_api_key_here
REDMINE_MCP_TRANSPORT=sse
REDMINE_MCP_PORT=8000

备注: uv run 自动加载 .env 从项目目录中。全局安装需要显式的环境变量或从包含以下内容的目录运行 .env.

Docker部署

Docker快速入门

# Build the image
docker build -t redmine-mcp .

# Run with environment variables
docker run -d \
  -e REDMINE_DOMAIN=https://your-redmine.com \
  -e REDMINE_API_KEY=your_api_key \
  -p 8000:8000 \
  --name redmine-mcp \
  redmine-mcp

使用Docker Compose

# Edit docker-compose.yml with your Redmine settings
# Then start the service
docker compose up -d

# View logs
docker compose logs -f

# Stop the service
docker compose down

Docker使用.env文件编写（推荐）

创建 .env 文件：

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

更新 docker-compose.yml 要使用环境变量：

environment:
  - REDMINE_DOMAIN=${REDMINE_DOMAIN}
  - REDMINE_API_KEY=${REDMINE_API_KEY}

启动服务：

docker compose up -d

在Docker中启用文件上传

文件上传工具(attach_files_to_issue 和 create_new_issue 与 file_paths)从读取本地文件 MCP服务器自己的文件系统.何时服务器在容器内运行，除非主机目录作为卷装载，否则上传失败 File does not exist or is not a file: ....

将保存上传源的目录挂载到 同一条路 在里面容器（只读就足够了），因此您传递的绝对路径将解析双方：

services:
  redmine-mcp:
    # ...
    volumes:
      - /Users/you/workspace:/Users/you/workspace:ro

然后重新创建容器，使体积生效：

docker compose up -d --force-recreate

笔记：

只能上传挂载目录下的文件；外面的路（例如。 ~/Desktop, ~/Downloads)除非也安装，否则仍然会失败。
通过 绝对路径 在挂载的目录下上传工具。
这在以下情况下是不必要的 stdio 模式，服务器在主机上运行本机读取本地路径。

将Claude代码连接到SSE服务器

SSE服务器运行后，配置Claude Code进行连接：

# Add MCP with SSE transport
claude mcp add --transport sse redmine http://localhost:8000/sse

或手动编辑 ~/.claude.json:

{
  "mcpServers": {
    "redmine": {
      "transport": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

备注：环境变量(REDMINE_DOMAIN, REDMINE_API_KEY)在上配置 SSE服务器端，而不是克劳德密码。

将VS代码（GitHub Copilot）连接到SSE服务器

使用GitHub Copilot的VS Code也可以连接到SSE服务器。编辑MCP配置文件：

macOS: ~/Library/Application Support/Code/User/mcp.json

视窗: %APPDATA%\Code\User\mcp.json

Linux: ~/.config/Code/User/mcp.json

添加以下配置：

{
  "servers": {
    "redmine": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

参考：有关VS Code MCP配置的更多详细信息，请参阅 VS代码MCP服务器文档.

🔄 更新/重新安装MCP

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

快速更新（推荐）

# Navigate to project directory
cd /path/to/redmine-mcp

# Pull latest changes (if from git)
git pull origin main

# Force reinstall with uv tool
uv tool install . --force --reinstall

# Restart Claude Code to reload MCP server

完全重新安装

如果快速更新不起作用，请按照以下步骤操作：

1.删除以前的安装

# Remove from Claude Code
claude mcp remove redmine

# Uninstall the package (if installed with uv tool)
uv tool uninstall redmine-mcp

# Or if installed with pip
pip uninstall redmine-mcp

2.安装最新版本

# Navigate to project directory
cd /path/to/redmine-mcp

# Pull latest changes (if from git)
git pull origin main

# Install latest version
uv tool install .

# Or using pip
pip install .

3.使用Claude Code重新注册

# Use full path to avoid PATH conflicts
claude mcp add redmine "$(which 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.验证更新的安装

# Check installed version
uv tool list | grep redmine

# Verify MCP registration
claude mcp list

# Or check in Claude Code using slash command
# /mcp

更新问题疑难解答

问题：更新后旧版本仍在运行

这通常发生在PATH有多个 redmine-mcp 可执行文件
解决方案：在Claude Code MCP配置中使用完整路径

# Find the correct path
ls -la ~/.local/bin/redmine-mcp

# Update MCP config with full path
claude mcp remove redmine
claude mcp add redmine "/Users/YOUR_USERNAME/.local/bin/redmine-mcp" \
  -e REDMINE_DOMAIN="https://your-redmine-domain.com" \
  -e REDMINE_API_KEY="your_api_key_here"

问题：更新后“无法重新连接到redmine”

完全重新启动Claude Code（关闭并重新打开）
或使用 /mcp 命令并选择 restart 用于redmine服务器

重要提示：

更新MCP服务器后始终重新启动Claude Code

使用 --force --reinstall 标记以确保安装清洁

检查刀具计数 /mcp 验证更新（当前：36个工具）

🛠️ 可用的MCP工具（36个工具）

基础工具

工具名称	描述
`server_info`	显示服务器信息和配置状态
`health_check`	检查服务器和Redmine连接健康状态
`refresh_cache`	手动刷新枚举值和用户缓存

问题操作

工具名称	描述
`get_issue`	获取指定问题的详细信息
`create_new_issue`	创建新问题（支持名称参数和 `file_paths` 附件）
`update_issue_status`	更新问题状态
`update_issue_content`	更新问题内容（标题、描述等）
`add_issue_note`	为问题添加注释（支持时间跟踪）
`assign_issue`	分配或取消分配问题
`close_issue`	关闭问题并设置完成率

日志工具

工具名称	描述
`list_issue_journals`	列出一期的所有日记/笔记
`get_journal`	获取特定期刊的详细信息

随机工具✨ 新

工具名称	描述
`get_attachment_info`	获取附件元数据（无需下载）
`get_attachment_image`	下载图像进行AI视觉分析（支持缩略图）
`attach_files_to_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`	获取所有可用的文档类别

用户工具

工具名称	描述
`search_users`	按名称或登录名搜索用户
`list_users`	列出所有用户
`get_user`	获取特定用户的详细信息

💡 使用示例

在Claude代码中使用

# Check server status
Please run health check

# Get project list
Show all accessible projects

# View system settings
Get all available issue statuses
Get all available tracker lists
Get all available issue priorities
Get all available time tracking activities
Get all available document categories

# View specific issue
Get detailed information for issue #123

# Create new issue
Create an issue in project ID 1:
- Title: Fix login error
- Description: Users cannot log in to the system properly
- Priority: High

# Search issues
Search for issues containing "login" keyword

# Update issue status
Update issue #123 status to "In Progress" with note "Starting to handle this issue"

🧪 测试

运行测试套件

# Run all tests
uv run python -m pytest

# Run MCP integration tests
uv run python tests/scripts/mcp_integration.py

# Run Claude Code integration tests  
uv run python tests/scripts/claude_integration.py

Docker环境测试

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

# Start Redmine test environment
docker-compose up -d

# Quick start complete test environment
./quick_start.sh

📁 项目结构

redmine-mcp/
├── src/redmine_mcp/          # Main source code
│   ├── __init__.py           # Package initialization
│   ├── server.py             # MCP server main program
│   ├── redmine_client.py     # Redmine API client
│   ├── config.py             # Configuration management
│   └── validators.py         # Data validation
├── tests/                    # Test files
├── docs/                     # Documentation directory
├── Dockerfile                # Docker build configuration
├── docker-compose.yml        # Docker Compose configuration
├── .dockerignore             # Docker build exclusions
├── CHANGELOG.md              # Version history
├── pyproject.toml            # Project configuration
└── README.md                 # Project documentation

🤝 贡献

分叉此项目
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add some amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

📦 更新日志

看更改日志.md 查看版本历史和发行说明。

🔗 相关链接

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

使用说明