Redmine MCP Server
Provides tools for managing Redmine issues, projects, time entries, and search, enabling AI agents to interact with a Redmine instance via the REST API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Redmine MCP Server Show me all open issues in project Alpha"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π¦ Agama β Redmine MCP Server
MCP server for Redmine. Enables AI agents to work with issues using simple natural language commands.
Works just as well as a personal tool for a single developer β or deployed once and shared by the whole team.
ββββββββββββ MCP (stdio) βββββββββββββββββββββββ REST/JSON ββββββββββββ
β Agent β βββββββββββββββΆ β Redmine MCP Server β βββββββββββββΆ β Redmine β
β (client) β βββββββββββββββ β (this project) β βββββββββββββ β server β
ββββββββββββ tool results βββββββββββββββββββββββ HTTP ββββββββββββπ¬ Just ask
"What issues are assigned to me? Sort them by priority."
"Create a bug in the Web project: login button doesn't respond on mobile, mark it urgent."
"Summarize issue #456 and all its subtasks."
"How many hours did I log this week, broken down by project?"
Related MCP server: Redmine MCP Server
Requirements
Node.js 22+
A Redmine instance with the REST API enabled (Administration β Settings β API)
A Redmine API key β go to My account β API access key while signed in
Quick start
Most MCP clients (e.g. Claude Desktop) launch the server for you β configure it once and forget it:
{
"mcpServers": {
"redmine": {
"command": "npx",
"args": ["-y", "@0xkillaflow/agama-redmine-mcp"],
"env": {
"REDMINE_URL": "https://redmine.example.com",
"REDMINE_API_KEY": "your-redmine-api-key"
}
}
}
}For Claude Desktop, this goes in claude_desktop_config.json (Settings β Developer β Edit
Config). Restart the client and the Redmine tools will appear in its tool list.
To run it standalone from a shell instead:
REDMINE_URL=https://redmine.example.com REDMINE_API_KEY=your-redmine-api-key \
npx -y @0xkillaflow/agama-redmine-mcpThe server speaks MCP over stdio and logs to stderr, so stdout stays clean for the protocol.
Configuration
Set via environment variables, validated at startup. See .env.example for a
template.
Variable | Required | Default | Purpose |
| yes | β | Base URL of the Redmine instance |
| yes | β | API key for the acting user |
| no |
| Per-request timeout in milliseconds |
| no | empty | Directories the attachment tools may use |
| no |
|
|
| no |
|
|
File access (REDMINE_ALLOWED_DIRECTORIES)
The attachment tools are the only ones that touch your filesystem, and they may
only touch it inside this allowlist β a :-separated list of absolute directories
(; on Windows). It governs both directions: reads for
redmine_upload_attachment and writes for redmine_download_attachment.
REDMINE_ALLOWED_DIRECTORIES=/Users/you/redmine-files:/tmp/redmine-downloadsIt defaults to empty, which means no local file access at all β both tools
refuse every path until you opt in. That default is deliberate: an agent that can
be talked into uploading a file is an agent that can be talked into uploading
~/.ssh/id_rsa or the .env holding your API key. Allowlist the narrowest
directory that does the job. Paths are fully resolved (.. segments and symlinks
included) before the check, so a symlink inside an allowed directory cannot point
out of it, and downloads never overwrite an existing file.
Tools
Nineteen intent-shaped tools, each tagged with MCP safety annotations. Full reference:
docs/tools.md.
Tool | Kind | Description |
| read | Search/filter issues by status, assignee, tracker, dates⦠|
| read | Full issue detail, optionally with journals and attachments |
| write | Create an issue |
| write | Edit an issue's status, assignee, notes⦠|
| write Β· destructive | Permanently delete an issue β no undo, cascades |
| write | Add/remove a watcher (notification subscription) |
| read | Dependency links of an issue, or one relation by its id |
| write | Link two issues (blocks, precedes, duplicates, relatesβ¦) |
| write Β· destructive | Remove one link β narrow in scope and reversible |
| read | Free-text search across issues, wiki, news, projects |
| read | List visible projects |
| read | Full project detail, trackers/categories/activities |
| read | Query logged time |
| write | Log hours against an issue or project |
| read | "Who am I" β the API key's user, memberships, groups |
| read | Find users by name/status/group β admin-gated on most sites |
| read | Statuses, trackers, priorities, activities, doc categories |
| write | Upload a local file β token for an issue's |
| write | Save an attachment to a local directory (writes to disk) |
Heads up:
redmine_delete_issueis the tool that destroys data β Redmine has no trash, and the delete takes the issue's comments, time entries, attachments, and relations with it. It is annotateddestructiveHint: trueso an MCP client can require confirmation; if your client does not gate on that, treat every call as final.redmine_delete_issue_relationcarries the same annotation but is far narrower: it removes one link between two issues, andredmine_create_issue_relationputs it back in a single call.
Heads up: on write, Redmine silently ignores an unknown
tracker_id,status_id, orfixed_version_idinstead of erroring β always check the returned issue. The same applies tois_private, which is silently dropped if your role lacks the "set public/private" permission.
Security
The server runs locally and acts as a single user: your REDMINE_API_KEY never leaves your
machine except as a request header to your own Redmine instance, and the server can do nothing
your account couldn't already do. Multi-user HTTP transport is planned but not yet implemented β
selecting MCP_TRANSPORT=http exits with a clear error.
Local file access is off by default and confined to
REDMINE_ALLOWED_DIRECTORIES when you enable it. Nothing
else in the server reads or writes your filesystem.
Troubleshooting
Symptom | Likely cause |
Client shows no tools | Something besides JSON-RPC is writing to stdout β check any wrapper |
Exits immediately on startup | A required env var is missing or invalid; the error names it |
| API key missing/wrong, or REST API disabled on the Redmine side |
| The key's user lacks permission for that action |
| The id doesn't exist or isn't visible to the key |
| Redmine rejected the write β check the field-level messages returned |
Documentation
docs/architecture.mdβ design and request lifecycledocs/tools.mdβ generated per-tool referencedocs/adding-a-tool.mdβ recipe for adding a new toolCONTRIBUTING.mdβ dev setup and contribution guide
Development
npm install # install dependencies
npm run dev # watch-run the stdio server
npm test # run the test suite
npm run build # bundle to dist/License
Available Tools
19 toolsredmine_create_issueCreate issueA
Create a new issue (bug, feature, task) in a project with subject, description, tracker, priority, assignee, dates, and custom fields. Returns the created issue with its id.
Inputs: subject (required), project_id (required), uploads, due_date, +14 more.
redmine_create_issue_relationCreate issue relationA
Link two issues with a typed relation β how dependencies are recorded when planning, e.g. "#42 cannot start until #17 ships". The relation is directional and reads as "issue_id <relation_type> issue_to_id", so state it once from the source issue: Redmine stores a single record and presents the inverse automatically on the other issue. Do NOT call this tool again with the ids swapped to "complete the pair" β that is either rejected as a duplicate or creates a second, redundant link. Use "relates" when no ordering is implied. delay (in days) applies only to "precedes"/"follows". Redmine rejects some relations on purpose β relating an issue to itself, a duplicate of an existing link, a circular "precedes" chain, or a cross-project link when the "cross_project_issue_relations" setting is off β and its message is passed back verbatim, so read it rather than retrying blindly. Read existing links first with redmine_list_issue_relations; undo one with redmine_delete_issue_relation.
Inputs: issue_id (required), issue_to_id (required), relation_type (required), delay.
redmine_create_time_entryCreate time entryA
Log hours against an issue or project with an activity type and comment β e.g. "log 3.5 hours on #456 for implementing auth". Exactly one of issue_id or project_id is required.
Inputs: hours (required), user_id, comments, issue_id, +4 more.
redmine_delete_issueDelete issueADestructive
Permanently delete an issue. THIS CANNOT BE UNDONE: Redmine has no trash and no restore, and the delete cascades β the issue's journals (comments), logged time entries, attachments, and relations are destroyed with it, and on many configurations its sub-issues are deleted too. Always confirm with the user before calling, quoting the issue id and subject (use redmine_get_issue to read them back first). In most situations the right tool is redmine_update_issue instead: setting a closed or rejected status_id takes the issue out of the way while keeping its history and staying reversible. Reserve this tool for genuine mistakes β duplicates, spam, or an issue filed in the wrong place. Requires the "Delete issues" permission; without it Redmine answers with a permission error.
Inputs: issue_id (required).
redmine_delete_issue_relationDelete issue relationADestructive
Remove a relation (dependency link) between two issues β the cleanup path for a wrong link, e.g. a false "duplicates" or an inverted "blocks". Takes the RELATION id, not an issue id: call redmine_list_issue_relations with the issue_id first to find the relation and its id. Deleting removes the link in both directions at once (Redmine stores one record and derives the inverse), so there is no second side to clean up. Nothing but the link is touched β both issues, their history, and their other relations are untouched β and the link is restored by a single redmine_create_issue_relation call, so this is far less consequential than deleting an issue. A repeated call fails with a not-found error rather than succeeding quietly.
Inputs: issue_relation_id (required).
redmine_download_attachmentDownload attachmentAIdempotent
Download a Redmine attachment and save it into a local directory. Find the id with redmine_get_issue using include: ["attachments"]. The file is written into save_path under the attachment's own name unless you override filename. The destination must be inside the operator-configured REDMINE_ALLOWED_DIRECTORIES, and an existing file is never overwritten β the call fails instead, so pass a different filename or directory to retry. Returns where the file was saved, its name, and its size in bytes.
Inputs: save_path (required), attachment_id (required), filename.
redmine_get_current_userGet current userARead-only
Identify who the API key belongs to, plus optional memberships and groups β the "who am I" call to make at the start of a session for default-assignee logic and permission-aware suggestions.
Inputs: include.
redmine_get_issueGet issueARead-only
Fetch full detail on a single issue, optionally expanded with journals, attachments, relations, children, watchers, and allowed status transitions. Reach for this before editing an issue to see current state and what is legal to change it to.
Inputs: issue_id (required), include.
redmine_get_projectGet projectARead-only
Show full detail for one project, optionally including its trackers, issue categories, time-entry activities, enabled modules, and issue custom fields β needed before creating issues or time entries in an unfamiliar project.
Inputs: project_id (required), include.
redmine_list_issue_relationsList issue relationsARead-only
Read the relations (dependency links) between issues β use it before reporting blockers or sequencing work. Pass exactly one of issue_id (all relations of that issue, returned as { relations: [...] }) or issue_relation_id (one relation by its own id). Each relation reads as "issue_id <relation_type> issue_to_id": issue_id is the SOURCE and issue_to_id the TARGET. Directions: "blocks" β the source blocks the target, so the target cannot be finished first; "blocked" β the source is blocked by the target; "precedes" β the source must finish before the target starts (with an optional delay in days); "follows" β the source starts after the target finishes; "duplicates"/"duplicated", "copied_to"/"copied_from" mirror each other the same way; "relates" is a plain, non-directional link. Redmine stores one record per link and derives the inverse, so an issue is listed as the source of some of its relations and the target of others β never assume issue_id equals the id you queried; compare both ids to work out which way the dependency points. The id of a relation is what redmine_delete_issue_relation takes.
Inputs: issue_id, issue_relation_id.
redmine_list_issuesList issuesARead-only
Search and filter issues across one or all projects β the primary entry point for "what's on the board". Supports status/assignee/tracker/date/custom-field filters, saved queries, sorting, and pagination.
Inputs: sort, limit, offset, include, +13 more.
redmine_list_projectsList projectsARead-only
List the projects the API key can see, optionally filtered by name, status, parent, or visibility β the standard "what projects exist" orientation call.
Inputs: name, limit, offset, status, +3 more.
redmine_list_reference_dataList reference dataARead-only
Look up the legal values behind the id parameters the write tools require β issue statuses, trackers, priorities, time-entry activities, or document categories β selected by kind. Call this before creating or updating an issue or time entry instead of guessing an id. These are the global, instance-wide lists; for what a single project actually has enabled, use redmine_get_project with include ("trackers", "issue_categories", "time_entry_activities").
Inputs: kind (required).
redmine_list_time_entriesList time entriesARead-only
Query logged time by user, project, issue, date range, or activity β used for timesheet review ("what did I log this week") and billing/reporting.
Inputs: to, from, sort, limit, +6 more.
redmine_list_usersList usersARead-only
Find Redmine users by name, status, or group β the way to turn a person's name into the numeric id that assigned_to_id, author_id, and watcher_user_ids require. Note that listing users requires admin permission on most Redmine instances; a non-admin API key gets a permission error, in which case ask the human for the id or use redmine_get_current_user for your own.
Inputs: name, limit, offset, status, +1 more.
redmine_manage_issue_watchersManage issue watchersAIdempotent
Add or remove a watcher on an existing issue β the notification subscription, e.g. "watch this bug for me" or "stop notifying John about #42". Pass the issue id, the user id, and action ("add" or "remove"). Get the user id from redmine_list_users (by name) or redmine_get_current_user (for yourself); read the current watchers with redmine_get_issue and include: ["watchers"]. Nothing is destroyed: removing a watcher only stops notifications and is reversed by adding them back. NOTE: managing watchers needs the separate "Manage watchers" Redmine permission, which an otherwise-capable API key often lacks β a permission error here means exactly that and does not mean the issue or user is missing, so do not retry with different ids.
Inputs: action (required), user_id (required), issue_id (required).
redmine_searchSearchARead-only
Free-text search across issues, wiki pages, news, and projects in one call. Best first move for vague requests where the issue id or project is unknown; prefer redmine_list_issues when you already have concrete filter values.
Inputs: q (required), news, limit, scope, +7 more.
redmine_update_issueUpdate issueA
Edit an issue: change status, reassign, reprioritize, adjust dates/done_ratio, and add a comment (notes) in the same call. Returns the re-fetched, updated issue for confirmation.
Inputs: issue_id (required), notes, subject, uploads, +16 more.
redmine_upload_attachmentUpload attachmentA
Upload a local file to Redmine and get back an upload token. This is the first half of a two-step flow and does nothing visible on its own: the token is not attached to anything until you pass it to redmine_create_issue or redmine_update_issue in their uploads array (e.g. uploads: [{ token, filename, description }]) β the returned object is already shaped for exactly that. Tokens expire, so make the second call promptly. The file must sit inside the operator-configured REDMINE_ALLOWED_DIRECTORIES, and Redmine may reject files over its own attachment size limit.
Inputs: file_path (required), description.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 19 tools
Each tool targets a distinct Redmine operation (e.g., CRUD issues, relations, watchers, search, projects, time entries, users, attachments). There is no ambiguity between similar tools like list_issues and search - one is for structured filtering, the other for free-text across multiple entity types.
All tools follow a consistent 'redmine_verb_noun' pattern, e.g., redmine_create_issue, redmine_list_projects. Minor deviations: redmine_search lacks a noun complement, and redmine_manage_issue_watchers uses 'manage' instead of a more specific verb, but overall the pattern is predictable.
With 19 tools, the set is on the higher end of the recommended range for a focused server. However, Redmine's feature breadth (issues, projects, time tracking, users, attachments, search) justifies the count. The tools are well-scoped without being excessive.
The tool surface covers the core Redmine lifecycle: CRUD for issues, relations (create/list/delete), watchers, time entries (create/list), projects (list/get), users (list/get current), attachments (upload/download), and reference data. Minor gaps exist (e.g., no project update/delete, no time entry update/delete), but these are less critical for typical use.
Maintenance
Related MCP Connectors
Manage Redbooth tasks, task lists, comments, tags and files from Claude and other AI assistants.
Task and bug tracker for AI coding agents: 75 tools to file, triage and update work.
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI assistants to interact with Redmine project management systems, providing comprehensive access to issues, projects, time tracking, users, and wiki pages through natural language commands.3359 npm1Apache 2.0
- AlicenseAqualityCmaintenanceEnables AI agents to interact with Redmine API for managing tickets, projects, users, and time entries. Supports comprehensive operations including issue creation/updates, project management, time logging, and search with dual authentication (Basic Auth + API Key).1436 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Redmine instances to manage issues, projects, and users. It provides comprehensive tools for issue tracking, project oversight, and user management through the Redmine REST API.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI applications to interact with Redmine project management systems for issue tracking, time logging, and project management through natural language.MIT