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