Skip to main content
Glama
Redmine MCP Server

Redmine MCP Server

by 0xkillaflow

🦎 Agama β€” Redmine MCP Server

npm version License Node Version GitHub Issues CI Coverage npm downloads

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-mcp

The 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

REDMINE_URL

yes

β€”

Base URL of the Redmine instance

REDMINE_API_KEY

yes

β€”

API key for the acting user

REDMINE_TIMEOUT_MS

no

30000

Per-request timeout in milliseconds

REDMINE_ALLOWED_DIRECTORIES

no

empty

Directories the attachment tools may use

LOG_LEVEL

no

info

debug | info | warn | error

MCP_TRANSPORT

no

stdio

stdio (only supported mode today)

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-downloads

It 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

redmine_list_issues

read

Search/filter issues by status, assignee, tracker, dates…

redmine_get_issue

read

Full issue detail, optionally with journals and attachments

redmine_create_issue

write

Create an issue

redmine_update_issue

write

Edit an issue's status, assignee, notes…

redmine_delete_issue

write Β· destructive

Permanently delete an issue β€” no undo, cascades

redmine_manage_issue_watchers

write

Add/remove a watcher (notification subscription)

redmine_list_issue_relations

read

Dependency links of an issue, or one relation by its id

redmine_create_issue_relation

write

Link two issues (blocks, precedes, duplicates, relates…)

redmine_delete_issue_relation

write Β· destructive

Remove one link β€” narrow in scope and reversible

redmine_search

read

Free-text search across issues, wiki, news, projects

redmine_list_projects

read

List visible projects

redmine_get_project

read

Full project detail, trackers/categories/activities

redmine_list_time_entries

read

Query logged time

redmine_create_time_entry

write

Log hours against an issue or project

redmine_get_current_user

read

"Who am I" β€” the API key's user, memberships, groups

redmine_list_users

read

Find users by name/status/group β€” admin-gated on most sites

redmine_list_reference_data

read

Statuses, trackers, priorities, activities, doc categories

redmine_upload_attachment

write

Upload a local file β†’ token for an issue's uploads array

redmine_download_attachment

write

Save an attachment to a local directory (writes to disk)

Heads up: redmine_delete_issue is 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 annotated destructiveHint: true so an MCP client can require confirmation; if your client does not gate on that, treat every call as final. redmine_delete_issue_relation carries the same annotation but is far narrower: it removes one link between two issues, and redmine_create_issue_relation puts it back in a single call.

Heads up: on write, Redmine silently ignores an unknown tracker_id, status_id, or fixed_version_id instead of erroring β€” always check the returned issue. The same applies to is_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

401 Unauthorized

API key missing/wrong, or REST API disabled on the Redmine side

403 Forbidden

The key's user lacks permission for that action

404 Not Found

The id doesn't exist or isn't visible to the key

422 Unprocessable Entity

Redmine rejected the write β€” check the field-level messages returned

Documentation

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

MIT

Available Tools

19 tools
redmine_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 issueA
Destructive

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 relationA
Destructive

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 attachmentA
Idempotent

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 userA
Read-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 issueA
Read-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 projectA
Read-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 relationsA
Read-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 issuesA
Read-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 projectsA
Read-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 dataA
Read-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 entriesA
Read-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 usersA
Read-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 watchersA
Idempotent

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_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

    A4.1/5.0

    Scored across 19 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      33
      59 npm
      1
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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).
      14
      36 npm
      MIT