title: Redmine MCP emoji: 🔧 colorFrom: blue colorTo: indigo sdk: docker app_port: 7860 pinned: false

Redmine MCP OAuth Server

A FastMCP HTTP server that exposes 53 Redmine REST endpoints as Model-Context-Protocol tools, behind an OAuth 2.1 Authorization Code flow with mandatory PKCE.

The user logs in with their own Redmine URL + API key — the server holds no second account. The API key is validated against /users/current.json, then mapped to a bearer token used by every subsequent MCP tool call.

Current version: 1.7 (CHANGELOG.md)

Contents

• Features

• Quick start (local Docker)

• Configuration

• Deployment

  • Docker Compose

  • Hugging Face Spaces

  • Render

  • Fly.io, Cloud Run, Railway, plain VPS

• OAuth flow

• Adding the server to an MCP client

• Tools implemented

• Architecture

• Security

• Testing

• Roadmap

• License

Features

• OAuth 2.1 authorization-code flow with mandatory PKCE S256.

• RFC 7591 Dynamic Client Registration so MCP clients can self-register.

• RFC 8252 loopback redirect URIs auto-allowed (works with every desktop MCP client out of the box).

• Refresh tokens with rotation (RFC 6749 §6) — single-use, rolling 30-day TTL.

• RFC 7009 revocation at POST /oauth/revoke.

• CSRF-protected login form with itsdangerous-signed cookies.

• SSRF defense on the user-supplied Redmine URL — DNS-resolved IPs in private / loopback / link-local / multicast / reserved space are refused. httpx.AsyncClient(follow_redirects=False) closes 302 bypasses.

• Per-IP rate limiting on /auth/login (5/min + 20/hour), /oauth/token (10/min), and /oauth/register (5/min).

• Pluggable token store — in-memory by default; opt-in Redis backend with Fernet at-rest encryption of API keys.

• Structured JSON audit log to stdout, with per-request IDs.

• Sanitized upstream errors — Redmine's raw response bodies (version banners, plugin names, occasional stack traces) never reach the MCP client. Just Permission denied. / Not found. / Upstream Redmine error. / parsed 422 validation errors.

• Confirm gate on every destructive tool (delete_* requires confirm=True).

• Health & version endpoints (/healthz, /readyz, /version).

• Portable Docker image — runs unchanged on Hugging Face Spaces (port 7860), Render, Fly.io, Cloud Run, and self-hosted Docker.

Quick start (local Docker)

git clone <repo> && cd redmine_mcp_py
cp .env.example .env

# 1. Generate the secret that signs CSRF cookies
python3 -c 'import secrets; print(secrets.token_urlsafe(32))'
# Paste into .env as REDMINE_MCP_SECRET=...

# 2. (Optional) generate a Fernet key if you want Redis persistence later
python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'

# 3. Run it
docker compose up --build

Open http://localhost:8000/healthz — should return {"status": "ok"}. The MCP endpoint is http://localhost:8000/mcp.

Configuration

All knobs are env-var-driven. Defaults are safe for local dev and production alike, except where noted.

Required

Recommended for production

Token lifetimes (seconds)

Rate limits (per IP)

Other knobs

Deployment

Docker Compose (local or self-hosted)

docker-compose.yml ships with sensible local-dev defaults. Two profiles:

# In-memory store (default profile, ephemeral)
docker compose up --build

# Redis-backed store (sessions survive restart)
docker compose --profile redis up --build

The Redis profile starts a sibling redis:7-alpine with a persistent volume and a healthcheck. Set the corresponding env vars first:

REDMINE_MCP_REDIS_URL=redis://redis:6379/0
REDMINE_MCP_FERNET_KEY=<paste-Fernet.generate_key()-output>

Hugging Face Spaces

The README.md frontmatter (top of this file) is HF metadata; HF reads sdk: docker and app_port: 7860 and runs the bundled Dockerfile.

1. Push the repo to a Space with sdk: docker.

2. In Settings → Variables and secrets, set:

   • REDMINE_MCP_SECRET (required — generate fresh)

   • REDMINE_MCP_TRUST_PROXY=true (HF sits behind a proxy)

   • REDMINE_MCP_ALLOWED_HOSTS=<your-redmine-host> (recommended)

3. Restart the Space.

⚠ HF Spaces free tier sleeps after 15 min idle — cold start wipes the in-memory token store, forcing users to reconnect. For always-on behavior either upgrade to a paid tier or enable Redis (point REDMINE_MCP_REDIS_URL at an external Redis like Upstash, since HF doesn't provide one).

Render

The repo includes render.yaml for one-click Blueprint deploys.

1. Push to GitHub/GitLab.

2. Render dashboard → New + → Blueprint → connect the repo → Apply.

3. In the service's Environment tab, fill in the two sync: false values:

   • REDMINE_MCP_ALLOWED_HOSTS (recommended — CSV of permitted Redmine hostnames)

   • REDMINE_MCP_ALLOWED_REDIRECTS (leave empty for desktop MCP clients)

4. First build takes ~3 min. You get https://redmine-mcp-XXXX.onrender.com.

The blueprint defaults to plan: free, which sleeps after 15 min idle like HF. Change to plan: starter ($7/mo) for always-on, or keep free and add Render's Key Value (Redis-compatible) addon for persistence across cold starts.

Fly.io, Cloud Run, Railway, plain VPS

The Dockerfile listens on ${PORT:-7860} and runs as UID 1000 with a baked-in HEALTHCHECK. It works unchanged on any platform that builds a Dockerfile.

Minimum env vars: REDMINE_MCP_SECRET, REDMINE_MCP_TRUST_PROXY=true (when behind a proxy), and ideally REDMINE_MCP_ALLOWED_HOSTS.

For self-hosted behind nginx / Caddy / Traefik, terminate TLS at the proxy and forward to the container's ${PORT}. Add proxy_set_header X-Forwarded-For $remote_addr; (nginx) or equivalent so rate-limit attribution works.

OAuth flow

User clicks "Connect" in Claude Desktop / Coworks / custom MCP client
  ↓
GET  /oauth/register              (DCR — client registers its redirect_uri)
  ↓
GET  /auth/authorize?response_type=code
                    &client_id=<dcr-issued>
                    &redirect_uri=http://127.0.0.1:<port>/callback
                    &code_challenge=<S256(verifier)>
                    &code_challenge_method=S256
                    &state=<csrf-state>
  → server returns the HTML login form + a CSRF cookie
  ↓
POST /auth/login                  (user submits Redmine URL + API key)
  → server validates creds against /users/current.json on that URL
  → server mints a single-use auth code, 302s to redirect_uri?code=...&state=...
  ↓
POST /oauth/token                 (PKCE verification, code exchange)
  → server returns {access_token, refresh_token, token_type, expires_in}
  ↓
Every MCP tool call carries the access_token as Bearer
  → looked up in the token store → Redmine API key extracted → upstream call
  ↓
POST /oauth/token (grant_type=refresh_token) once the access token expires
  → old refresh_token consumed atomically (GETDEL in Redis), new pair issued
  ↓
POST /oauth/revoke (optional, on logout)

The user only ever supplies their own Redmine credentials — no second account is required on the MCP server side.

Adding the server to an MCP client

Claude Desktop, Claude Code, Coworks, …

Settings → Connectors → Add custom connector → URL = https://your-server/mcp.

OAuth Client ID and Secret can be left blank — the server is a public OAuth client (token_endpoint_auth_method: none). The real credential is the user's Redmine API key, captured during /auth/login.

From the Anthropic API or other MCP SDKs

Use the standard MCP streamable-http transport pointed at https://your-server/mcp. The SDK handles DCR + PKCE automatically.

Tools implemented

All 53 tools accept structured arguments and return raw Redmine JSON (or {} for 204 No Content responses). Tools that mutate state require their respective Redmine role/permission. Destructive delete_* tools require confirm=True.

limit parameters are clamped to 1..100 (Redmine's hard server-side max). create_issue_relation.relation_type, create_version.status, and create_version.sharing use typing.Literal so the MCP tool schema surfaces the allowed values to the LLM.

Architecture

┌──────────────────────┐
│  MCP client          │  Claude Desktop / Coworks / custom SDK
│  (loopback callback) │
└──────────┬───────────┘
           │ HTTPS
┌──────────▼─────────────────────────────────────────────────────────────┐
│  FastAPI app (server.py)                                               │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │  RequestIDMiddleware   →  contextvar request_id                   │  │
│  │  SecurityHeadersMiddleware → HSTS, CSP, X-Frame-Options, …        │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│  ┌─────────────────────────┐  ┌────────────────────────────────────┐   │
│  │  auth/routes.py         │  │  53 MCP tools (FastMCP)            │   │
│  │  /auth/authorize        │  │  list_issues, create_project, …    │   │
│  │  /auth/login            │  │  call _redmine() → outbound httpx  │   │
│  │  /oauth/token           │  │  with SSRF re-validation + audit   │   │
│  │  /oauth/revoke          │  │                                    │   │
│  │  /oauth/register        │  │                                    │   │
│  └─────────────┬───────────┘  └────────────┬───────────────────────┘   │
│                │                           │                           │
│  ┌─────────────▼───────────────────────────▼───────────────────────┐   │
│  │  auth/token_store.py — TokenStore Protocol                      │   │
│  │  ┌─────────────────────┐    ┌────────────────────────────────┐  │   │
│  │  │ InMemoryTokenStore  │ OR │ RedisTokenStore                │  │   │
│  │  │ (default)           │    │ (Fernet-encrypted API keys)    │  │   │
│  │  └─────────────────────┘    └────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  audit.py — one-line JSON to stdout                             │   │
│  │  login_ok / login_rejected / token_issued / token_refreshed /   │   │
│  │  token_revoked / rate_limit_exceeded / redmine_call             │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────────────────┘
                                            │
                                            │ httpx, follow_redirects=False
                                            ▼
                              ┌───────────────────────────────┐
                              │  User's Redmine instance      │
                              │  X-Redmine-API-Key: <secret>  │
                              └───────────────────────────────┘

Key invariants:

• API keys are wrapped in RedactedStr (returns '***' from repr/ str); they only reach the outbound HTTP path via .reveal().

• Every outbound URL is re-validated against the SSRF block-list on every call, not just at login.

• The CSRF cookie is HttpOnly, SameSite=Lax, Secure (unless REDMINE_MCP_ALLOW_HTTP=true), path-scoped to /auth/.

• Audit records never contain API keys, query params, request bodies, or response bodies — only method, path, status, latency, and the operator's Redmine login.

Security

SECURITY.md documents the threat model, every defect found during the Phase 0 review, the fix, and the regression test that pins it.

Vulnerabilities should be reported privately to the maintainer rather than as a public GitHub issue.

Testing

pip install -r requirements.txt
pip install pytest pytest-asyncio respx
pytest

Currently 60 tests covering Phase 0 + Phase 1 (~2s on a laptop) plus 2 opt-in Redis tests, run with:

docker run --rm -d -p 6379:6379 --name redis-test redis:7-alpine
REDMINE_MCP_TEST_REDIS_URL=redis://localhost:6379/15 pytest
docker stop redis-test

Roadmap

TODO.md tracks remaining work. Phase 0 (critical security) and Phase 1 (high-priority hardening) are complete. Phase 2 (reliability + code quality: modularization, shared httpx client, retries, CI, ruff/mypy) and Phase 3 (operability: Prometheus metrics, pydantic-settings, multi-stage Dockerfile) are the next chunks.

License

MIT