Content
# RedmineMCP
An MCP (Model Context Protocol) server that lets [Claude Code](https://claude.ai/claude-code) operate Redmine directly.
Runs as an HTTP server on RHEL or Docker. Credentials are never stored on the server — they are passed per-request via HTTP headers from the Claude Code configuration file.
---
## Key Features
1. **Context-First Design**
Returns journals (comments) alongside issues so the AI can reason about history, generate accurate follow-up proposals, and summarize progress.
2. **Stateless Design**
API keys are passed per-request from the client and never stored on the server. This brings three practical benefits:
- **Maximum security** — Even if the server is compromised, there are no API keys stored on it to steal.
- **Multi-tenant out of the box** — Deploy one server for the whole team. Each user simply sets their own API key on the Claude side; no per-user configuration is needed on the server.
- **Zero maintenance for credential changes** — When a Redmine password or API key changes, only the client-side Claude configuration needs updating. The server requires no changes.
3. **Powerful Full-Text Search**
`search_issues_full` searches across subject, description, and all comments, returning results in an AI-friendly format.
---
## Requirements
- Redmine 5.0+ (Redmine 5.0+ required for `update_journal`)
- Python 3.12
- RHEL (systemd deployment) **or** Docker
---
## Redmine Initial Setup
Before using RedmineMCP, enable the Redmine REST API (disabled by default).
1. Log in as an administrator
2. **Administration → Settings → API** tab → check **Enable REST web service** and save
To get an API key:
1. Open **My account** from the top-right menu
2. Click **Show** next to **API access key**
3. Use this key as `X-Redmine-API-Key` in the Claude Code configuration
---
## Architecture
```
Client PC (Claude Code / Mac or Windows)
↓ HTTP :8000 + headers (X-Redmine-URL / X-Redmine-API-Key)
Server (RHEL or Docker)
↓ REST API
Redmine
```
---
## Installation
### Option A — RHEL (systemd)
**1. Transfer files to the server**
```bash
ssh root@<server> "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@<server>:/tmp/redmine-mcp-stateless/
```
**2. Run the installer**
```bash
cd /tmp/redmine-mcp-stateless
chmod +x install.sh
./install.sh
```
`install.sh` performs the following:
- Pre-flight checks (root, OS, Python 3.12, required files)
- Creates a dedicated `redmine-mcp-stateless` system user
- Copies files to `/opt/redmine-mcp-stateless/` and creates a Python virtual environment
- Configures logrotate
- Registers and starts a systemd service
- Configures SELinux (registers port 8000 as `http_port_t`)
- Opens port 8000 in firewalld
- Verifies service startup and port listening
**3. Verify**
```bash
systemctl status redmine-mcp-stateless
journalctl -u redmine-mcp-stateless -f
```
**To uninstall**
```bash
bash uninstall.sh
```
---
### Option B — Docker
Runs the MCP server as a container. Requires an existing Redmine instance accessible from the host.
**1. Build and start**
```bash
docker compose up -d --build
```
**2. Verify**
```bash
docker compose ps
docker compose logs -f redmine-mcp-stateless
```
**Stop**
```bash
docker compose down
```
---
## Claude Code Configuration
Add the following to `~/.claude.json`:
**RHEL**
```json
{
"mcpServers": {
"redmine-mcp-stateless": {
"type": "sse",
"url": "http://<server-IP>:8000/sse",
"headers": {
"X-Redmine-URL": "https://<your-redmine>",
"X-Redmine-API-Key": "<your-api-key>"
}
}
}
}
```
**Docker**
```json
{
"mcpServers": {
"redmine-mcp-stateless": {
"type": "sse",
"url": "http://localhost:8000/sse",
"headers": {
"X-Redmine-URL": "https://<your-redmine>",
"X-Redmine-API-Key": "<your-api-key>"
}
}
}
}
```
**stdio transport (for registry inspection / local use)**
The server normally runs with SSE (HTTP). Setting the environment variable `MCP_TRANSPORT=stdio` switches it to stdio transport. In this mode, credentials are passed via environment variables instead of HTTP headers:
```bash
MCP_TRANSPORT=stdio REDMINE_URL=https://<your-redmine> REDMINE_API_KEY=<your-api-key> \
python redmine_mcp_interface.py
```
This mode exists mainly for MCP registry inspection (e.g. Glama). Use SSE for shared team deployment.
---
## Available Tools
### Issues
| Tool | Description |
|---|---|
| `list_issues` | List issues with optional filters (project, status, assignee) |
| `get_issue` | Issue details including all comments and attachments |
| `create_issue` | Create a new issue |
| `update_issue` | Update an issue or add a comment |
| `update_journal` | Edit an existing comment (requires Redmine 5.0+) |
| `list_issues_with_journals` | List issues with all comments — useful for per-assignee progress review |
| `search_issues_full` | Full-text search across subject, description, and comments |
### Projects
| Tool | Description |
|---|---|
| `list_projects` | List all projects |
| `get_project` | Project details |
### Master Data
| Tool | Description |
|---|---|
| `list_statuses` | Available issue statuses |
| `list_trackers` | Available trackers |
| `list_priorities` | Available priorities |
| `list_users` | User list (may require admin privileges) |
---
## Retrievable Data
| Category | Fields |
|---|---|
| **Project** | ID, identifier, name, description, status |
| **Issue** | ID, subject, description, status, project, tracker, priority, assignee, created/updated date |
| **Journal (comment)** | comment ID, body, created date, author |
| **Attachment** | file ID, filename, file size, MIME type, description, author, created date |
| **Status / Tracker / Priority** | ID, name |
| **User** | ID, login, first name, last name, full name |
---
## File Structure
| File | Description |
|---|---|
| `redmine_mcp_interface.py` | MCP server entry point |
| `redmine_mcp_server.py` | Redmine REST API client |
| `requirements.txt` | Python dependencies |
| `Dockerfile` | Container image (python:3.12-slim) |
| `compose.yml` | Docker Compose configuration |
| `redmine-mcp-stateless.service` | systemd unit file |
| `install.sh` | RHEL installation script |
| `uninstall.sh` | Uninstallation script |
| `example-claude-code-config.json` | Example Claude Code configuration |
---
## Security Notes
- Redmine URL and API key are **never stored on the server**
- Passed per-request via `X-Redmine-URL` and `X-Redmine-API-Key` headers
- Stored temporarily in a `ContextVar` and discarded after each request completes
- On RHEL, the service runs as a dedicated unprivileged user (`redmine-mcp-stateless`)
---
## License
MIT
