RedmineMCP

An MCP (Model Context Protocol) server that lets 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

Context-First Design

Returns journals (comments) alongside issues so the AI can reason about history, generate accurate follow-up proposals, and summarize progress.

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.

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

---

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>" } } } } ``

---

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

redmine-mcp-stateless