内容
# 红矿MCP
一款MCP（模型上下文协议）服务器，允许 [Claude Code](https://claude.ai/claude-code) 直接操作Redmine。
在RHEL或Docker上作为HTTP服务器运行。凭证永远不会存储在服务器上 — 它们通过Claude Code配置文件中的HTTP标头传递。
---
## 主要功能
1. **上下文优先设计**
返回日志（评论）以及问题，以便AI可以推理历史，生成准确的后续提案，并总结进展。
2. **无状态设计**
API密钥通过客户端的每个请求传递，永远不会存储在服务器上。这带来了三个实际的好处：
- **最大安全性** — 即使服务器被泄露，也没有存储的API密钥可以窃取。
- **开箱即用的多租户** — 为整个团队部署一台服务器。每个用户只需在Claude侧设置自己的API密钥；服务器上不需要每个用户的配置。
- **凭证更改无需维护** — 当Redmine密码或API密钥更改时，只需更新客户端的Claude配置。服务器不需要更改。
3. **强大的全文搜索**
`search_issues_full` 在主题、描述和所有评论中进行搜索，以AI友好的格式返回结果。
---
## 要求
- Redmine 5.0+（Redmine 5.0+ 需要 `update_journal`）
- Python 3.12
- RHEL（systemd部署） **或** Docker
---
## Redmine初始设置
在使用RedmineMCP之前，请启用Redmine REST API（默认情况下禁用）。
1. 以管理员身份登录
2. **管理 → 设置 → API** 标签 → 勾选 **启用REST Web服务** 并保存
获取API密钥：
1. 从右上角菜单打开 **我的账户**
2. 点击 **显示** 位于 **API访问密钥** 旁边
3. 在Claude Code配置中使用此密钥作为 `X-Redmine-API-Key`
---
## 架构
```
客户端PC（Claude Code / Mac 或 Windows）
↓ HTTP :8000 + 头部（X-Redmine-URL / X-Redmine-API-Key）
服务器（RHEL 或 Docker）
↓ REST API
Redmine
```
---
## 安装
### 选项A — RHEL（systemd）
**1. 将文件传输到服务器**
```bash
ssh root@<服务器> "mkdir -p /tmp/redmine-mcp-stateless"
scp redmine_mcp_interface.py redmine_mcp_server.py requirements.txt \
redmine-mcp-stateless.service install.sh uninstall.sh \
root@<服务器>:/tmp/redmine-mcp-stateless/
```
**2. 运行安装程序**
```bash
cd /tmp/redmine-mcp-stateless
chmod +x install.sh
./install.sh
```
`install.sh` 执行以下操作：
- 预检（根用户、操作系统、Python 3.12、所需文件）
- 创建专用的 `redmine-mcp-stateless` 系统用户
- 将文件复制到 `/opt/redmine-mcp-stateless/` 并创建Python虚拟环境
- 配置logrotate
- 注册并启动systemd服务
- 配置SELinux（将端口8000注册为 `http_port_t` ）
- 在firewalld中打开端口8000
- 验证服务启动和端口监听
**3. 验证**
```bash
systemctl status redmine-mcp-stateless
journalctl -u redmine-mcp-stateless -f
```
**卸载**
```bash
bash uninstall.sh
```
---
### 选项B — Docker
以容器形式运行MCP服务器。需要一个可从主机访问的现有Redmine实例。
**1. 构建并启动**
```bash
docker compose up -d --build
```
**2. 验证**
```bash
docker compose ps
docker compose logs -f redmine-mcp-stateless
```
**停止**
```bash
docker compose down
```
---
## Claude Code 配置
将以下内容添加到 `~/.claude.json`：
**RHEL**
```json
{
"mcpServers": {
"redmine-mcp-stateless": {
"type": "sse",
"url": "http://<服务器-IP>:8000/sse",
"headers": {
"X-Redmine-URL": "https://<您的Redmine>",
"X-Redmine-API-Key": "<您的API密钥>"
}
}
}
}
```
**Docker**
```json
{
"mcpServers": {
"redmine-mcp-stateless": {
"type": "sse",
"url": "http://localhost:8000/sse",
"headers": {
"X-Redmine-URL": "https://<您的Redmine>",
"X-Redmine-API-Key": "<您的API密钥>"
}
}
}
}
```
**stdio传输（用于注册检查/本地使用）**
服务器通常使用SSE（HTTP）运行。设置环境变量 `MCP_TRANSPORT=stdio` 可切换到stdio传输。在此模式下，凭证通过环境变量传递，而不是HTTP头部：
```bash
MCP_TRANSPORT=stdio REDMINE_URL=https://<您的Redmine> REDMINE_API_KEY=<您的API密钥> \
python redmine_mcp_interface.py
```
此模式主要用于MCP注册检查（例如Glama）。对于共享团队部署，请使用SSE。
---
## 可用工具
### 问题
| 工具 | 描述 |
|---|---|
| `list_issues` | 列出问题，可选过滤器（项目、状态、指派人） |
| `get_issue` | 问题详情，包括所有评论和附件 |
| `create_issue` | 创建新问题 |
| `update_issue` | 更新问题或添加评论 |
| `update_journal` | 编辑现有评论（需要Redmine 5.0+） |
| `list_issues_with_journals` | 列出问题和所有评论 — 有助于按指派人审查进度 |
| `search_issues_full` | 跨主题、描述和评论的全文搜索 |
### 项目
| 工具 | 描述 |
|---|---|
| `list_projects` | 列出所有项目 |
| `get_project` | 项目详情 |
### 主数据
| 工具 | 描述 |
|---|---|
| `list_statuses` | 可用的问题状态 |
| `list_trackers` | 可用的跟踪器 |
| `list_priorities` | 可用的优先级 |
| `list_users` | 用户列表（可能需要管理员权限） |
---
## 可检索数据
| 类别 | 字段 |
|---|---|
| **项目** | ID、标识符、名称、描述、状态 |
| **问题** | ID、主题、描述、状态、项目、跟踪器、优先级、指派人、创建时间/更新时间 |
| **日志（评论）** | 评论ID、正文、创建时间、作者 |
| **附件** | 文件ID、文件名、文件大小、MIME类型、描述、作者、创建时间 |
| **状态 / 跟踪器 / 优先级** | ID、名称 |
| **用户** | ID、登录名、名、姓、全名 |
---
## 文件结构
| 文件 | 描述 |
|---|---|
| `redmine_mcp_interface.py` | MCP服务器入口点 |
| `redmine_mcp_server.py` | Redmine REST API客户端 |
| `requirements.txt` | Python依赖项 |
| `Dockerfile` | 容器镜像（python:3.12-slim） |
| `compose.yml` | Docker Compose配置 |
| `redmine-mcp-stateless.service` | systemd单元文件 |
| `install.sh` | RHEL安装脚本 |
| `uninstall.sh` | 卸载脚本 |
| `example-claude-code-config.json` | 示例Claude Code配置 |
---
## 安全说明
- Redmine URL和API密钥 **永远不会存储在服务器上**
- 通过 `X-Redmine-URL` 和 `X-Redmine-API-Key` 头部在每个请求中传递
- 临时存储在 `ContextVar` 中，并在每个请求完成后丢弃
- 在RHEL上，服务作为专用的非特权用户（`redmine-mcp-stateless`）运行
---
## 许可证
MIT
