Content
# Redmine MCP Server
Claude Code(또는 다른 MCP 클라이언트)에서 **Redmine을 자연어로** 다룰 수 있게 해주는 MCP 서버.
Windows · macOS · Linux 모두 지원하는 **pip 패키지**입니다. 자체 호스팅(self-hosted) Redmine이든 사내 Redmine이든, API 접근키만 있으면 됩니다.
> ⚠️ API 키와 Redmine 주소는 **사용자 PC의 `~/.claude.json`에만** 저장됩니다. 서버는 stdio로 로컬에서만 동작하며, 외부로 키를 보내지 않습니다.
## Tool List
| Tool | Description |
|---|---|
| `list_projects` | List projects |
| `list_issues` | List issues (project/assignee/status/period filter) |
| `get_issue` | Get issue details + comments + attachments |
| `create_issue` | Create a new issue |
| `add_comment` | Add a comment to an issue (status change possible) |
| `list_wiki_pages` | List wiki pages |
| `get_wiki` | Get a wiki page |
| `update_wiki` | Create/update a wiki page |
| `get_my_today` | Get assigned issues + recently updated issues (for morning notifications) |
| `list_enumerations` | List tracker/status/priority IDs |
---
## 🚀 Installation — Two lines (Windows · macOS · Linux common)
### Prerequisites (once)
- Python 3.10 or higher ([python.org](https://www.python.org/downloads/) — check "Add to PATH" during installation)
- `pipx` ([installation guide](https://pipx.pypa.io/stable/installation/))
- Run Claude Code at least once (`~/.claude.json` is automatically created)
- Redmine API access key (Redmine login → top right 'My account' → 'API access key')
### Installation command (recommended: pipx)
```bash
pipx install git+https://github.com/junstellar/redmine-mcp-jun.git
redmine-mcp-setup
```
`redmine-mcp-setup` will automatically:
1. Backup `~/.claude.json` (`~/.claude.json.backup.YYYYMMDD_HHMMSS`)
2. Prompt for Redmine server URL and API key (key is input like a console password — no log)
3. Register `mcpServers.redmine` entry
Then, **completely exit Claude Code → restart** to activate the `mcp__redmine__*` tools.
### Why pipx?
- Install CLI tools in an isolated environment → no pollution of system Python
- Avoid `pip install` blockage in **PEP 668** environments (Ubuntu 23.04+, Debian 12+, latest Fedora, etc.)
- Same command works on all OS
### Update / Uninstall
```bash
pipx upgrade redmine-mcp # Update and restart Claude Code
redmine-mcp-uninstall # Remove entry from .claude.json
pipx uninstall redmine-mcp
```
### Alternative: regular pip (when pipx is not available)
```bash
pip install git+https://github.com/junstellar/redmine-mcp-jun.git
redmine-mcp-setup
```
- In PEP 668 blocked environments, use `pip install --user ...` or a virtual environment
- If `pip` is not available, use `pip3` / `python3 -m pip`
---
## ⚡ Non-interactive Installation (Automation/Batch)
```bash
redmine-mcp-setup --url "https://redmine.example.com" --api-key "your_api_key_here" --force
```
---
## 🐧 OS-specific Status
| Environment | Status | Notes |
|---|---|---|
| Windows 10/11 + Python 3.10~3.14 | ✅ Verified | pip / pipx both OK |
| macOS (Homebrew Python) | ✅ Standard behavior | |
| Ubuntu 22.04 (Python 3.10) | ✅ Standard behavior | |
| Ubuntu 24.04, Debian 12+, latest Fedora/Arch | ⚠️ **pipx required** | `pip install` blocked by PEP 668 |
| Ubuntu 20.04 with Python 3.8 default | ⚠️ Python upgrade required | use `deadsnakes` PPA or `pyenv`/`uv` |
| WSL2 | ✅ Same as Linux | |
**Common requirements:** Redmine API must be enabled (Admin → Settings → API), and the Redmine server must be accessible over the network. If it's an internal/private network Redmine, ensure it's accessible via VPN, etc.
---
## Usage Examples (inside Claude Code)
Query
- "Summarize my tasks for today"
- "Show me the issue list for my-project"
- "What was the content of issue 123?"
- "Show me the updated issues for this week"
- "List my assigned issues that are in progress"
Create/Edit
- "Create a new issue in my-project with 'GPU memory shortage'"
- "Add a comment '#123 is in progress'"
- "Change the status of #123 to closed"
Wiki
- "List the wiki pages for my-project"
- "Create a new wiki page 'Getting Started' for my-project"
Application
- "Summarize my updated tasks in an email format"
- "Count the number of issues by status for the last week"
---
## Manual Installation (without script)
1. Package installation
```bash
pip install git+https://github.com/junstellar/redmine-mcp-jun.git
```
2. Add the `mcpServers` section to `~/.claude.json`:
```json
{
"mcpServers": {
"redmine": {
"command": "python",
"args": ["-m", "redmine_mcp"],
"env": {
"REDMINE_URL": "https://redmine.example.com",
"REDMINE_API_KEY": "your_api_key_here",
"PYTHONIOENCODING": "utf-8"
}
}
}
}
```
* Windows: `%USERPROFILE%\.claude.json`
* macOS/Linux: `~/.claude.json`
3. Restart Claude Code
---
## File Structure
```
redmine-mcp/
├─ pyproject.toml # pip package metadata
├─ src/
│ └─ redmine_mcp/
│ ├─ __init__.py
│ ├─ __main__.py # python -m redmine_mcp
│ ├─ server.py # MCP server main (10 tools)
│ └─ installer.py # installation/removal script
├─ install.ps1 # Windows-specific wrapper (optional)
├─ uninstall.ps1 # Windows-specific wrapper (optional)
├─ INSTALL_PROMPT.md # Claude Code prompt to auto-install
├─ LICENSE # MIT
└─ README.md
```
## Direct Execution Test (Debug)
stdio mode will wait for client input (exit with Ctrl+C).
```bash
REDMINE_URL=https://redmine.example.com \
REDMINE_API_KEY=your_api_key_here \
redmine-mcp
```
Windows PowerShell:
```powershell
$env:REDMINE_URL="https://redmine.example.com"
$env:REDMINE_API_KEY="your_api_key_here"
redmine-mcp
```
---
## License
MIT — feel free to use, modify, and distribute. See [LICENSE](LICENSE) for details.
