igorolv/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.
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:
Architecture
The server supports only the stdio transport.
Stdio
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_ =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