Skip to main content
Glama
redmine-mcp-server

redmine-mcp-server

Redmine MCP Server

CI Release License Java 25 MCP Glama score Listed on mcpservers.org

A local MCP server for accessing a corporate Redmine instance. It exposes a limited set of write operations for issues, time entries, and wiki alongside the read tools; set REDMINE_MCP_WRITE_ENABLED=false to run fully read-only. It lets AI agents (Claude Code, Cursor, VS Code Copilot, etc.) work with issues, projects, members, versions, wiki, attachments, time entries, and reference data.

Quick Start

This documentation covers installing and connecting Redmine MCP Server itself. Installing and configuring the AI clients themselves is out of scope here.

  1. Install JDK 25+.

  2. Download redmine-mcp-server.jar from the latest release, or build it yourself: ./gradlew bootJar (see Build). A Docker image is published as well.

  3. Obtain REDMINE_URL and REDMINE_API_KEY (see Configuration).

  4. Verify that the JAR starts (see Smoke Test).

  5. Add the JAR to your client's MCP configuration (see Connecting to an AI Client).

For Claude Code that is one command:

claude mcp add --scope user -e REDMINE_URL=https://redmine.example.com -e REDMINE_API_KEY=your_key -- redmine java -jar /path/to/redmine-mcp-server.jar

Related MCP server: Redmine MCP Server

Architecture

The server supports only the stdio transport.

Stdio

┌─────────────┐     stdio      ┌──────────────────┐    REST API    ┌──────────┐
│  AI agent   │ <------------> │  redmine-mcp-    │ -------------> │ Redmine  │
│ (Claude Code│   stdin/stdout │  server (Java)   │   HTTP + API   │ (corp.)  │
│  Cursor...) │                │                  │   Key          │          │
└─────────────┘                └──────────────────┘                └──────────┘

The AI client launches the server as a child process; communication follows the MCP protocol over stdin/stdout.

Tools

The server exports 32 read-only MCP tools plus 7 write tools by default. Set REDMINE_MCP_WRITE_ENABLED=false to remove the write tools and run fully read-only.

User

Tool

Description

getCurrentUser

Current user: ID, login, groups, projects. Useful for "my issues" filtering

Projects

Tool

Description

listProjects

List of all accessible projects

getProject

Project details: trackers, modules, description

listProjectMembers

Project members with roles

listVersions

Project versions (milestones)

Issues

Tool

Description

listIssues

Issue list with filters: project, status, tracker, assignee, priority, version, saved query, custom fields (customFieldFilters in cf_<id>=value format), sorting

searchIssues

Full-text issue search with detailed results

getIssue

Issue details: description, status, assignee, dates, notes, relations, custom fields, attachments, linked revisions (changesets). Parameters: issueId, focus (default, implementation, timeline, full; optional)

getIssueJournal

A single complete issue journal note/event without response compression. Parameters: issueId, journalId

getMyIssues

Issues of the current user. Parameters: projectId, statusId, sort, limit, offset

getIssueTree

Parent chain and subtasks. root and ancestors keep the Issue JSON shape but contain compact context; call getIssue for full details or relations. Parameters: issueId, depth (default 2, max 5)

getIssueHistory

Creation and every journal event, with status intervals. Long text is shortened; journalId identifies the full entry for getIssueJournal. Follow nextOffset with the optional offset parameter until it is absent.

Issue, Time Entry, and Wiki Writes (optional)

These tools appear in tools/list by default; set REDMINE_MCP_WRITE_ENABLED=false to remove them:

Tool

Description

createIssue

Creates an issue. Supports core Redmine fields and custom fields via customFieldsJson

updateIssue

Partially updates the specified fields of an existing issue

addIssueNote

Adds a note to the issue journal

attachFileToIssue

Uploads a file from any readable local path and attaches it to the issue

createTimeEntry

Creates a time entry for the user from REDMINE_API_KEY; accepts exactly one of issueId/projectId, hours, date, activity, comment, and custom fields

createWikiPage

Creates a wiki page and rejects the request if the page already exists

updateWikiPage

Fully replaces the wiki page text, requiring the optimistic-lock version returned by getWikiPage

Redmine itself enforces the permissions, workflow, and required-field rules of the REDMINE_API_KEY user. The MCP server introduces no additional model of "own" issues or notes. To make AI-created issues recognizable, the description of an issue created by createIssue is prefixed with AI_EDIT: by default (updateIssue does not add it). Notes, time-entry comments, wiki revision comments, and uploaded file names are not marked by default; each marker is configured separately with a REDMINE_MCP_WRITE_*_PREFIX variable (see Configuration), and an empty value turns it off. Issue descriptions and notes get the prefix on its own line followed by a blank line; single-line fields (time-entry and wiki revision comments) get the prefix and a space; file names get the prefix with no separator. Wiki page markup itself is never changed.

Editing and deleting existing notes is not implemented: the targeted Redmine 4.0.4 does not provide a compatible REST API for it. Editing and deleting time entries; deleting, renaming, and protecting wiki pages; and creating time entries on behalf of another user are outside the current operation set.

Tool

Description

searchAll

Global Redmine search: issues, wiki, news, documents, commits, etc. Parameters: searchQuery, projectId, types, limit, offset

Attachments and Wiki

Tool

Description

getAttachment

Downloads the original attachment file into a local snapshot directory, returns localPath/fileUri, and immediately adds text context to parts[] if the format is supported: txt/log/xml/json/csv, PDF, Word (.docx), Excel (.xlsx), PowerPoint (.pptx), ZIP. A ZIP may yield a separate part per entry. A .docx yields one text part: pandoc markdown when pandoc is available, POI plain text otherwise. Parameters: issueId, attachmentId, maxChars, partLimit (see Processing Limits)

getWikiPage

Content of a project wiki page

listWikiPages

List of all wiki pages of a project

searchWikiPages

Full-text search across wiki pages. Parameters: searchQuery, projectId, limit, offset

Time Entries

Tool

Description

listTimeEntries

Logged time with filters: project, issue, user, period

getMyTimeEntries

Logged time of the current user. Parameters: projectId, issueId, from, to, limit, offset

Reference Data

Tool

Description

listQueries

Saved queries (custom filters) — ID + name. Use the ID with listIssues(queryId) to apply the filter, including custom-field filters

listStatuses

All issue statuses (ID + name) — for filtering in listIssues

listTrackers

All trackers (ID + name) — for filtering in listIssues

listPriorities

All priorities (ID + name) — for filtering in listIssues

listIssueCategories

Issue categories of a project (ID + name)

listTimeEntryActivities

Activity types for interpreting existing time entries (ID + name)

Analytics

Tool

Description

getProjectSummary

Aggregated project summary: overall open/closed count; analyzed open issues broken down by status, tracker, priority, assignee; overdue issues; estimated/spent hours. Analyzes up to 500 open issues and returns a truncation flag. Parameters: projectId, versionId (optional)

getUserWorkload

Workload analysis: open issues by project and priority, overdue issues, top issues. Analyzes up to 500 open issues and returns a truncation flag. Parameters: userId (optional, defaults to current user), projectId (optional)

getVersionChangelog

Version issues grouped by tracker, open/closed statistics. Analyzes up to 500 issues and returns a truncation flag. Parameters: projectId, versionId

getBlockerChain

Recursive traversal of the blocking chain (blocks/blocked_by) upward and downward, limited to depth 10 and 30 loaded issues. Parameters: issueId

getStaleIssues

Open issues not updated for N days, oldest first. Parameters: projectId, daysSinceUpdate (default 30), limit

getReleaseRisks

Release risk assessment: blockers, overdue items, high-priority issues, unassigned issues. Analyzes up to 500 open issues and returns a truncation flag. Parameters: projectId, versionId

compareVersions

Compares two versions: unique issues, shared issues, closure percentage. Analyzes up to 500 issues per version and returns a truncation flag. Parameters: projectId, versionId1, versionId2

With REDMINE_MCP_WRITE_ENABLED=false all tools are read-only and no data in Redmine is modified.

Tool Groups (enable/disable)

Tools are grouped by domain, and each group can be disabled via an environment variable. All groups are enabled by default — the out-of-the-box tool manifest is unchanged. Disabling groups shrinks the MCP tools/list manifest that the client loads into model context at session start. This helps small-context (local) models: disable unneeded groups so only the tools the model actually needs remain.

Variable

Group (tools)

REDMINE_MCP_TOOLS_ISSUE

Issues (core): listIssues, searchIssues, getIssue, getMyIssues, getIssueJournal

REDMINE_MCP_TOOLS_ISSUE_STRUCTURE

Issue structure/history: getIssueTree, getIssueHistory

REDMINE_MCP_TOOLS_PROJECT

Projects: listProjects, getProject, listProjectMembers, listVersions

REDMINE_MCP_TOOLS_SEARCH

Search: searchAll

REDMINE_MCP_TOOLS_ATTACHMENT

Attachments: getAttachment

REDMINE_MCP_TOOLS_WIKI

Wiki: getWikiPage, listWikiPages, searchWikiPages

REDMINE_MCP_TOOLS_TIME_ENTRY

Time entries: listTimeEntries, getMyTimeEntries

REDMINE_MCP_TOOLS_REFERENCE_DATA

Reference data: listQueries, listStatuses, listTrackers, listPriorities, listIssueCategories, listTimeEntryActivities

REDMINE_MCP_TOOLS_USER

User: getCurrentUser

REDMINE_MCP_TOOLS_ISSUE_ANALYTICS

Issue analytics: getBlockerChain, getStaleIssues

REDMINE_MCP_TOOLS_RELEASE_ANALYTICS

Release/project analytics: getProjectSummary, getUserWorkload, getVersionChangelog, getReleaseRisks, compareVersions

Each variable accepts true (default) or false. Example: to keep only issue and project work, disable the remaining groups — REDMINE_MCP_TOOLS_RELEASE_ANALYTICS=false, REDMINE_MCP_TOOLS_WIKI=false, etc. MCP prompts are not affected by these flags; a prompt tells the model to skip a step whose tool is disabled.

MCP Prompts

The server also exports MCP prompts for typical issue-handling scenarios. Each takes one required argument, issueId — the Redmine issue number (12345 or #12345).

Prompt

Description

incident-brief

Quick incident overview: fetches the issue via getIssue, downloads all attachments via getAttachment with short previews, and produces a concise Markdown report

incident-implementation

Implementation context: fetches the issue with focus=implementation, picks relevant attachments by name, description and date, recovers compressed journal data only when it matters, and produces requirements, revision evidence, and a verification checklist

incident-timeline

Incident chronology: uses getIssue(focus=timeline) for issue and changeset context, then reads every getIssueHistory page for journal events and status intervals

issue-remaining-work

What is still unfinished: combines getIssue, getIssueTree (including siblings when relevant), getBlockerChain, and getIssueHistory when needed, and reports open items without trusting the status alone

Clients that build command templates by requesting a prompt with a placeholder argument (for example opencode 1.x, which sends $1) get the template with the placeholder left in place, so their own substitution keeps working.

Tech Stack

  • Java 25, Spring Boot 4.2.0-M2, Spring AI MCP 2.1.0-M1 (stdio transport)

  • Apache PDFBox 3.0.5 — text extraction from PDFs

  • Apache POI 5.4.0 — text extraction from Word, Excel, PowerPoint

  • Apache Tika 3.2.0 (core + parsers-standard) — fallback parser and metadata extraction

  • Pandoc (optional, external binary) — improved DOCX to text/markdown conversion when available on PATH; otherwise the server uses POI

  • Gradle 9.3.1 with version catalog (gradle/libs.versions.toml)

Build

Linux/macOS:

# Point to JDK 25+ if it is not the default JDK:
export JAVA_HOME="$HOME/.jdks/jdk-25.0.2"

./gradlew build

Windows PowerShell:

# Point to JDK 25+ if it is not the default JDK:
$env:JAVA_HOME="C:\Program Files\Java\jdk-25"

.\gradlew.bat build

Result: build/libs/redmine-mcp-server.jar

Configuration

The server needs REDMINE_URL and REDMINE_API_KEY; the remaining variables are optional:

Variable

Description

REDMINE_URL

Base URL of the Redmine instance (e.g. https://redmine.example.com)

REDMINE_API_KEY

Redmine user's API key

REDMINE_MCP_WRITE_ENABLED

Adds the createIssue, updateIssue, addIssueNote, attachFileToIssue, createTimeEntry, createWikiPage, updateWikiPage tools to tools/list; set to false to remove them and run read-only; defaults to true

REDMINE_MCP_WRITE_ISSUE_DESCRIPTION_PREFIX

Marker prepended to the description of issues created by createIssue; defaults to AI_EDIT:. Set to an empty value to disable

REDMINE_MCP_WRITE_ISSUE_NOTE_PREFIX

Marker prepended to notes added by addIssueNote; empty (disabled) by default

REDMINE_MCP_WRITE_TIME_ENTRY_COMMENT_PREFIX

Marker prepended to createTimeEntry comments; counts toward Redmine's 1024-character limit; empty (disabled) by default

REDMINE_MCP_WRITE_WIKI_COMMENT_PREFIX

Marker prepended to wiki revision comments of createWikiPage / updateWikiPage; empty (disabled) by default

REDMINE_MCP_WRITE_ATTACHMENT_FILENAME_PREFIX

Prefix added to file names uploaded by attachFileToIssue (e.g. AI_EDIT__); must not contain / \ ? % * : | " ' < >; empty (disabled) by default

REDMINE_MCP_DATA_DIR

Local data directory of the server; defaults to ~/.redmine-mcp-server

REDMINE_MCP_HTTP_CONNECT_TIMEOUT_SECONDS

Timeout for opening a connection to Redmine; defaults to 10 seconds

REDMINE_MCP_HTTP_READ_TIMEOUT_SECONDS

Timeout for Redmine to answer one request (including the request upload); defaults to 30 seconds. Tool calls are processed one at a time, so a stalled request otherwise delays every later call

REDMINE_MCP_HTTP_SLOW_REQUEST_WARN_MILLIS

Redmine requests slower than this are logged as warnings; defaults to 5000 ms

REDMINE_MCP_ATTACHMENT_PER_PART_CHARS

Text limit per single part (e.g., one file inside a ZIP) for getAttachment calls without limits; defaults to 30000 characters. The tool's partLimit parameter replaces it, and so does maxChars when partLimit is omitted.

REDMINE_MCP_ATTACHMENT_PER_ATTACHMENT_CHARS

Total limit of extracted text per attachment in getAttachment calls without maxChars; defaults to 40000 characters, which keeps a default response below REDMINE_MCP_RESPONSE_MAX_CHARS.

REDMINE_MCP_ATTACHMENT_MAX_REQUEST_CHARS

Ceiling for the maxChars and partLimit a caller passes to getAttachment; defaults to 200000 characters. Larger requests are reduced to it and the response limits.note says so.

REDMINE_MCP_RELATED_MAX_SIBLINGS

Maximum sibling issues added to related when reading an issue; defaults to 20

REDMINE_MCP_RELATED_MAX_CHILDREN

Maximum child issues added to related when reading an issue; defaults to 20

REDMINE_MCP_RELATED_MAX_RELATED

Maximum related issues from relations added to related when reading an issue; defaults to 10

getIssue resolves the related context with one lightweight read of the parent and one batched lookup for siblings, children and relation targets; related issues are not snapshotted. The timeline and changesets focus modes omit related and skip these requests entirely. | REDMINE_MCP_RESPONSE_MAX_CHARS | Target response size limit before stepwise compression of getIssue and getAttachment; defaults to 50000 characters | | REDMINE_MCP_RESPONSE_JOURNAL_TAIL_KEEP | How many most-recent journal entries the budget compression of getIssue keeps before more aggressive reduction; defaults to 30 | | REDMINE_MCP_RESPONSE_ATTACHMENT_TEXT_PART_CHARS | Text limit per attachment part during response compression of getAttachment calls without maxChars/partLimit; defaults to 10000 characters. Calls with explicit limits are never truncated below them. | | REDMINE_MCP_RESPONSE_JOURNAL_NOTE_CHARS | Text limit per journal note during response compression of getIssue; defaults to 5000 characters | | REDMINE_MCP_RESPONSE_IMAGE_PARTS_KEEP | How many image parts the response compression of getAttachment keeps; defaults to 5 | | REDMINE_MCP_PAGINATION_DEFAULT_LIMIT | Default page size for list/search tools; defaults to 25 | | REDMINE_MCP_PAGINATION_DEFAULT_OFFSET | Default offset for list/search tools; defaults to 0 | | REDMINE_MCP_PAGINATION_MEMBERS_DEFAULT_LIMIT | Default page size for listProjectMembers; defaults to 100 | | REDMINE_MCP_TREE_DEFAULT_DEPTH | Default depth for getIssueTree; defaults to 2 | | REDMINE_MCP_TREE_MAX_DEPTH | Maximum depth of getIssueTree; defaults to 5 | | REDMINE_MCP_TREE_MAX_ISSUES | Maximum issues loaded by getIssueTree; defaults to 50 | | REDMINE_MCP_ANALYSIS_MAX_PAGES | Maximum Redmine pages read by analytics tools; defaults to 5 | | REDMINE_MCP_ANALYSIS_PAGE_SIZE | Redmine page size for analytics tools; defaults to 100 | | REDMINE_MCP_ANALYSIS_TOP_ISSUES_LIMIT | Maximum issues in top lists of analytics responses; defaults to 10 | | REDMINE_MCP_ANALYSIS_MAX_BLOCKER_DEPTH | Maximum traversal depth for getBlockerChain; defaults to 10 | | REDMINE_MCP_ANALYSIS_MAX_BLOCKER_ISSUES | Maximum issues loaded by getBlockerChain; defaults to 30 | | REDMINE_MCP_ANALYSIS_STALE_ISSUES_DEFAULT_DAYS_SINCE_UPDATE | Default daysSinceUpdate for getStaleIssues; defaults to 30 | | REDMINE_MCP_ANALYSIS_STALE_ISSUES_DEFAULT_LIMIT | Default result limit for getStaleIssues; defaults to 25 | | REDMINE_MCP_ANALYSIS_STALE_ISSUES_MAX_LIMIT | Maximum result limit for getStaleIssues; defaults to 100 | | REDMINE_MCP_EXTRACTION_PANDOC_ENABLED | Enables the use of Pandoc for DOCX when the binary is found on PATH; defaults to true | | REDMINE_MCP_EXTRACTION_PANDOC_PROBE_TIMEOUT_SECONDS | Timeout for probing Pandoc availability at startup; defaults to 2 seconds | | REDMINE_MCP_EXTRACTION_PANDOC_CONVERSION_TIMEOUT_SECONDS | Timeout for a single DOCX conversion via Pandoc; defaults to 30 seconds | | REDMINE_MCP_EXTRACTION_LIMITS_MAX_DEPTH | Maximum recursion depth for processing nested documents and archives; defaults to 1 | | REDMINE_MCP_EXTRACTION_LIMITS_MAX_TOTAL_PARTS | Maximum text/metadata parts per extraction; defaults to 100 | | REDMINE_MCP_EXTRACTION_LIMITS_MAX_TOTAL_BYTES | Total bytes-read limit per extraction; defaults to 52428800 bytes | | REDMINE_MCP_EXTRACTION_LIMITS_MAX_ENTRY_BYTES | Limit for a single entry inside an archive; defaults to 10485760 bytes | | REDMINE_MCP_EXTRACTION_ZIP_MAX_ENTRIES_PER_ARCHIVE | Maximum entries per ZIP archive; defaults to 100 | | REDMINE_MCP_EXTRACTION_TIKA_BODY_LIMIT_BYTES | Body size limit passed to the Tika fallback parser; defaults to 5242880 bytes | | REDMINE_MCP_EXTRACTION_TIKA_METADATA_MAX_FIELDS | Maximum Tika metadata fields in the response; defaults to 40 |

How to Get REDMINE_URL

Open Redmine in your browser and copy the address-bar value without the path — scheme and domain only.

Examples:

In browser address bar

REDMINE_URL value

https://redmine.example.com/projects/myproject

https://redmine.example.com

http://192.168.1.50:3000/issues/123

http://192.168.1.50:3000

http://10.0.0.5/redmine/projects

http://10.0.0.5/redmine

If Redmine is reachable only by IP address (no domain name), use the IP as-is, including the port if it differs from the standard one (80/443). If Redmine is deployed under a subpath (e.g. /redmine), include it in the URL too.

How to Get REDMINE_API_KEY

  1. Log in to Redmine with your account

  2. Click "My account" (top right corner)

  3. In the right column find the "API access key" block

  4. Click "Show" — your personal API key will be displayed

  5. Copy the key and use it as the REDMINE_API_KEY value

If the "API access key" block is not shown, contact the Redmine administrator — the REST API may be disabled in settings.

Smoke Test

Before connecting an AI client it is worth verifying that the JAR starts correctly with the same environment variables that will later go into the client configuration.

Linux/macOS:

REDMINE_URL=https://redmine.example.com REDMINE_API_KEY=your_key \
  java -jar build/libs/redmine-mcp-server.jar

Windows PowerShell:

$env:REDMINE_URL="https://redmine.example.com"
$env:REDMINE_API_KEY="your_key"
java -jar .\build\libs\redmine-mcp-server.jar

The server runs over stdio and opens no HTTP port: after a successful start it silently waits for MCP requests on stdin/stdout. A successful start shows as the absence of errors in the log and no immediate process exit. Press Ctrl+C to stop.

Docker

The image is published to GHCR with every release:

docker run -i --rm   -e REDMINE_URL=https://redmine.example.com   -e REDMINE_API_KEY=your_key   ghcr.io/igorolv/redmine-mcp-server:latest

The same command is what an MCP client should launch (-i keeps stdin open for the stdio transport). Mount a host directory at /data to keep logs and issue snapshots between runs. To build the image locally: docker build -t redmine-mcp-server .

Logs

Logs are written to ${REDMINE_MCP_DATA_DIR:-~/.redmine-mcp-server}/logs/redmine-mcp-server.log. The file rotates by date and size: 10MB, retention 30 days, total cap 512MB.

Issue Snapshots

When loading an issue the server persists a snapshot to disk under ${REDMINE_MCP_DATA_DIR:-~/.redmine-mcp-server}/issues/<issue-id>/: issue.json, snapshot.json with snapshot metadata, attachments.json, and an extracted/<attachment-id>/ directory for derived files. Attachments are materialized under attachments/ with names like <attachment-id>__<filename> and can be reused across snapshots when the local file already exists and its size matches the Redmine metadata.

Connecting to an AI Client

Add to the client configuration:

{
  "command": "java",
  "args": ["-jar", "<absolute-path>/redmine-mcp-server.jar"],
  "env": {
    "REDMINE_URL": "https://redmine.example.com",
    "REDMINE_API_KEY": "your_api_key"
  }
}

Where exactly:

Client

How to connect

Claude Code

claude mcp add --scope user -e REDMINE_URL=... -e REDMINE_API_KEY=... -- redmine java -jar /path/to/redmine-mcp-server.jar

Qwen Code

~/.qwen/settings.json -> "mcpServers" -> "redmine"

VS Code

.vscode/mcp.json -> "servers" -> "redmine"

Cursor

.cursor/mcp.json -> "mcpServers" -> "redmine"

Claude Desktop

claude_desktop_config.json -> "mcpServers" -> "redmine"

Restart the client afterwards.

Operations and Security

This MCP server is designed to run locally alongside the AI client. It opens no HTTP port and accepts no incoming network connections: the client launches the JAR as a child process and communicates with it via stdin/stdout.

Access Model

  • The server uses the permissions of the Redmine user whose API key is set in REDMINE_API_KEY.

  • Seven explicitly listed write tools for issues, time entries, and wiki are available by default; set REDMINE_MCP_WRITE_ENABLED=false to run fully read-only. The server neither extends the API user's rights nor bypasses the Redmine workflow.

  • Accessible projects, issues, attachments, and time entries are determined by the user's permissions in Redmine. If a user cannot see an object in Redmine, the server must not gain access to it either.

  • The REDMINE_MCP_WRITE_*_PREFIX markers (such as the default AI_EDIT: on created issues) are search labels, not an authorization mechanism: authorship of a change is reliably established by the Redmine account that owns the API key.

  • attachFileToIssue deliberately accepts any readable local path without an allow-list of directories. Since write tools are on by default, run the server only next to a trusted AI client, keeping in mind that the client will be able to pass the contents of any file readable by the process into Redmine.

  • Treat the API key as a secret. Do not commit it to the repository, shell scripts, .vscode/mcp.json, .cursor/mcp.json, or other shared files of the project.

For development and verification of write operations use a separate test Redmine and a separate API key. Because writes are on by default, set REDMINE_MCP_WRITE_ENABLED=false when pointing integrationTest or a manual smoke test at a production installation.

What Data Is Passed to the AI Client

The AI client receives exactly the data it requests through MCP tools:

  • issue cards: subject, description, status, priority, assignee, author, dates, relations, subtasks, journals/comments, custom fields;

  • information about projects, versions, members, reference data, and time entries;

  • wiki pages;

  • attachment metadata;

  • local paths to the original attachment files and text extracted from PDF, DOCX, XLSX, PPTX, ZIP, and text files via getAttachment.

Before connecting an external or cloud AI client, check your company's internal policies: Redmine data may contain trade secrets, personal data, logs, keys, error dumps, and document contents.

Processing Limits

There are protective limits in the code so that a single large document or a related network of issues cannot overload the MCP client:

Area

Limit

Each text part of getAttachment.parts[]

up to 30,000 characters by default, beyond that the text is truncated

One attachment in getAttachment in total

up to 40,000 characters by default

Explicit maxChars / partLimit in getAttachment

honored up to 200,000 characters each

ZIP depth

1 level

ZIP archives

up to 100 entries

ZIP file inside an archive

up to 10 MB

ZIP archive in total

up to 50 MB of extracted data

getIssueTree

depth up to 5, max 50 issues

getIssueHistory

Each JSON page fits REDMINE_MCP_RESPONSE_MAX_CHARS in both characters and UTF-8 bytes; all events remain available through nextOffset

getAttachment reports the limits it applied in limits (maxChars, partLimit, and a note when a requested value was reduced to the ceiling); a cut part carries totalChars with its full length. Without explicit limits, a response that still exceeds REDMINE_MCP_RESPONSE_MAX_CHARS (for example, many ZIP entries) is compressed: extra image parts are collapsed, then text parts are cut to REDMINE_MCP_RESPONSE_ATTACHMENT_TEXT_PART_CHARS. With explicit limits, only image parts are collapsed. The original file remains on disk at localPath; for pandoc DOCX extraction, the markdown part also points to its saved text file. Other document parts can point to a PDF or Office source file rather than a separate extracted-text file.

getIssue supports the focus parameter. default keeps the usual response shape and applies compression only when the response budget is exceeded. implementation targets implementation work on the issue: the full issue is still persisted to disk, while the tool response keeps the description, human notes, attachment metadata, and all changeset revisions; verbose history and commit message bodies are omitted. timeline targets "who did what and when" questions: it keeps journals and changesets but omits attachments, custom fields, and related context. full is an explicit choice of the full form with protective budget compression.

getIssueTree still loads and snapshots every fetched issue in full, but returns only compact Issue context for root and ancestors; their description, journals, custom fields, attachments, and changesets are omitted from this view. Its subtree remains the hierarchy view. This changes the contents of those existing Issue fields: clients that previously read full details from the tree should call getIssue(id) instead. getIssueTree does not include direct relations.

getIssueHistory includes the creation event and each journal event, including journals without a note or a recognized field change. It shortens long notes and old/new field values when needed, keeps journalId on each update, and explains reductions in compressionNotes. For exact wording or a complete old/new value, call getIssueJournal(issueId, journalId). Start with getIssueHistory(issueId); when nextOffset is present, pass that number as offset in the next call. Continue until nextOffset is absent. totalEvents includes creation. Status intervals in statusDurations belong to events on that page; combine them across pages. Compare sourceUpdatedOn across pages and restart if it changes. The server uses the existing REDMINE_MCP_RESPONSE_MAX_CHARS setting; no new environment variable is needed. If one event cannot fit after text shortening, its page keeps the event and journalId but reduces the event to metadata; compressionNotes identify any omitted status intervals and point to getIssueJournal for the full entry.

If the note you need was dropped from the getIssue response by budget compression or the note was shortened, call getIssueJournal(issueId, journalId): it re-takes the issue snapshot and returns the selected journal entry without response compression.

Some regular list tools (listIssues, listProjects, listTimeEntries, listQueries) accept limit and offset directly. For reliable operation avoid requesting excessively large pages; a practical range is 25-100 items per call.

Diagnostics

Environment check:

java -version
echo "$REDMINE_URL"
test -n "$REDMINE_API_KEY" && echo "REDMINE_API_KEY is set"

Redmine REST API access check:

curl -H "X-Redmine-API-Key: <key>" <url>/users/current.json

Build check:

./gradlew test
./gradlew build

Integration tests against a live Redmine:

REDMINE_URL=<url> REDMINE_API_KEY=<key> ./gradlew integrationTest

Integration tests require a reachable Redmine and real test data. Unit tests exclude tests tagged integration by default.

Known Operational Limitations

  • HTTP timeouts and the retry policy are currently not configurable separately. If Redmine is slow to respond, an MCP call may wait longer than is convenient for the AI client.

  • Redmine errors (401, 403, 404, 5xx) are currently handled mostly at the Spring RestClient level; the message seen by the AI-client user may be less friendly than a dedicated MCP tool error.

  • A note or attachment may be written successfully, but its new journalId/attachmentId may stay undefined if Redmine or a concurrent user modifies the issue between confirmation reads. The operation itself is still considered completed.

  • Search depends on Redmine settings. If /search.json is disabled by the administrator, searchAll, searchIssues, and searchWikiPages may not return the expected results.

  • Text extraction from PDF works only for PDFs with a text layer. Scanned documents without OCR are detected as PDFs with no extractable text.

  • Images are not re-encoded. getAttachment returns the path to the original file; text parts[] for images remain empty.

Project Structure

├── src/main/java/ru/it_spectrum/ai/redmine/mcp/
│   ├── RedmineMcpServerApplication.java   — Spring Boot entry point
│   ├── api/                                — stable MCP wire format: records returned by tools/services
│   │   ├── Issue.java
│   │   ├── AttachmentContent.java
│   │   ├── Project.java
│   │   ├── IssueMutationResult.java        — stable result of issue write operations
│   │   ├── TimeEntryMutationResult.java    — stable result of time-entry creation
│   │   ├── WikiMutationResult.java         — stable result of wiki-page writes
│   │   └── ...                             — tool response DTOs and analytics DTOs
│   ├── client/
│   │   ├── RedmineClient.java              — read-only wrapper over the Redmine REST API
│   │   ├── RedmineMutationClient.java      — optional POST/PUT for issues, time entries, and wiki
│   │   └── model/                          — raw Redmine REST API DTOs, never exported directly to MCP
│   │       ├── RedmineIssue.java
│   │       ├── RedmineAttachment.java
│   │       ├── RedmineProject.java
│   │       └── ...
│   ├── config/
│   │   ├── RedmineClientProperties.java   — url + apiKey from env
│   │   ├── RedmineMcpProperties.java      — all redmine-mcp.* runtime settings
│   │   ├── RedmineConfig.java             — RestClient
│   │   ├── McpServerConfig.java           — stdio MCP customizer with immediateExecution(true)
│   │   └── JsonConfig.java                — ObjectMapper for MCP JSON
│   ├── extraction/
│   │   ├── ExtractionPipeline.java        — document-to-text pipeline
│   │   ├── DocumentParser.java            — parser interface
│   │   ├── FileTypeDetector.java          — file type detection
│   │   ├── PandocAvailability.java        — external pandoc probe at startup
│   │   └── parser/
│   │       ├── PlainTextParser.java       — txt/log/csv/json/xml
│   │       ├── PdfTextParser.java         — PDF via PDFBox
│   │       ├── DocxTextParser.java        — DOCX via POI
│   │       ├── DocxPandocParser.java      — DOCX via Pandoc when available
│   │       ├── XlsxTextParser.java        — XLSX via POI
│   │       ├── PptxTextParser.java        — PPTX via POI
│   │       ├── ZipParser.java             — ZIP with bounded recursion
│   │       ├── ImagePassthroughParser.java
│   │       ├── TikaTextFallbackParser.java
│   │       ├── TikaMetadataParser.java
│   │       └── BinaryFallbackParser.java
│   ├── service/
│   │   ├── IssueService.java              — issue business logic and mapping client.model -> api
│   │   ├── IssueMutationService.java      — optional issue writing and AI marking
│   │   ├── TimeEntryMutationService.java  — optional time-entry creation
│   │   ├── WikiMutationService.java       — safe wiki writing with optimistic locking
│   │   ├── AttachmentService.java         — attachment snapshot, download, and extraction
│   │   ├── IssueSnapshotService.java      — local issue and attachment snapshots
│   │   ├── AnalysisService.java           — analytics, risks, blocker chain
│   │   └── ...                            — services for projects, wiki, search, reference data, time entries
│   └── tools/
│       ├── AttachmentTools.java           — 1 MCP tool for files and attachment context
│       ├── IncidentPrompts.java           — 4 MCP prompts for issue investigation
│       ├── IssueAnalyticsTools.java       — 2 issue-analytics MCP tools (blocker chain, stale)
│       ├── IssueStructureTools.java       — 2 MCP tools: issue tree and change history
│       ├── IssueTools.java                — 5 core issue MCP tools
│       ├── IssueWriteTools.java           — 4 optional issue-write MCP tools
│       ├── ProjectTools.java              — 4 project MCP tools
│       ├── ReferenceDataTools.java        — 6 reference-data MCP tools
│       ├── ReleaseAnalyticsTools.java     — 5 release/project analytics MCP tools
│       ├── SearchTools.java               — 1 global-search MCP tool
│       ├── TimeEntryTools.java            — 2 time-entry MCP tools
│       ├── TimeEntryWriteTools.java       — 1 optional time-entry creation MCP tool
│       ├── UserTools.java                 — 1 current-user MCP tool
│       ├── WikiTools.java                 — 3 wiki MCP tools
│       └── WikiWriteTools.java            — 2 optional wiki-write MCP tools
└── src/main/resources/
    ├── application.yml                    — MCP server configuration (stdio)
    └── logback-spring.xml                 — logging configuration

Troubleshooting

  • "Gradle requires JVM 17 or later" — point JAVA_HOME at JDK 25+

  • Connection refused / 401 — check REDMINE_URL and REDMINE_API_KEY. Test: curl -H "X-Redmine-API-Key: <key>" <url>/users/current.json

  • No search results — verify that /search.json is available in Redmine (it may be disabled by the administrator)

Available Tools

39 tools
addIssueNoteaddIssueNoteA

Append a new journal note to one existing Redmine issue without changing its fields. This is non-idempotent: retrying can add a duplicate note, and existing journal entries cannot be edited.

Inputs: notes (required), issueId (required). Returns: issueId, journalId, attachmentId

attachFileToIssueattachFileToIssueA

Upload a readable server-local file and attach it to one existing Redmine issue. This is non-idempotent and retries may create duplicate attachments; getAttachment performs the reverse read/download flow.

Inputs: issueId (required), localPath (required), description. Returns: issueId, journalId, attachmentId

compareVersionscompareVersionsA
Read-onlyIdempotent

Compare the issue scope and completion of two known versions/milestones in one project. Returns issues unique to each, shared issues and closure percentages; use listVersions to discover IDs.

Inputs: projectId (required), versionId1 (required), versionId2 (required). Returns: Side-by-side comparison of two Redmine versions/milestones: per-version complet…

createIssuecreateIssueA

Create a new Redmine issue in a known project with core or custom fields. This writes as the API-key user and is not idempotent; use updateIssue when the issue already exists.

Inputs: subject (required), projectId (required), dueDate, statusId, +12 more. Returns: issueId, journalId, attachmentId

createTimeEntrycreateTimeEntryA

Record logged hours for the API-key user against exactly one issue or project. This is non-idempotent and retries can duplicate time; use listTimeEntryActivities when an activity ID is needed.

Inputs: hours (required), issueId, spentOn, comments, +3 more. Returns: Result of creating a Redmine time entry.

createWikiPagecreateWikiPageA

Create a new Redmine wiki page with its complete initial text and optional parent. This writes as the API-key user and fails if the title already exists; use updateWikiPage for an existing page.

Inputs: text (required), pageTitle (required), projectId (required), comments, +1 more. Returns: Result of creating or updating a Redmine wiki page.

getAttachmentgetAttachmentA
Read-onlyIdempotent

Retrieve and inspect one known issue attachment by downloading it to the server's local snapshot and extracting text from supported documents or archives. Use getIssue to discover attachment IDs; images and unsupported binaries return metadata and a local path without extracted text. Text cut by the limits stays readable at each part's localPath.

Inputs: issueId (required), attachmentId (required), maxChars, partLimit. Returns: Materialised attachment: the original file has been downloaded to local storage…

getBlockerChaingetBlockerChainA
Read-onlyIdempotent

Trace only blocks/blocked_by relations recursively in both directions, returning the full upstream and downstream blocking dependency chains. Use getIssueTree for parent/subtask hierarchy and other direct relation types.

Inputs: issueId (required). Returns: Blocking-dependency chain centred on an issue. `blockedBy` is the upstream chai…

getCurrentUsergetCurrentUserA
Read-onlyIdempotent

Retrieve the identity and user ID of the currently authenticated API-key user. Use the ID in assignee/user filters; getMyIssues, getMyTimeEntries and the default getUserWorkload do not require it.

Inputs: no named parameters. Returns: Redmine user, trimmed to fields relevant for LLM context (no API keys, group me…

getIssuegetIssueA
Read-onlyIdempotent

Retrieve complete context for one known issue ID: core and custom fields, subtasks, direct relations, journals, attachments and linked changesets, with focus modes controlling compression. Use getIssueTree for recursive structure, getIssueJournal for a journal omitted or shortened by compression, or getAttachment for file content.

Inputs: issueId (required), focus. Returns: Full Redmine issue with description, relations, history notes, child tasks and…

getIssueHistorygetIssueHistoryA
Read-onlyIdempotent

Read an issue's chronological journal events and status intervals. Long text is shortened; use journalId with getIssueJournal for full text, and nextOffset to read any remaining events.

Inputs: issueId (required), offset. Returns: Interpreted issue history. Read pages until nextOffset is absent to cover every…

getIssueJournalgetIssueJournalA
Read-onlyIdempotent

Retrieve one known issue journal entry in full, without response compression. Use a journal ID from getIssue or getIssueHistory when exact text is needed.

Inputs: issueId (required), journalId (required). Returns: Single history entry: a user comment, a set of field changes, or both.

getIssueTreegetIssueTreeA
Read-onlyIdempotent

Explore one issue's parent chain and subtasks down to the requested depth. Root and ancestors are compact; use getIssue for full details or relations and getBlockerChain for blockers.

Inputs: issueId (required), depth. Returns: Hierarchical view around a target issue: the issue itself, its ancestor chain u…

getMyIssuesgetMyIssuesA
Read-onlyIdempotent

Browse issues assigned to the currently authenticated API-key user without first resolving their user ID. Use getUserWorkload for aggregated workload metrics or listIssues for another assignee.

Inputs: sort, limit, offset, statusId, +1 more. Returns: Issues assigned to the currently authenticated Redmine user, together with that…

getMyTimeEntriesgetMyTimeEntriesA
Read-onlyIdempotent

Browse actual time-entry records logged by the currently authenticated API-key user without first resolving their user ID. Use listTimeEntries for another user or broader administrative filtering.

Inputs: to, from, limit, offset, +2 more. Returns: Time entries logged by the currently authenticated Redmine user, together with…

getProjectgetProjectA
Read-onlyIdempotent

Inspect one known project's configuration and metadata, including description, trackers and enabled modules. Use getProjectSummary for aggregated issue metrics, listProjectMembers for people or listVersions for milestones.

Inputs: projectId (required). Returns: Redmine project. Numeric `status` field and audit timestamps are omitted — they…

getProjectSummarygetProjectSummaryA
Read-onlyIdempotent

Summarize one project's issue health, optionally scoped to a milestone: complete open/closed totals plus status, tracker, priority and assignee distributions, overdue work and estimated versus spent hours for the analyzed open-issue set. Use listIssues when issue records are needed instead of aggregates.

Inputs: projectId (required), versionId. Returns: Aggregated snapshot of a Redmine project (optionally scoped to a version): issu…

getReleaseRisksgetReleaseRisksA
Read-onlyIdempotent

Assess readiness risks for one known version/milestone: open blockers, overdue work, high-priority unresolved issues and unassigned tasks, with a risk score. Use getVersionChangelog for the milestone issue breakdown rather than risk triage.

Inputs: projectId (required), versionId (required). Returns: Risk assessment for a Redmine version/milestone: open issues classified into bl…

getStaleIssuesgetStaleIssuesA
Read-onlyIdempotent

Identify neglected open issues in one project by last-update age, ordered most stale first. Use listIssues for general field or status filters; this tool is for inactivity triage.

Inputs: projectId (required), limit, daysSinceUpdate. Returns: Open issues that have not been updated for at least `daysSinceUpdate` days, sor…

getUserWorkloadgetUserWorkloadA
Read-onlyIdempotent

Analyze one user's open-issue workload by project and priority, including overdue count, estimated versus spent hours and top issues; omitting userId selects the API-key user. This returns aggregates, not issue records; use getMyIssues for the current user or listIssues for a specified user.

Inputs: userId, projectId. Returns: Workload analysis for a single user: open issue counts grouped by project and p…

getVersionChangeloggetVersionChangelogA
Read-onlyIdempotent

Summarize the issue scope of one known version/milestone as open and closed counts with issues grouped by tracker. Use getReleaseRisks for readiness risks or listVersions to discover the version ID.

Inputs: projectId (required), versionId (required). Returns: Changelog for a Redmine version/milestone: all issues grouped by tracker, with…

getWikiPagegetWikiPageA
Read-onlyIdempotent

Read the complete markup content and current version of one known project wiki page. Use listWikiPages or searchWikiPages to discover its title; the returned version is required by updateWikiPage.

Inputs: pageTitle (required), projectId (required). Returns: Redmine wiki page. When returned from the index listing only metadata fields ar…

listIssueCategorieslistIssueCategoriesA
Read-onlyIdempotent

Discover issue category IDs and names configured for one known project. Reuse the IDs as categoryId in createIssue or updateIssue.

Inputs: projectId (required). Returns: List of Redmine entity references (id+name pairs). Wraps a JSON array so the MC…

listIssueslistIssuesA
Read-onlyIdempotent

Browse issue summaries with structured Redmine filters, saved queries, custom-field filters, sorting and pagination. Use searchIssues when only free text is known, or getIssue for one known issue's complete context.

Inputs: sort, limit, offset, queryId, +7 more. Returns: Paginated slice of issue summaries. Use `offset` + `limit` to walk the full res…

listPrioritieslistPrioritiesA
Read-onlyIdempotent

Discover valid issue priority IDs and names before filtering, creating or updating issues. Reuse the IDs as priorityId in listIssues, createIssue or updateIssue.

Inputs: no named parameters. Returns: List of Redmine entity references (id+name pairs). Wraps a JSON array so the MC…

listProjectMemberslistProjectMembersA
Read-onlyIdempotent

Discover the users and groups that belong to one project, their IDs and assigned roles. Use when choosing or interpreting assignees; getUserWorkload analyzes a user's issues rather than membership.

Inputs: projectId (required), limit, offset. Returns: Paginated slice of project memberships.

listProjectslistProjectsA
Read-onlyIdempotent

Discover accessible Redmine projects and their valid identifiers before project-scoped operations when the target project is unknown. Returns project summaries; use getProject for one project's details.

Inputs: limit, offset. Returns: Paginated slice of projects.

listQuerieslistQueriesA
Read-onlyIdempotent

Discover saved Redmine issue queries (stored filters), especially filters involving custom fields. Returns query IDs and names rather than issue results; pass a selected queryId to listIssues.

Inputs: limit, offset. Returns: Paginated slice of saved queries.

listStatuseslistStatusesA
Read-onlyIdempotent

Discover valid Redmine issue status IDs and names for structured issue filtering or mutation. Reuse the IDs as statusId in listIssues, createIssue or updateIssue.

Inputs: no named parameters. Returns: List of Redmine entity references (id+name pairs). Wraps a JSON array so the MC…

listTimeEntrieslistTimeEntriesA
Read-onlyIdempotent

Browse actual Redmine time-entry records using project, issue, user and date-range filters. Use getMyTimeEntries for the API-key user without looking up an ID; getUserWorkload returns aggregates instead.

Inputs: to, from, limit, offset, +3 more. Returns: Paginated slice of time entries.

listTimeEntryActivitieslistTimeEntryActivitiesA
Read-onlyIdempotent

Discover valid time-entry activity IDs and names for interpreting logged hours or creating a time entry. Reuse an ID as activityId in createTimeEntry when the default activity is unsuitable.

Inputs: no named parameters. Returns: List of Redmine entity references (id+name pairs). Wraps a JSON array so the MC…

listTrackerslistTrackersA
Read-onlyIdempotent

Discover valid tracker (issue type) IDs and names before filtering, creating or updating issues. Reuse the IDs as trackerId in listIssues, createIssue or updateIssue.

Inputs: no named parameters. Returns: List of Redmine entity references (id+name pairs). Wraps a JSON array so the MC…

listVersionslistVersionsA
Read-onlyIdempotent

Discover versions/milestones of one project and the IDs used by issue filters and release analytics. Returns milestone metadata, not issue scope or risk; use getVersionChangelog or getReleaseRisks for those.

Inputs: projectId (required). Returns: List of Redmine project versions / milestones. Wraps a JSON array so the MCP ou…

listWikiPageslistWikiPagesA
Read-onlyIdempotent

Discover wiki page titles in one known project without loading every page body. Use getWikiPage to read a selected title or searchWikiPages when only content terms are known.

Inputs: projectId (required). Returns: List of wiki pages in a Redmine project. Wraps a JSON array so the MCP outputSc…

searchAllsearchAllA
Read-onlyIdempotent

Search by free text across mixed Redmine content such as issues, wiki pages, news, documents, changesets, messages and projects. Use searchIssues for richer issue-only results or searchWikiPages for wiki-only discovery.

Inputs: searchQuery (required), limit, types, offset, +1 more. Returns: Paginated slice of Redmine full-text search hits. Hits may be issues, wiki page…

searchIssuessearchIssuesA
Read-onlyIdempotent

Find issue summaries by full-text query, optionally within one project. Use listIssues for exact field, saved-query or custom-field filtering, then getIssue to inspect a selected result.

Inputs: searchQuery (required), limit, offset, projectId. Returns: Paginated slice of issue summaries. Use `offset` + `limit` to walk the full res…

searchWikiPagessearchWikiPagesA
Read-onlyIdempotent

Find project wiki pages by full-text content query, optionally across all accessible projects. Use getWikiPage to read a selected result or searchAll when non-wiki content should also match.

Inputs: searchQuery (required), limit, offset, projectId. Returns: Paginated slice of Redmine full-text search hits. Hits may be issues, wiki page…

updateIssueupdateIssueA
DestructiveIdempotent

Modify only the supplied fields of one existing Redmine issue; omitted fields remain unchanged. Use addIssueNote for a comment-only change; this tool does not edit existing journal entries.

Inputs: issueId (required), dueDate, subject, statusId, +13 more. Returns: issueId, journalId, attachmentId

updateWikiPageupdateWikiPageA
DestructiveIdempotent

Replace the complete text of one existing Redmine wiki page; this is not a patch or append operation. Pass the current version from getWikiPage for optimistic locking, and use createWikiPage if absent.

Inputs: text (required), version (required), pageTitle (required), projectId (required), +1 more. Returns: Result of creating or updating a Redmine wiki page.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 39 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, and descriptions explicitly cross-reference alternatives (e.g., listIssues vs searchIssues vs getMyIssues, getIssue vs getIssueHistory). The surface is large but boundaries are clearly documented, leaving little true ambiguity.

    Naming Consistency5/5

    Consistent camelCase verb_noun pattern throughout (listIssues, getIssue, createWikiPage, searchAll). Minor 'My' variants (getMyIssues, getMyTimeEntries) remain predictable and readable.

    Tool Count2/5

    39 tools is excessive for a single MCP server; many list* metadata tools and specialized read tools could be consolidated or dynamically discovered, increasing selection burden.

    Completeness3/5

    Issue tracking and analytics are well covered, but notable gaps exist: no delete operations for issues, wiki pages, or time entries; no update/delete for time entries; no create/update for projects or versions.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers