Redmine MCP Stateless

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

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

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

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

systemctl status redmine-mcp-stateless
journalctl -u redmine-mcp-stateless -f

To uninstall

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

docker compose up -d --build

2. Verify

docker compose ps
docker compose logs -f redmine-mcp-stateless

Stop

docker compose down

---

Claude Code Configuration

Add the following to ~/.claude.json:

RHEL

{
  "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

{
  "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:

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

Projects

Master Data

---

Retrievable Data

---

File Structure

---

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