# Redmine MCP Server

An MCP server that lets you work with **Redmine in natural language** from Claude Code (or any other MCP client).
Shipped as a **pip package** supporting Windows, macOS, and Linux. Works with any self-hosted or corporate Redmine — all you need is an API access key.

> ⚠️ Your API key and Redmine URL are stored **only in `~/.claude.json` on your own machine**. The server runs locally over stdio and never sends your key anywhere.

## Provided Tools (10)

| Tool | Description |
|---|---|
| `list_projects` | List projects |
| `list_issues` | List issues (filter by project/assignee/status/date range) |
| `get_issue` | Issue details + comments + attachments |
| `create_issue` | Create a new issue |
| `add_comment` | Add a comment to an issue (can also change status) |
| `list_wiki_pages` | List wiki pages |
| `get_wiki` | Read a wiki page |
| `update_wiki` | Create/update a wiki page |
| `get_my_today` | Issues assigned to me + recently updated issues (morning briefing) |
| `list_enumerations` | List tracker/status/priority IDs |

---

## 🚀 Install — Two Lines (Windows · macOS · Linux)

### Prerequisites (one-time)
- Python 3.10+ ([python.org](https://www.python.org/downloads/) — check "Add to PATH" during install)
- `pipx` ([installation guide](https://pipx.pypa.io/stable/installation/))
- Claude Code launched at least once (auto-creates `~/.claude.json`)
- A Redmine API access key (log in to Redmine → top-right "My account" → "API access key")

### Install command (recommended: pipx)

```bash
pipx install git+https://github.com/junstellar/redmine-mcp-jun.git
redmine-mcp-setup
```

`redmine-mcp-setup` automatically:
1. Backs up `~/.claude.json` (`~/.claude.json.backup.YYYYMMDD_HHMMSS`)
2. Prompts for your Redmine server URL + API key (the key is entered as a console password — never logged)
3. Registers the `mcpServers.redmine` entry

Then **fully quit and restart Claude Code** — the 10 `mcp__redmine__*` tools become available.

### Why pipx?
- Installs CLI tools into isolated environments → keeps your system Python clean
- Avoids the **PEP 668** restriction (Ubuntu 23.04+, Debian 12+, recent Fedora, etc.) where plain `pip install` is blocked
- Same command on every OS

### Update / Uninstall

```bash
pipx upgrade redmine-mcp          # then restart Claude Code

redmine-mcp-uninstall             # removes the entry from .claude.json
pipx uninstall redmine-mcp
```

### Alternative: plain pip (no pipx)

```bash
pip install git+https://github.com/junstellar/redmine-mcp-jun.git
redmine-mcp-setup
```

- On PEP 668-restricted systems, use `pip install --user ...` or a virtual environment
- If `pip` is missing, try `pip3` / `python3 -m pip`

---

## ⚡ Non-Interactive Install (automation/batch)

```bash
redmine-mcp-setup --url "https://redmine.example.com" --api-key "YOUR_API_KEY" --force
```

---

## 🐧 Status by OS

| Environment | Status | Notes |
|---|---|---|
| Windows 10/11 + Python 3.10–3.14 | ✅ Verified | Both pip and pipx OK |
| macOS (Homebrew Python) | ✅ Works as standard | |
| Ubuntu 22.04 (Python 3.10) | ✅ Works as standard | |
| Ubuntu 24.04, Debian 12+, recent Fedora/Arch | ⚠️ **pipx required** | plain `pip install` blocked by PEP 668 |
| Ubuntu 20.04 and other Python 3.8 defaults | ⚠️ Python upgrade needed | `deadsnakes` PPA or `pyenv`/`uv` |
| WSL2 | ✅ Same as Linux | |

**Common requirements:** the Redmine REST API must be enabled (Administration → Settings → API) and the Redmine server must be reachable from your machine. For internal/private-network Redmine, make sure you're on VPN etc.

---

## Usage Examples (inside Claude Code)

Reading
- "Summarize my issues for today"
- "Show me the issue list for my-project"
- "What was issue #123 about?"
- "Show issues updated this week"
- "Show only in-progress issues assigned to me"

Writing
- "Create a new issue 'GPU out of memory' in my-project"
- "Comment 'Starting work on this' on #123"
- "Change the status of #123 to Closed"

Wiki
- "List the wiki pages of my-project"
- "Create a 'Getting Started' wiki page in my-project"

Beyond
- "Summarize my issues updated yesterday as an email body"
- "Count my issues from the past week by status"

---

## Manual Install (register without the setup script)

1. Install the package
   ```bash
   pip install git+https://github.com/junstellar/redmine-mcp-jun.git
   ```

2. Add to the `mcpServers` section of `~/.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

---

## Project Layout

```
redmine-mcp/
├─ pyproject.toml          # pip package metadata
├─ src/
│  └─ redmine_mcp/
│     ├─ __init__.py
│     ├─ __main__.py       # python -m redmine_mcp
│     ├─ server.py         # MCP server core (10 tools)
│     └─ installer.py      # setup/uninstall scripts
├─ install.ps1             # optional Windows wrapper
├─ uninstall.ps1           # optional Windows wrapper
├─ INSTALL_PROMPT.md       # paste-into-Claude-Code auto-install prompt
├─ LICENSE                 # MIT
└─ README.md
```

## Running Directly (debug)

It's a stdio-mode server, so running it directly just waits for client input (quit with Ctrl+C).

```bash
REDMINE_URL=https://redmine.example.com \
REDMINE_API_KEY=YOUR_KEY \
redmine-mcp
```

Windows PowerShell:
```powershell
$env:REDMINE_URL="https://redmine.example.com"
$env:REDMINE_API_KEY="YOUR_KEY"
redmine-mcp
```

---

## License

MIT — use, modify, and distribute freely. See [LICENSE](LICENSE).