mcp-redmine-rd — Redmine MCP for Claude Code

Brings Redmine bug tickets — description, comments, custom fields, and screenshots as viewable images — into Claude Code, and ships a /fix-bug skill that drives a ticket to a verified fix. Built with FastMCP 3.

It authenticates to Redmine with your own API key, needs no admin rights, and launches over stdio so your MCP client starts it on demand. Each developer runs it with their own key, so every read and write to the tracker is attributed to them.

How it works

MCP Client (Claude Code, MCP Inspector, …)
        │  MCP over stdio (launched on demand)
        ▼
┌───────────────────────────────────┐
│           mcp-redmine-rd          │
│  authenticates with your Redmine  │──── REST API ───▶ Redmine
│  API key (X-Redmine-API-Key)      │◀────────────────
│  Tools + /fix-bug skill           │
└───────────────────────────────────┘

Related MCP server: Redmine MCP Server

Prerequisites

• Python 3.11+

• A Redmine instance with the REST API enabled (Administration → Settings → API → Enable REST web service)

• Your personal API key: My account → API access key → Show. No admin rights needed.

Quickstart (local mode)

git clone https://github.com/Jebershon/mcp-redmine-rd.git
cd mcp-redmine-rd
python -m venv .venv && . .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .
cp .env.example .env
# set REDMINE_URL and REDMINE_API_KEY in .env

Open the repo in Claude Code — .mcp.json launches the server over stdio automatically, and the redmine tools plus /fix-bug are ready. Try /fix-bug 1234.

To run the server standalone over HTTP instead of stdio, mcp-redmine-rd serves http://127.0.0.1:8000/mcp; point your client at it with header Authorization: Bearer <MCP_LOCAL_TOKEN> (default local).

Sharing with your team

The easiest way to give co-developers both the server and the /fix-bug skill is one git repo. Committed to it are .mcp.json (wires up the MCP server) and .claude/skills/fix-bug/ (the skill). Secrets are not: each developer keeps their own API key in a gitignored .env.

.mcp.json launches the server over stdio, so there is no port to manage and no server to start by hand:

{
  "mcpServers": {
    "redmine": {
      "command": "mcp-redmine-rd-local",
      "env": { "REDMINE_URL": "https://tracker.rapiddata.com" }
    }
  }
}

A developer's one-time setup

Prerequisites: Python 3.11+, git, and Claude Code. Check Python with python --version (use python3 on macOS/Linux if python points at 2.x).

1. Clone the repo and enter it

git clone https://github.com/Jebershon/mcp-redmine-rd.git
cd mcp-redmine-rd

2. Create and activate a virtual environment

A venv keeps this project's dependencies isolated. Activating it also puts the mcp-redmine-rd-local command on your PATH, which .mcp.json needs.

python -m venv .venv

Activate it — pick the line for your shell:

source .venv/bin/activate        # macOS / Linux
.venv\Scripts\Activate.ps1       # Windows PowerShell
source .venv/Scripts/activate    # Windows Git Bash

Your prompt should now show (.venv).

3. Install the server

pip install -e .

Confirm the launch command is available (this is what .mcp.json runs):

mcp-redmine-rd-local --help  ||  echo "not on PATH — is the venv active?"

4. Get your personal Redmine API key

In Redmine (https://tracker.rapiddata.com): click your name (top right) → My account → in the right sidebar, API access key → Show. Copy the 40-character key. It acts as your account — treat it like a password.

5. Create your .env file

The server reads your key from a local .env that is gitignored — it is never committed and never shared. REDMINE_URL already comes from .mcp.json, so .env only needs your key:

cp .env.example .env

Open .env and set:

REDMINE_API_KEY=<paste-your-40-char-key>

6. Verify it works (optional but recommended)

Run the test suite to confirm the install is healthy:

pip install pytest pytest-asyncio
pytest -q

7. Open the repo in Claude Code

Launch Claude Code from this repo directory, with the venv still active (so the command is on PATH):

claude

Claude Code reads .mcp.json, starts the redmine server over stdio on demand, and the tools plus the /fix-bug skill become available. Verify inside Claude Code with /mcp — you should see redmine connected — then try /fix-bug <an issue number>.

If redmine doesn't connect, the mcp-redmine-rd-local command isn't on PATH — you most likely launched Claude Code without the venv active. Either activate the venv first, or edit .mcp.json's command to the script's absolute path (.venv/Scripts/mcp-redmine-rd-local.exe on Windows, .venv/bin/mcp-redmine-rd-local on macOS/Linux).

Environment variables

Available tools & resources

The "Redmine permission" column is what your API key's account role must grant — a tool returns a descriptive error if your account lacks the permission.

Planned: attachment upload, structured logging.

Custom fields

create_issue, update_issue, create_project, and update_project accept a custom_fields map keyed by field name or numeric field ID:

{"Severity": "High", "Affected version": "2.4.1", "7": ["iOS", "Android"]}

Use a list for multi-value fields. Booleans are encoded as Redmine expects them ("1" / "0", not "true" / "false"). On update, only the fields you pass are touched — the rest keep their current values.

Name resolution calls /custom_fields.json, which Redmine restricts to admins. For a non-admin user, names cannot be resolved and the tool says so, telling the caller to pass numeric IDs instead. Those IDs are listed next to each custom field by get_issue_details and get_project_details, so the workflow still closes without admin rights. The name→ID map is cached for 10 minutes once fetched.

Screenshots

get_issue_details returns image content blocks for any image attached to the issue — including images added in later comments, which is usually where the useful screenshot lives. Images are downscaled to 1500px on the long edge and re-encoded as PNG before being returned; a 3000×2000 screenshot comes back at roughly a quarter of its original size. At most four are inlined per call (the most recent ones); the rest are listed by name and can be fetched individually with get_issue_attachment.

An attachment that is missing, oversized, or undecodable degrades to a text note — it never fails the whole call.

The /fix-bug skill

.claude/skills/fix-bug/SKILL.md drives the full loop: read the ticket and its screenshots → locate the cause → reproduce → fix → verify → report back to the ticket. The MCP server is the plumbing; the skill is what makes a bug fix fast.

When you open this repo in Claude Code, the skill is picked up automatically. To use it while working in a different repository, copy it there:

mkdir -p your-app/.claude/skills
cp -r .claude/skills/fix-bug your-app/.claude/skills/

Then /fix-bug 1234, or just "fix #1234".

The skill will not write to Redmine without asking, and will not close a ticket on its own. It also treats issue text as untrusted input — anyone who can file a bug can write instructions aimed at the model in the repro steps.

Connect Claude Code automatically

Opening this repo in Claude Code connects the server automatically via .mcp.json — nothing else to do.

To make the redmine tools available in every project (not just this repo), register the server once at user scope. With the venv active, run:

claude mcp add redmine --scope user \
  --env REDMINE_URL=https://tracker.rapiddata.com \
  --env REDMINE_API_KEY=<your-40-char-key> \
  -- mcp-redmine-rd-local

Claude Code now starts the server on demand in any project. Confirm with:

claude mcp list        # should show: redmine

or /mcp inside a Claude Code session (look for redmine connected). Remove it again any time with claude mcp remove redmine --scope user.

The command (mcp-redmine-rd-local) must be resolvable when Claude Code launches it. If you registered it from a venv, keep that venv active, or use the script's absolute path in place of the bare command (.venv/Scripts/mcp-redmine-rd-local.exe on Windows, .venv/bin/mcp-redmine-rd-local on macOS/Linux).

License

MIT — see LICENSE. Forked from tuzumkuru/mcp-redmine-oauth.