内容
# 红矿MCP服务器
Claude Code(或其他MCP客户端)中**以自然语言操作Redmine**的MCP服务器。
Windows · macOS · Linux均支持的**pip包**。无论是自托管Redmine还是公司内部Redmine，只需具备API访问密钥即可。
> ⚠️ API密钥和Redmine地址**仅存储在用户PC的`~/.claude.json`中**。服务器仅在本地通过stdio运行，不会向外部发送密钥。
## 提供工具（10个）
| 工具 | 描述 |
|---|---|
| `list_projects` | 项目列表 |
| `list_issues` | 任务列表（项目/负责人/状态/时间过滤） |
| `get_issue` | 任务详情 + 评论 + 附件 |
| `create_issue` | 新建任务 |
| `add_comment` | 在任务中添加评论（可更改状态） |
| `list_wiki_pages` | 维基页面列表 |
| `get_wiki` | 查询维基页面 |
| `update_wiki` | 创建/编辑维基页面 |
| `get_my_today` | 指派给我的任务 + 最近更新的任务（用于晨间通知） |
| `list_enumerations` | 跟踪器/状态/优先级ID列表 |
---
## 🚀 安装 — 两行命令（Windows · macOS · Linux 通用）
### 前期准备（仅需一次）
- Python 3.10 或更高版本（[python.org](https://www.python.org/downloads/) — 安装时勾选 "Add to PATH"）
- `pipx`（[安装指南](https://pipx.pypa.io/stable/installation/)）
- 运行Claude Code一次（自动生成 `~/.claude.json`）
- Redmine API访问密钥（Redmine登录 → 右上角 '我的账户' → 'API访问密钥'）
### 安装命令（推荐：pipx）
```bash
pipx install git+https://github.com/junstellar/redmine-mcp-jun.git
redmine-mcp-setup
```
`redmine-mcp-setup` 会自动：
1. 备份 `~/.claude.json`（`~/.claude.json.backup.YYYYMMDD_HHMMSS`）
2. 输入Redmine服务器URL + API密钥（密钥以控制台密码输入 — 不记录在日志中）
3. 注册 `mcpServers.redmine` 条目
之后**完全关闭Claude Code → 重新启动**，即可激活 `mcp__redmine__*` 10个工具。
### 为什么选择pipx？
- 将CLI工具安装在隔离环境中 → 不污染系统Python
- 绕过 **PEP 668**（Ubuntu 23.04+、Debian 12+、最新Fedora等）环境中 `pip install` 被阻止的问题
- 在所有操作系统上使用相同的命令
### 更新 / 卸载
```bash
pipx upgrade redmine-mcp # 更新后重启Claude Code
redmine-mcp-uninstall # 从 `.claude.json` 中移除条目
pipx uninstall redmine-mcp
```
### 替代方法：普通pip（无pipx时）
```bash
pip install git+https://github.com/junstellar/redmine-mcp-jun.git
redmine-mcp-setup
```
- 在受PEP 668限制的环境中，使用 `pip install --user ...` 或虚拟环境
- 如果没有 `pip`，可使用 `pip3` / `python3 -m pip`
---
## ⚡ 非交互式安装（自动化/批量）
```bash
redmine-mcp-setup --url "https://redmine.example.com" --api-key "在此处输入API密钥" --force
```
---
## 🐧 各操作系统运行状态
| 环境 | 状态 | 备注 |
|---|---|---|
| Windows 10/11 + Python 3.10~3.14 | ✅ 验证通过 | pip / pipx 均可 |
| macOS (Homebrew Python) | ✅ 标准运行 | |
| Ubuntu 22.04 (Python 3.10) | ✅ 标准运行 | |
| Ubuntu 24.04, Debian 12+, 最新Fedora/Arch | ⚠️ **必须使用pipx** | `pip install` 因PEP 668被阻止 |
| Ubuntu 20.04 等 Python 3.8 默认 | ⚠️ 需要升级Python | 使用 `deadsnakes` PPA 或 `pyenv`/`uv` |
| WSL2 | ✅ 与Linux相同 | |
**共同要求：** Redmine API必须启用（管理 → 设置 → API），且可以从网络访问Redmine。如果是公司内网/私有网络Redmine，则需要通过VPN等方式确保可访问。
---
## 使用示例（在Claude Code中）
查询
- "今天我的任务是什么？"
- "显示我的项目任务列表"
- "123号任务的内容是什么？"
- "显示本周更新的任务"
- "显示指派给我的进行中的任务"
创建/编辑
- "在my-project中创建一个名为 'GPU内存不足' 的新任务"
- "在#123上评论 '开始进行'"
- "将#123的状态更改为已结束"
维基
- "显示my-project的维基页面列表"
- "创建my-project的 'Getting Started' 维基页面"
应用
- "总结昨天更新的我的任务，以邮件格式显示"
- "告诉我过去一周我的任务按状态分类的数量"
---
## 手动安装（无需脚本，直接注册）
1. 安装包
```bash
pip install git+https://github.com/junstellar/redmine-mcp-jun.git
```
2. 在 `~/.claude.json` 的 `mcpServers` 部分添加：
```json
{
"mcpServers": {
"redmine": {
"command": "python",
"args": ["-m", "redmine_mcp"],
"env": {
"REDMINE_URL": "https://redmine.example.com",
"REDMINE_API_KEY": "在此处输入您的API密钥",
"PYTHONIOENCODING": "utf-8"
}
}
}
}
```
* Windows: `%USERPROFILE%\.claude.json`
* macOS/Linux: `~/.claude.json`
3. 重启Claude Code
---
## 文件结构
```
redmine-mcp/
├─ pyproject.toml # pip 包元数据
├─ src/
│ └─ redmine_mcp/
│ ├─ __init__.py
│ ├─ __main__.py # python -m redmine_mcp
│ ├─ server.py # MCP服务器本体（10个工具）
│ └─ installer.py # 安装/卸载脚本
├─ install.ps1 # Windows专用包装器（可选）
├─ uninstall.ps1 # Windows专用包装器（可选）
├─ INSTALL_PROMPT.md # 用于Claude Code自动安装的提示
├─ LICENSE # MIT
└─ README.md
```
## 直接运行测试（调试）
stdio模式，直接运行时会等待客户端输入并暂停（使用Ctrl+C退出）。
```bash
REDMINE_URL=https://redmine.example.com \
REDMINE_API_KEY=在此处输入密钥 \
redmine-mcp
```
Windows PowerShell:
```powershell
$env:REDMINE_URL="https://redmine.example.com"
$env:REDMINE_API_KEY="在此处输入密钥"
redmine-mcp
```
---
## 许可证
MIT — 您可以自由使用、修改和分发。详见 [LICENSE](LICENSE)。
