redmine-mcp-server
This Redmine MCP server lets AI agents read and explore Redmine issues, projects, time entries, wiki pages, attachments, and reference data via stdio, with optional write tools (not shown in the provided schema) for issues, time entries, and wiki.
Identify the current API-key user and use it for “my issues” and “my time entries”.
Browse, filter, search, and retrieve full issue context, including history, journals, tree structure, blocker chains, and stale issues.
Access project metadata: projects, members, versions, issue categories, trackers, statuses, priorities, and saved queries.
Read and search wiki pages; retrieve page content, list pages, and inspect revision metadata.
Download attachments to a local snapshot and extract text from supported formats like PDF, DOCX, XLSX, PPTX, ZIP, and plain text.
Query time entries with project, issue, user, and date-range filters, plus time-entry activities.
Run analytics: project summaries, version changelogs, release risks, user workload, version comparisons, and more.
Perform global full-text search across issues, wiki pages, news, documents, changesets, messages, and projects.
If write tools are enabled, create/update issues, add notes, attach files, create time entries, and create/update wiki pages (not present in the provided read-only schema).
Provides tools for interacting with Redmine, allowing AI agents to work with issues, projects, members, versions, wiki pages, attachments, time entries, and reference data. Includes search and analytics tools and is read-only by default, with optional issue and time entry write operations.
Redmine MCP Server
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.
Install JDK 25+.
Download
redmine-mcp-server.jarfrom the latest release, or build it yourself:./gradlew bootJar(see Build). A Docker image is published as well.Obtain
REDMINE_URLandREDMINE_API_KEY(see Configuration).Verify that the JAR starts (see Smoke Test).
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.jarRelated 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 |
| Current user: ID, login, groups, projects. Useful for "my issues" filtering |
Projects
Tool | Description |
| List of all accessible projects |
| Project details: trackers, modules, description |
| Project members with roles |
| Project versions (milestones) |
Issues
Tool | Description |
| Issue list with filters: project, status, tracker, assignee, priority, version, saved query, custom fields ( |
| Full-text issue search with detailed results |
| Issue details: description, status, assignee, dates, notes, relations, custom fields, attachments, linked revisions ( |
| A single complete issue journal note/event without response compression. Parameters: |
| Issues of the current user. Parameters: |
| Parent chain and subtasks. |
| Creation and every journal event, with status intervals. Long text is shortened; |
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 |
| Creates an issue. Supports core Redmine fields and custom fields via |
| Partially updates the specified fields of an existing issue |
| Adds a note to the issue journal |
| Uploads a file from any readable local path and attaches it to the issue |
| Creates a time entry for the user from |
| Creates a wiki page and rejects the request if the page already exists |
| Fully replaces the wiki page text, requiring the optimistic-lock version returned by |
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.
Search
Tool | Description |
| Global Redmine search: issues, wiki, news, documents, commits, etc. Parameters: |
Attachments and Wiki
Tool | Description |
| Downloads the original attachment file into a local snapshot directory, returns |
| Content of a project wiki page |
| List of all wiki pages of a project |
| Full-text search across wiki pages. Parameters: |
Time Entries
Tool | Description |
| Logged time with filters: project, issue, user, period |
| Logged time of the current user. Parameters: |
Reference Data
Tool | Description |
| Saved queries (custom filters) — ID + name. Use the ID with |
| All issue statuses (ID + name) — for filtering in |
| All trackers (ID + name) — for filtering in |
| All priorities (ID + name) — for filtering in |
| Issue categories of a project (ID + name) |
| Activity types for interpreting existing time entries (ID + name) |
Analytics
Tool | Description |
| 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: |
| Workload analysis: open issues by project and priority, overdue issues, top issues. Analyzes up to 500 open issues and returns a truncation flag. Parameters: |
| Version issues grouped by tracker, open/closed statistics. Analyzes up to 500 issues and returns a truncation flag. Parameters: |
| Recursive traversal of the blocking chain (blocks/blocked_by) upward and downward, limited to depth 10 and 30 loaded issues. Parameters: |
| Open issues not updated for N days, oldest first. Parameters: |
| Release risk assessment: blockers, overdue items, high-priority issues, unassigned issues. Analyzes up to 500 open issues and returns a truncation flag. Parameters: |
| Compares two versions: unique issues, shared issues, closure percentage. Analyzes up to 500 issues per version and returns a truncation flag. Parameters: |
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) |
| Issues (core): |
| Issue structure/history: |
| Projects: |
| Search: |
| Attachments: |
| Wiki: |
| Time entries: |
| Reference data: |
| User: |
| Issue analytics: |
| Release/project analytics: |
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 |
| Quick incident overview: fetches the issue via |
| Implementation context: fetches the issue with |
| Incident chronology: uses |
| What is still unfinished: combines |
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 POIGradle 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 buildWindows PowerShell:
# Point to JDK 25+ if it is not the default JDK:
$env:JAVA_HOME="C:\Program Files\Java\jdk-25"
.\gradlew.bat buildResult: build/libs/redmine-mcp-server.jar
Configuration
The server needs REDMINE_URL and REDMINE_API_KEY; the remaining variables are optional:
Variable | Description |
| Base URL of the Redmine instance (e.g. |
| Redmine user's API key |
| Adds the |
| Marker prepended to the description of issues created by |
| Marker prepended to notes added by |
| Marker prepended to |
| Marker prepended to wiki revision comments of |
| Prefix added to file names uploaded by |
| Local data directory of the server; defaults to |
| Timeout for opening a connection to Redmine; defaults to |
| Timeout for Redmine to answer one request (including the request upload); defaults to |
| Redmine requests slower than this are logged as warnings; defaults to |
| Text limit per single |
| Total limit of extracted text per attachment in |
| Ceiling for the |
| Maximum sibling issues added to |
| Maximum child issues added to |
| Maximum related issues from relations added to |
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 |
|
|
|
|
|
|
|
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
Log in to Redmine with your account
Click "My account" (top right corner)
In the right column find the "API access key" block
Click "Show" — your personal API key will be displayed
Copy the key and use it as the
REDMINE_API_KEYvalue
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.jarWindows PowerShell:
$env:REDMINE_URL="https://redmine.example.com"
$env:REDMINE_API_KEY="your_key"
java -jar .\build\libs\redmine-mcp-server.jarThe 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:latestThe 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 |
|
Qwen Code |
|
VS Code |
|
Cursor |
|
Claude Desktop |
|
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=falseto 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_*_PREFIXmarkers (such as the defaultAI_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.attachFileToIssuedeliberately 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 | up to 30,000 characters by default, beyond that the text is truncated |
One attachment in | up to 40,000 characters by default |
Explicit | 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 |
| depth up to 5, max 50 issues |
| Each JSON page fits |
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.jsonBuild check:
./gradlew test
./gradlew buildIntegration tests against a live Redmine:
REDMINE_URL=<url> REDMINE_API_KEY=<key> ./gradlew integrationTestIntegration 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 SpringRestClientlevel; 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/attachmentIdmay 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.jsonis disabled by the administrator,searchAll,searchIssues, andsearchWikiPagesmay 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.
getAttachmentreturns the path to the original file; textparts[]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 configurationTroubleshooting
"Gradle requires JVM 17 or later" — point
JAVA_HOMEat JDK 25+Connection refused / 401 — check
REDMINE_URLandREDMINE_API_KEY. Test:curl -H "X-Redmine-API-Key: <key>" <url>/users/current.jsonNo search results — verify that
/search.jsonis available in Redmine (it may be disabled by the administrator)
Available Tools
39 toolsaddIssueNoteaddIssueNoteA
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
compareVersionscompareVersionsARead-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.
getAttachmentgetAttachmentARead-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…
getBlockerChaingetBlockerChainARead-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…
getCurrentUsergetCurrentUserARead-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…
getIssuegetIssueARead-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…
getIssueHistorygetIssueHistoryARead-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…
getIssueJournalgetIssueJournalARead-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.
getIssueTreegetIssueTreeARead-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…
getMyIssuesgetMyIssuesARead-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…
getMyTimeEntriesgetMyTimeEntriesARead-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…
getProjectgetProjectARead-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…
getProjectSummarygetProjectSummaryARead-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…
getReleaseRisksgetReleaseRisksARead-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…
getStaleIssuesgetStaleIssuesARead-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…
getUserWorkloadgetUserWorkloadARead-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…
getVersionChangeloggetVersionChangelogARead-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…
getWikiPagegetWikiPageARead-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…
listIssueCategorieslistIssueCategoriesARead-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…
listIssueslistIssuesARead-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…
listPrioritieslistPrioritiesARead-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…
listProjectMemberslistProjectMembersARead-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.
listProjectslistProjectsARead-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.
listQuerieslistQueriesARead-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.
listStatuseslistStatusesARead-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…
listTimeEntrieslistTimeEntriesARead-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.
listTimeEntryActivitieslistTimeEntryActivitiesARead-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…
listTrackerslistTrackersARead-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…
listVersionslistVersionsARead-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…
listWikiPageslistWikiPagesARead-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…
searchAllsearchAllARead-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…
searchIssuessearchIssuesARead-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…
searchWikiPagessearchWikiPagesARead-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…
updateIssueupdateIssueADestructiveIdempotent
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
updateWikiPageupdateWikiPageADestructiveIdempotent
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
Scored across 39 tools
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.
Consistent camelCase verb_noun pattern throughout (listIssues, getIssue, createWikiPage, searchAll). Minor 'My' variants (getMyIssues, getMyTimeEntries) remain predictable and readable.
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.
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
Related MCP Connectors
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseCqualityDmaintenanceModel Context Protocol (MCP) server for Redmine that provides comprehensive access to the Redmine REST API, enabling users to operate Redmine from MCP clients such as Claude Desktop.9014 npmMIT
- AlicenseAqualityDmaintenanceEnables AI assistants to manage Redmine issues, projects, time tracking, wiki, and files via the MCP protocol.3362 npm6Apache 2.0
- AlicenseAqualityCmaintenanceMCP server for Redmine integration, enabling AI assistants to manage issues, upload files, automate workflows, and handle wiki pages.18MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI clients (Cursor, Claude Desktop) to manage Redmine issues, projects, time tracking, and wiki pages through natural language.13 npm1ISC