Skip to content
Back to search

redmine-mcp-server

MCP server connecting AI assistants to Redmine: issues, projects, wikis, time tracking, agile boards, and CRM, with OAuth2 multi-user support

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/jztan/redmine-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/jztan/redmine-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jztan--redmine-mcp-server/badge.svg)](/listings/jztan--redmine-mcp-server)

HTML

<a href="/listings/jztan--redmine-mcp-server"><img src="/api/listings/jztan--redmine-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. **Install the package**

   pip install redmine-mcp-server

2. **Create a `.env` file** with your Redmine credentials (see [Installation](#installation) for template) 3. **Start the server**

   redmine-mcp-server

4. **Add the server to your MCP client** using one of the guides in [MCP Client Configuration](#mcp-client-configuration).

Once running, the server listens on `http://localhost:8000` with the MCP endpoint at `/mcp`, health check at `/health`, and file serving at `/files/{file_id}`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 921 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Redmine MCP Server
  2. [![PyPI Version](https://img.shields.io/pypi/v/redmine-mcp-server.svg)](https://pypi.org/project/redmine-mcp-server/)
  3. [![License](https://img.shields.io/github/license/jztan/redmine-mcp-server.svg)](LICENSE)
  4. [![Python Version](https://img.shields.io/pypi/pyversions/redmine-mcp-server.svg)](https://pypi.org/project/redmine-mcp-server/)
  5. [![Redmine Version](https://img.shields.io/badge/Redmine-6.1%20%7C%207.0-blue.svg)](#redmine-compatibility)
  6. [![GitHub Issues](https://img.shields.io/github/issues/jztan/redmine-mcp-server.svg)](https://github.com/jztan/redmine-mcp-server/issues)
  7. [![CI](https://github.com/jztan/redmine-mcp-server/actions/workflows/pr-tests.yml/badge.svg)](https://github.com/jztan/redmine-mcp-server/actions/workflows/pr-tests.yml)
  8. [![Coverage](https://codecov.io/gh/jztan/redmine-mcp-server/branch/master/graph/badge.svg)](https://codecov.io/gh/jztan/redmine-mcp-server)
  9. [![Downloads](https://pepy.tech/badge/redmine-mcp-server)](https://pepy.tech/project/redmine-mcp-server)
  10. A Model Context Protocol (MCP) server that connects AI assistants to Redmine. It exposes your Redmine instance's projects, issues, time tracking, wiki pages, and files as MCP tools.
  11. **mcp-name: io.github.jztan/redmine-mcp-server**
  12. <p align="center">
  13. <a href="https://redmine-mcp-server.jztan.com">
  14. <img src="https://raw.githubusercontent.com/jztan/redmine-mcp-server/develop/assets/redmine-mcp-demo.gif" alt="An AI agent triaging a Redmine sprint backlog through redmine-mcp-server" width="820" />
  15. </a>
  16. </p>
  17. <p align="center"><sub>An AI agent triaging a Redmine sprint through redmine-mcp-server. <a href="https://redmine-mcp-server.jztan.com">Try the live demo →</a></sub></p>
  18. ## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./docs/contributing.md) | [Troubleshooting](./docs/troubleshooting.md)
  19. ## Features
  20. - **53 MCP tools on a stock Redmine, 69 with the RedmineUP and DMSF plugins** (plus 1 operator tool gated by `REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true`): Issues, projects, news, time tracking, wiki, Gantt, file operations, membership management, products and orders, contacts and deals (CRM), DMSF documents, Helpdesk email replies and ticket contacts, and more
  21. - **Interactive Kanban Board**: `show_triage_board` renders a live, drag-and-drop issue board right in the chat via the MCP Apps extension
  22. - **Flexible Authentication**: API key, username/password, OAuth2 per-user tokens, or a browser login with each user's own API key on Redmines without OAuth
  23. - **Prompt Injection Protection**: User-controlled content wrapped in boundary tags for safe LLM consumption
  24. - **Read-Only Mode**: Restrict to read-only operations via `REDMINE_MCP_READ_ONLY` environment variable
  25. - **HTTP File Serving**: Secure attachment access via UUID-based URLs with automatic expiry
  26. - **Pagination Support**: Handle large result sets with configurable limits
  27. - **MCP Compliant**: Built on FastMCP with HTTP transport
  28. - **Docker Ready**: Dockerfile, docker-compose setup, and prebuilt images on GHCR
  29. ## Quick Start
  30. 1. **Install the package**
  31. ```bash
  32. pip install redmine-mcp-server
  33. ```
  34. 2. **Create a `.env` file** with your Redmine credentials (see [Installation](#installation) for template)
  35. 3. **Start the server**
  36. ```bash
  37. redmine-mcp-server
  38. ```
  39. 4. **Add the server to your MCP client** using one of the guides in [MCP Client Configuration](#mcp-client-configuration).
  40. Once running, the server listens on `http://localhost:8000` with the MCP endpoint at `/mcp`, health check at `/health`, and file serving at `/files/{file_id}`.
  41. ## Installation
  42. ### Prerequisites
  43. - Python 3.11+ (for local installation)
  44. - Docker (alternative deployment, uses Python 3.13)
  45. - Access to a Redmine instance
  46. #### Redmine Compatibility
  47. The integration suite passes in full against Redmine 6.1 and 7.0. Older
  48. versions are untested. Individual tools list their own minimum where one is
  49. known (global search needs 3.3.0+, issue watchers 2.3.0+, project time-entry
  50. activities 3.4.0+), so on an older server those specific tools fail rather than
  51. the whole server.
  52. Per-user authentication works on any version: OAuth2 needs Redmine 6.1+ for
  53. Doorkeeper, and the other per-user modes do not. See
  54. [Authentication](#authentication) to pick a mode.
  55. ### Install from PyPI (Recommended)
  56. ```bash
  57. # Install the package
  58. pip install redmine-mcp-server
  59. # Create configuration file .env
  60. cat > .env << 'EOF'
  61. # Redmine connection (required)
  62. REDMINE_URL=https://your-redmine-server.com
  63. # Authentication - Use either API key (recommended) or username/password
  64. REDMINE_API_KEY=your_api_key
  65. # OR use username/password:
  66. # REDMINE_USERNAME=your_username
  67. # REDMINE_PASSWORD=your_password
  68. # Server configuration (optional, defaults shown)
  69. SERVER_HOST=0.0.0.0
  70. SERVER_PORT=8000
  71. # Public URL for file serving (optional)
  72. PUBLIC_HOST=localhost
  73. PUBLIC_PORT=8000
  74. # File management (optional)
  75. ATTACHMENTS_DIR=./attachments
  76. AUTO_CLEANUP_ENABLED=true
  77. CLEANUP_INTERVAL_MINUTES=10
  78. ATTACHMENT_EXPIRES_MINUTES=60
  79. EOF
  80. # Edit .env with your actual Redmine settings
  81. nano .env # or use your preferred editor
  82. # Run the server
  83. redmine-mcp-server
  84. # Or alternatively:
  85. python -m redmine_mcp_server.main
  86. ```
  87. The server runs on `http://localhost:8000` with the MCP endpoint at `/mcp`, health check at `/health`, and file serving at `/files/{file_id}`.
  88. ### Environment Variables Configuration
  89. <details>
  90. <summary><strong>Environment Variables</strong></summary>
  91. | Variable | Required | Default | Description |
  92. |----------|----------|---------|-------------|
  93. | `REDMINE_URL` | Yes | – | Base URL of your Redmine instance |
  94. | `REDMINE_AUTH_MODE` | No | `legacy` | Authentication mode: `legacy`, `legacy-per-user`, `oauth`, `oauth-proxy`, or `api-key-login` (see [Authentication](#authentication)) |
  95. | `REDMINE_PER_USER_TRUST_PROXY` | Yes* | `false` | Required for `legacy-per-user` mode. Operator attestation: "this server sits behind TLS and my proxy does not forward client `X-Forwarded-Proto`." |
  96. | `REDMINE_PER_USER_AUDIT_IDENTITY` | No | `false` | `legacy-per-user` only: resolve and log the Redmine user ID per request (adds one extra round-trip) |
  97. | `REDMINE_API_KEY_LOGIN_ALLOW_ADMIN` | No | `false` | `api-key-login` only: accept the API keys of Redmine administrators. Tokens never carry the `admin` scope either way ([details](docs/api-key-login-auth.md#administrator-accounts)) |
  98. | `REDMINE_API_KEY_LOGIN_ALLOW_HTTP` | No | `false` | `api-key-login` only: allow an `http://` `REDMINE_MCP_BASE_URL`. Local development only |
  99. | `REDMINE_API_KEY_LOGIN_SESSION_DAYS` | No | `30` | `api-key-login` only: how long a session lasts before the user logs in again. Must be positive |
  100. | `REDMINE_API_KEY_LOGIN_RATE_LIMIT` | No | `300` | `api-key-login` only: login attempts per minute, a process-wide safety ceiling |
  101. | `REDMINE_API_KEY_LOGIN_BINDING_CRYPTO` | No | `server-secret` | `api-key-login` only: `server-secret` or `token-derived`. `token-derived` puts stored API keys beyond the reach of the volume plus the signing key, at the cost of any server-side read ([details](docs/api-key-login-auth.md#binding-protection)) |
  102. | `REDMINE_API_KEY` | Yes† | – | API key (legacy mode only) |
  103. | `REDMINE_USERNAME` | Yes† | – | Username for basic auth (legacy mode only) |
  104. | `REDMINE_PASSWORD` | Yes† | – | Password for basic auth (legacy mode only) |
  105. | `REDMINE_MCP_BASE_URL` | Yes‡¶ | `http://localhost:3040` | Public base URL of this server, no trailing slash (OAuth modes and `api-key-login`) |
  106. | `FASTMCP_STREAMABLE_HTTP_PATH` | No | `/mcp` | MCP transport path inside `REDMINE_MCP_BASE_URL` |
  107. | `REDMINE_INTROSPECT_CLIENT_ID` | Yes‡ | – | Doorkeeper OAuth client ID used by the MCP server to introspect Bearer tokens (RFC 7662). Register a confidential OAuth app in Redmine (see [`docs/oauth-setup.md`](docs/oauth-setup.md) Step 2). |
  108. | `REDMINE_INTROSPECT_CLIENT_SECRET` | Yes‡ | – | Secret for the introspection client |
  109. | `REDMINE_MCP_JWT_SIGNING_KEY` | Yes§¶ | – | Stable signing/encryption key used by FastMCP OAuthProxy tokens and storage, and by the `api-key-login` store. Changing it signs everyone out |
  110. | `REDMINE_OAUTH_CLIENT_ID` | No | – | Optional upstream Redmine OAuth client ID for `oauth-proxy`; defaults to `REDMINE_INTROSPECT_CLIENT_ID` |
  111. | `REDMINE_OAUTH_CLIENT_SECRET` | No | – | Optional upstream Redmine OAuth client secret for `oauth-proxy`; defaults to `REDMINE_INTROSPECT_CLIENT_SECRET` |
  112. | `FASTMCP_HOME` | No | platform default (`/app/data/fastmcp` in Docker) | FastMCP data directory. In `oauth-proxy` mode, encrypted OAuthProxy state is stored below `FASTMCP_HOME/oauth-proxy/`, and in `api-key-login` mode below `FASTMCP_HOME/api-key-login/`. Either must be on a persistent volume to survive a container rebuild |
  113. | `REDMINE_MCP_ALLOWED_CLIENT_REDIRECT_URIS` | No | loopback only | `oauth-proxy` and `api-key-login` client redirect-URI allowlist (glob patterns, comma/space separated). Unset = `http://localhost:*` and `http://127.0.0.1:*`; `*` = allow any |
  114. | `REDMINE_MCP_ACCESS_TOKEN_EXPIRY_SECONDS` | No | Redmine's `expires_in` (2h) | `oauth-proxy` only. Lifetime of the access token the proxy issues to clients. Raise it (e.g. `604800`) so clients rarely refresh; the upstream Redmine token is still refreshed server-side. Unset or `0` mirrors Redmine |
  115. | `HEALTH_INTROSPECTION_TTL_SECONDS` | No | `30` | TTL (seconds) for the `/health` Doorkeeper introspection probe cache. Set to `0` to disable caching. |
  116. | `SERVER_HOST` | No | `0.0.0.0` | Host/IP the MCP server binds to |
  117. | `SERVER_PORT` | No | `8000` | Port the MCP server listens on |
  118. | `REDMINE_MCP_TRANSPORT` | No | `http` | `http` serves MCP at `/mcp`. `stdio` serves it over stdin/stdout to a client that starts the server itself, with no port and no bridge; `legacy` mode only. Any other value refuses to start ([details](#stdio-transport)) |
  119. | `PUBLIC_HOST` | No | `localhost` | Hostname used when generating download URLs |
  120. | `PUBLIC_PORT` | No | `8000` | Public port used for download URLs |
  121. | `PUBLIC_SCHEME` | No | derived | Scheme for download URLs (`http` or `https`). When unset, `https` is derived from `PUBLIC_PORT=443`, otherwise `http`. Set explicitly for TLS on a nonstandard port. Default ports (80/443) are omitted from generated URLs. |
  122. | `REDMINE_PUBLIC_URL` | No | – | Publicly-reachable URL of your Redmine instance. When set, `content_url` values returned on attachments are rewritten from `REDMINE_URL`'s origin to this one (preserving path/query/fragment and any reverse-proxy subpath). Useful when `REDMINE_URL` is the internal container hostname unreachable from MCP clients. When unset, the raw URL Redmine echoes back is returned. |
  123. | `ATTACHMENTS_DIR` | No | `./attachments` | Directory for downloaded attachments |
  124. | `ATTACHMENT_MAX_DOWNLOAD_BYTES` | No | `209715200` (200 MB) | Cap applied to every `get_redmine_attachment` download regardless of content type. Exceeding the cap aborts the download mid-stream and deletes the partial file. |
  125. | `REDMINE_MCP_UPLOAD_FILE_ROOTS` | No | – | Extra directories allowed as `file_path` upload sources (OS path separator-separated). `ATTACHMENTS_DIR` is always allowed. Unset restricts uploads to `ATTACHMENTS_DIR` only. |
  126. | `AUTO_CLEANUP_ENABLED` | No | `true` | Toggle automatic cleanup of expired attachments |
  127. | `CLEANUP_INTERVAL_MINUTES` | No | `10` | Interval for cleanup task (also deletes expired OAuth state in `oauth-proxy` and `api-key-login` modes) |
  128. | `ATTACHMENT_EXPIRES_MINUTES` | No | `60` | Expiry window for generated download URLs |
  129. | `REDMINE_MCP_JOURNAL_VALUE_MAX_CHARS` | No | `500` | Above this many characters, a journal field-change reports its before/after text as `old_value_length` / `new_value_length` with `elided: true` instead of in full. Redmine records a description edit with both texts, so a repeatedly edited ticket otherwise returns several copies of its description. `0` disables eliding; `get_redmine_issue` and `get_private_notes` take `include_journal_values=true` per call. |
  130. | `REDMINE_MCP_EXPOSE_ADMIN_TOOLS` | No | `false` | Expose operator/admin tools on the MCP surface. Currently gates `cleanup_attachment_files`. The background cleanup task runs regardless of this flag. |
  131. | `REDMINE_SSL_VERIFY` | No | `true` | Enable/disable SSL certificate verification |
  132. | `REDMINE_SSL_CERT` | No | – | Path to custom CA certificate file |
  133. | `REDMINE_SSL_CLIENT_CERT` | No | – | Path to client certificate for mutual TLS |
  134. | `REDMINE_TIMEOUT` | No | `30` | Whole seconds to wait for a Redmine HTTP response before failing the call. Applied as a connect timeout of at most 10s plus a read timeout of the full value. Set to `0` to wait indefinitely, which restores the previous behavior and can hang the request. |
  135. | `REDMINE_MCP_READ_ONLY` | No | `false` | Block all write operations (create/update/delete) when set to `true` |
  136. | `REDMINE_MCP_ALLOW_TOOLS` | No | – | Expose only these tools (comma-separated names). Unset exposes all; set but naming no tool refuses to start. Narrows the surface only: a listed tool whose plugin flag is off stays hidden. Whole tools, so per-action control on `manage_X` remains `REDMINE_MCP_READ_ONLY`'s job. Names matching no tool are warned about at startup ([details](docs/tool-reference.md#tool-allow-list)) |
  137. | `REDMINE_MCP_ALLOW_TOOLS_FILE` | No | – | Path to a file with one allowed tool name per line (`#` starts a comment). Used when `REDMINE_MCP_ALLOW_TOOLS` is unset or empty |
  138. | `REDMINE_MCP_EXTENSIONS` | No | – | Python modules to import at startup so they can register tools for an in-house Redmine plugin (comma- or whitespace-separated, imported in order). Unset means none. A module that fails to import, or that claims a family or tool name already taken, stops the server ([details](docs/extensions.md)) |
  139. | `REDMINE_OAUTH_SCOPE_ENFORCEMENT` | No | `on` | OAuth modes and `api-key-login` only: deny tool calls whose access token lacks the tool's Redmine permission scopes, and filter `tools/list` accordingly. Set to `off` temporarily while re-consenting older tokens ([details](docs/oauth-setup.md#scope-enforcement)) |
  140. | `REDMINE_OAUTH_DISCOVERY_AS` | No | `redmine` | OAuth modes only: which authorization server discovery advertises. `redmine` names your Redmine; `self` advertises this server (issuer = `REDMINE_MCP_BASE_URL`) and serves RFC 8414 metadata at its own canonical well-known location, which clients that probe there need, Cursor among them ([details](docs/oauth-setup.md#cursor-and-self-as-discovery)) |
  141. | `REDMINE_MCP_SCOPES` | No | – | OAuth modes and `api-key-login` only: advertise a subset of scopes in discovery, matching the permissions your Redmine OAuth Application actually enables. Avoids `invalid_scope` at consent when a client requests the full advertised list. In `api-key-login` it only narrows the scopes this server offers |
  142. | `REDMINE_AGILE_ENABLED` | No | `false` | Enable RedmineUP Agile plugin support: `get_redmine_issue` returns `story_points`, `agile_sprint_id`, `agile_position`; `update_redmine_issue` accepts `story_points` |
  143. | `REDMINE_CHECKLISTS_ENABLED` | No | `false` | Enable RedmineUP Checklists plugin support: `get_checklist`, `create_checklist_item`, `update_checklist_item` (requires Checklists Pro plugin) |
  144. | `REDMINE_PRODUCTS_ENABLED` | No | `false` | Enable RedmineUP Products plugin support: `manage_product` (action=list/get/create/update) |
  145. | `REDMINE_ORDERS_ENABLED` | No | `false` | Enable RedmineUP Products **orders** support: `manage_order` (action=list/get, read-only). Separate from `REDMINE_PRODUCTS_ENABLED` because the plugin declares orders as their own project module with their own permissions, so a deployment may enable one without the other. Requires the Products plugin, the `orders` project module enabled on the project, and the `view_orders_list` and `view_orders` permissions; under OAuth the flag advertises both, which the Redmine OAuth application must grant before the flag is turned on. |
  146. | `REDMINE_CRM_ENABLED` | No | `false` | Enable RedmineUP CRM plugin support: `manage_contact` (action=list/get/create/update/delete/assign_to_project/remove_from_project) `list_contact_tags`, `manage_crm_note` (notes on contacts) and `list_crm_queries`. Requires the CRM plugin and the `view_contacts` / `view_private_contacts` permissions on the Redmine server, plus `add_contacts` / `edit_contacts` / `delete_contacts` for the write actions. In OAuth mode these are advertised as scopes only when this flag is set, so the OAuth application must grant them too. |
  147. | `REDMINE_CRM_EDITION` | No | `light` | Which build of the CRM plugin the Redmine server runs: `light` or `pro`. The two register different contact query filters — the Pro build registers the contact fields, the Light build registers only `tags` — and Redmine ignores an unregistered filter parameter without erroring, answering with the whole collection instead. So `manage_contact` refuses `first_name`, `last_name`, `middle_name`, `company`, `job_title`, `email`, `phone` and `author_id` on `list` unless this is `pro`, rather than returning a silently unfiltered list. The build cannot be detected: Redmine exposes plugin versions only through `admin/plugins`, which is HTML and admin-only. |
  148. | `REDMINE_TEXT_FORMATTING` | No | `auto` | Markup the Redmine server renders text with: `textile`, `markdown`, `common_mark` or `none`. `auto` detects it once from an issue page, and the text-writing tools' descriptions then tell the model which syntax to use. If detection can't run (for example the account can't edit or add notes to any visible issue), the model is told to write plain text; set the value explicitly to avoid that. |
  149. | `REDMINE_DEALS_ENABLED` | No | `false` | Enable RedmineUP CRM **deals** support: `manage_deal` (action=list/get/create/update/delete), `list_deal_statuses`, `manage_deal_category`, `manage_crm_note` (notes on deals), `list_crm_queries` and, together with `REDMINE_PRODUCTS_ENABLED`, `add_deal_product`. Separate from `REDMINE_CRM_ENABLED` because the CRM plugin's Light edition ships no deals and defines none of the deal permissions, so advertising them there would make consent fail. Requires the CRM plugin's **Pro** edition, the `deals` project module enabled on the project, and the `view_deals` permission, plus `add_deals` / `edit_deals` / `delete_deals` for the write actions. |
  150. | `REDMINE_CRM_NOTE_EDIT_SCOPES` | No | `false` | OAuth modes only: also advertise `edit_notes` and `edit_own_notes` as scopes when `REDMINE_CRM_ENABLED` or `REDMINE_DEALS_ENABLED` is set. CRM PRO 4.5.1 checks them for `manage_crm_note(action=update)`, so OAuth tokens need them there; earlier CRM versions do not define them, and one unknown scope in the advertised list fails consent with `invalid_scope` for every scope, so they are opt-in. Grant both on the Redmine OAuth application before turning this on. API-key and legacy auth do not need it. |
  151. | `REDMINE_DMSF_ENABLED` | No | `false` | Enable DMSF document-management plugin support: `manage_document` (action=list/get/create/update). Requires `redmine_dmsf` plugin on the Redmine server. |
  152. | `REDMINE_HELPDESK_ENABLED` | No | `false` | Enable RedmineUP Helpdesk plugin support: `send_helpdesk_email_reply` (emails a reply to the ticket's customer). Requires the Helpdesk plugin on the Redmine server. Under OAuth it advertises `send_response`, which the Redmine OAuth application must grant before the flag is turned on. |
  153. | `REDMINE_HELPDESK_TICKETS_ENABLED` | No | `false` | Enable RedmineUP Helpdesk ticket support: `manage_helpdesk_ticket` (action=get/set_contact/create) reads a ticket's Helpdesk data, opens a new ticket for an existing contact, and moves a ticket to another existing contact. Requires the Helpdesk and CRM plugins. Separate from `REDMINE_HELPDESK_ENABLED` because under OAuth it advertises `view_helpdesk_tickets`, `view_contacts`, `view_private_contacts` and `edit_helpdesk_tickets`, which the Redmine OAuth application must grant before the flag is turned on. |
  154. | `REDMINE_TAGS_ENABLED` | No | `false` | Enable AlphaNodes additional_tags plugin support: `get_redmine_issue` returns a `tags` array, and `create_redmine_issue`/`update_redmine_issue` accept a `tag_list`. Requires the `additional_tags` plugin and the `view_issue_tags` / `create_issue_tags` / `edit_issue_tags` permissions on the Redmine server. |
  155. | `REDMINE_AUTOFILL_REQUIRED_CUSTOM_FIELDS` | No | `false` | Enable one retry for issue creation by filling missing required custom fields |
  156. | `REDMINE_REQUIRED_CUSTOM_FIELD_DEFAULTS` | No | `{}` | JSON object mapping required custom field names to fallback values used when creating issues |
  157. | `REDMINE_ALLOW_PRIVATE_FETCH_URLS` | No | `false` | **Warning:** disables all SSRF protection for attachment fetching. Never set to `true` in production. |
  158. *\* Required when `REDMINE_AUTH_MODE=legacy-per-user`.*
  159. *† Required when `REDMINE_AUTH_MODE=legacy`. Either `REDMINE_API_KEY` or `REDMINE_USERNAME`+`REDMINE_PASSWORD` must be set. API key is recommended.*
  160. *‡ Required when `REDMINE_AUTH_MODE=oauth` or `REDMINE_AUTH_MODE=oauth-proxy`.*
  161. *§ Required when `REDMINE_AUTH_MODE=oauth-proxy`.*
  162. *¶ Required when `REDMINE_AUTH_MODE=api-key-login`.*
  163. Secret values can also be supplied with Docker/Kubernetes-style file variables: `REDMINE_INTROSPECT_CLIENT_SECRET_FILE`, `REDMINE_MCP_JWT_SIGNING_KEY_FILE`, and `REDMINE_OAUTH_CLIENT_SECRET_FILE`.
  164. When `REDMINE_AUTOFILL_REQUIRED_CUSTOM_FIELDS=true`, `create_redmine_issue` retries once on relevant custom-field validation errors (for example `<Field Name> cannot be blank` or `<Field Name> is not included in the list`) and fills values only from:
  165. - the Redmine custom field `default_value`, or
  166. - `REDMINE_REQUIRED_CUSTOM_FIELD_DEFAULTS`
  167. In practice only the second one can fire. The server reads project custom fields from `GET /projects/{id}.json?include=issue_custom_fields`, which Redmine renders as id and name only, so it never sees `default_value` -- see [`list_project_issue_custom_fields`](docs/tool-reference.md#list_project_issue_custom_fields). Set the env map if you want autofill to have anything to work with.
  168. Example:
  169. ```bash
  170. REDMINE_AUTOFILL_REQUIRED_CUSTOM_FIELDS=true
  171. REDMINE_REQUIRED_CUSTOM_FIELD_DEFAULTS='{"Required Field A":"Value A","Required Field B":"Value B"}'
  172. ```
  173. </details>
  174. ### SSL Certificate Configuration
  175. Configure SSL certificate handling for Redmine servers with self-signed certificates or internal CA infrastructure.
  176. <details>
  177. <summary><strong>Self-Signed Certificates</strong></summary>
  178. If your Redmine server uses a self-signed certificate or internal CA:
  179. ```bash
  180. # In .env file
  181. REDMINE_URL=https://redmine.company.com
  182. REDMINE_API_KEY=your_api_key
  183. REDMINE_SSL_CERT=/path/to/ca-certificate.crt
  184. ```
  185. Supported certificate formats: `.pem`, `.crt`, `.cer`
  186. </details>
  187. <details>
  188. <summary><strong>Mutual TLS (Client Certificates)</strong></summary>
  189. For environments requiring client certificate authentication:
  190. ```bash
  191. # In .env file
  192. REDMINE_URL=https://secure.redmine.com
  193. REDMINE_API_KEY=your_api_key
  194. REDMINE_SSL_CERT=/path/to/ca-bundle.pem
  195. REDMINE_SSL_CLIENT_CERT=/path/to/cert.pem,/path/to/key.pem
  196. ```
  197. **Note**: Private keys must be unencrypted (Python requests library requirement).
  198. </details>
  199. <details>
  200. <summary><strong>Disable SSL Verification (Development Only)</strong></summary>
  201. ⚠️ **WARNING**: Only use in development/testing environments!
  202. ```bash
  203. # In .env file
  204. REDMINE_SSL_VERIFY=false
  205. ```
  206. Disabling SSL verification makes your connection vulnerable to man-in-the-middle attacks.
  207. </details>
  208. For SSL troubleshooting, see the [Troubleshooting Guide](./docs/troubleshooting.md#ssl-certificate-errors).
  209. ## Authentication
  210. The server supports five authentication modes, selected via `REDMINE_AUTH_MODE`. It defaults to `legacy`, so existing deployments keep working with no changes; OAuth2 support is purely additive.
  211. | Your situation | Mode | Redmine |
  212. |---|---|---|
  213. | Single shared credential, simplest setup | `legacy` (default) | any |
  214. | Multi-user, you control the MCP client | `oauth` | 6.1+ |
  215. | Hosted server, clients self-register (DCR) | `oauth-proxy` | 6.1+ |
  216. | Multi-user, no OAuth on your Redmine, users log in in a browser | `api-key-login` | any, incl. Easy Redmine |
  217. | Multi-user, no OAuth on your Redmine, users set their key in the client | `legacy-per-user` | any |
  218. The advanced modes are collapsed below. For full setup, the [OAuth2 Setup Guide](./docs/oauth-setup.md) covers `oauth` and `oauth-proxy`, the [api-key-login guide](./docs/api-key-login-auth.md) covers `api-key-login`, and the [legacy-per-user guide](./docs/legacy-per-user-auth.md) covers `legacy-per-user`.
  219. ### Legacy mode (default)
  220. A single shared credential (API key or username/password) configured once in `.env`. Every request to Redmine uses the same identity.
  221. ```bash
  222. REDMINE_AUTH_MODE=legacy # or omit entirely; this is the default
  223. REDMINE_URL=https://redmine.example.com
  224. REDMINE_API_KEY=your_api_key
  225. # OR:
  226. # REDMINE_USERNAME=your_username
  227. # REDMINE_PASSWORD=your_password
  228. ```
  229. <details>
  230. <summary><strong>OAuth2 mode</strong> (multi-user, Redmine 6.1+)</summary>
  231. Each MCP request carries its own `Authorization: Bearer <token>`, so every user authenticates with their own Redmine account. The server validates each token against Doorkeeper's introspection endpoint before forwarding it, and exposes the OAuth2 discovery and `/revoke` endpoints clients need.
  232. ```bash
  233. REDMINE_AUTH_MODE=oauth
  234. REDMINE_URL=https://redmine.example.com
  235. REDMINE_MCP_BASE_URL=https://redmine-mcp.example.com # public URL of this server
  236. # Confidential OAuth app registered in Redmine admin (see setup guide)
  237. REDMINE_INTROSPECT_CLIENT_ID=...
  238. REDMINE_INTROSPECT_CLIENT_SECRET=...
  239. ```
  240. You register the OAuth app manually in Redmine admin → **Applications** (no Dynamic Client Registration). Full walkthrough, endpoint reference, and troubleshooting: [OAuth2 Setup Guide](./docs/oauth-setup.md).
  241. </details>
  242. <details>
  243. <summary><strong>OAuthProxy mode</strong> (hosted deployments with client self-registration)</summary>
  244. FastMCP acts as the MCP-facing authorization server: it handles DCR for MCP clients, then redirects users to Redmine as the upstream OAuth provider for consent. Use this when clients (e.g. Claude Desktop, VS Code) expect to register themselves.
  245. ```bash
  246. REDMINE_AUTH_MODE=oauth-proxy
  247. REDMINE_URL=https://redmine.example.com
  248. REDMINE_MCP_BASE_URL=https://redmine-mcp.example.com # public URL of this server
  249. # Confidential OAuth app registered in Redmine admin (see setup guide)
  250. REDMINE_INTROSPECT_CLIENT_ID=...
  251. REDMINE_INTROSPECT_CLIENT_SECRET=...
  252. REDMINE_MCP_JWT_SIGNING_KEY=...
  253. ```
  254. The upstream Redmine app must register `${REDMINE_MCP_BASE_URL}/auth/callback` as its redirect URI. Storage, scaling, and credential-reuse notes are in the [OAuth2 Setup Guide](./docs/oauth-setup.md).
  255. </details>
  256. <details>
  257. <summary><strong>api-key-login mode</strong> (per-user identity without OAuth: Easy Redmine, Redmine older than 6.1)</summary>
  258. The server acts as its own OAuth authorization server, so MCP clients connect with nothing but its URL. On first use the client opens a browser, the user pastes their personal Redmine API key into a page this server serves, and every tool call from then on runs as that user. No key goes into any client configuration, and passwords are never asked for.
  259. ```bash
  260. REDMINE_AUTH_MODE=api-key-login
  261. REDMINE_URL=https://redmine.example.com
  262. REDMINE_MCP_BASE_URL=https://redmine-mcp.example.com # public https URL of this server
  263. REDMINE_MCP_JWT_SIGNING_KEY=... # encrypts the stored keys
  264. ```
  265. The server stores each user's key encrypted below `FASTMCP_HOME/api-key-login/`, so that directory needs a persistent volume and the mode runs as a single replica. OAuth scopes here are a narrowing the client asks for, not Redmine permissions; Redmine's own permissions stay the boundary. Read the [api-key-login guide](./docs/api-key-login-auth.md) for the security model, session rules and client setup before enabling it.
  266. </details>
  267. <details>
  268. <summary><strong>legacy-per-user mode</strong> (Redmine older than 6.1)</summary>
  269. For Redmine instances too old for OAuth, each user's MCP client sends its own Redmine API key in an `X-Redmine-API-Key` header. Each request runs as that user's identity with that user's permissions.
  270. **This is an advanced, opt-in mode.** It requires TLS end-to-end and a correctly configured reverse proxy. Read [`docs/legacy-per-user-auth.md`](docs/legacy-per-user-auth.md) for the threat model, firewall guidance, and revocation runbook before enabling it.
  271. **`mcp-remote` (recommended):**
  272. ```json
  273. { "mcpServers": { "redmine": {
  274. "command": "npx",
  275. "args": ["mcp-remote", "https://your-host/mcp",
  276. "--header", "X-Redmine-API-Key:${RM_KEY}"],
  277. "env": { "RM_KEY": "<your redmine api key>" }
  278. }}}
  279. ```
  280. Note the colon with no surrounding spaces in `X-Redmine-API-Key:${RM_KEY}`. This avoids an arg-escaping bug in Cursor and Claude Desktop on Windows.
  281. **VS Code (`mcp.json`):**
  282. Use `.vscode/mcp.json` (workspace file) or the user profile `mcp.json`. The workspace `.mcp.json` silently drops `headers` (see microsoft/vscode#319528), so do not use that file. Pin VS Code 1.102 or newer.
  283. ```json
  284. {
  285. "servers": {
  286. "redmine": {
  287. "type": "http",
  288. "url": "https://your-host/mcp",
  289. "headers": { "X-Redmine-API-Key": "${input:rmKey}" },
  290. "inputs": [{ "id": "rmKey", "type": "promptString",
  291. "description": "Redmine API key", "password": true }]
  292. }
  293. }
  294. }
  295. ```
  296. **Unsupported:** any client that cannot set a custom request header, or that reserves the `Authorization` header for its own OAuth flow.
  297. </details>
  298. ## MCP Client Configuration
  299. The server exposes an HTTP endpoint at `http://127.0.0.1:8000/mcp`. Register it with your preferred MCP-compatible agent using the instructions below. A client that starts MCP servers itself can run this one over stdio instead, with no running server and no bridge: see [stdio transport](#stdio-transport).
  300. > The examples below assume `legacy` or `oauth` mode. In `legacy-per-user` mode each client must also send an `X-Redmine-API-Key` header; see [legacy-per-user mode](#authentication) above for header-aware configs.
  301. <details>
  302. <summary><strong>Visual Studio Code (Native MCP Support)</strong></summary>
  303. VS Code has built-in MCP support via GitHub Copilot (requires VS Code 1.102+).
  304. **Using CLI (Quickest):**
  305. ```bash
  306. code --add-mcp '{"name":"redmine","type":"http","url":"http://127.0.0.1:8000/mcp"}'
  307. ```
  308. **Using Command Palette:**
  309. 1. Open Command Palette (`Cmd/Ctrl+Shift+P`)
  310. 2. Run `MCP: Open User Configuration` (for global) or `MCP: Open Workspace Folder Configuration` (for project-specific)
  311. 3. Add the configuration:
  312. ```json
  313. {
  314. "servers": {
  315. "redmine": {
  316. "type": "http",
  317. "url": "http://127.0.0.1:8000/mcp"
  318. }
  319. }
  320. }
  321. ```
  322. 4. Save the file. VS Code will automatically load the MCP server.
  323. **Manual Configuration:**
  324. Create `.vscode/mcp.json` in your workspace (or `mcp.json` in your user profile directory):
  325. ```json
  326. {
  327. "servers": {
  328. "redmine": {
  329. "type": "http",
  330. "url": "http://127.0.0.1:8000/mcp"
  331. }
  332. }
  333. }
  334. ```
  335. </details>
  336. <details>
  337. <summary><strong>Claude Code</strong></summary>
  338. Add to Claude Code using the CLI command:
  339. ```bash
  340. claude mcp add --transport http redmine http://127.0.0.1:8000/mcp
  341. ```
  342. Or configure manually in your Claude Code settings file (`~/.claude.json`):
  343. ```json
  344. {
  345. "mcpServers": {
  346. "redmine": {
  347. "type": "http",
  348. "url": "http://127.0.0.1:8000/mcp"
  349. }
  350. }
  351. }
  352. ```
  353. </details>
  354. <details>
  355. <summary><strong>Claude Desktop (macOS & Windows)</strong></summary>
  356. Claude Desktop's config file supports stdio transport only. Use FastMCP's proxy via `uv` to bridge to this HTTP server.
  357. **Setup:**
  358. 1. Open Claude Desktop
  359. 2. Click the **Claude** menu (macOS menu bar / Windows title bar) > **Settings...**
  360. 3. Click the **Developer** tab > **Edit Config**
  361. 4. Add the following configuration:
  362. ```json
  363. {
  364. "mcpServers": {
  365. "redmine": {
  366. "command": "uv",
  367. "args": [
  368. "run",
  369. "--with", "fastmcp",
  370. "fastmcp",
  371. "run",
  372. "http://127.0.0.1:8000/mcp"
  373. ]
  374. }
  375. }
  376. }
  377. ```
  378. 5. Save the file, then **fully quit and restart** Claude Desktop
  379. 6. Look for the tools icon in the input area to verify the connection
  380. **Config file locations:**
  381. - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  382. - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  383. **Note:** The Redmine MCP server must be running before starting Claude Desktop.
  384. </details>
  385. <details>
  386. <summary><strong>Cursor</strong></summary>
  387. Cursor talks to HTTP MCP servers directly, with no bridge.
  388. 1. Create `~/.cursor/mcp.json` (available in every project) or `.cursor/mcp.json` in your project root (that project only):
  389. ```json
  390. {
  391. "mcpServers": {
  392. "redmine": {
  393. "url": "http://127.0.0.1:8000/mcp"
  394. }
  395. }
  396. }
  397. ```
  398. 2. Save the file. Cursor picks the server up automatically; its MCP settings list the server and the tools it loaded.
  399. **Note:** Cursor identifies a remote server by a bare `url` and has no `type` field, unlike the VS Code and Claude Code configs above.
  400. **In `legacy-per-user` mode**, add the API key header:
  401. ```json
  402. {
  403. "mcpServers": {
  404. "redmine": {
  405. "url": "https://your-host/mcp",
  406. "headers": { "X-Redmine-API-Key": "<your redmine api key>" }
  407. }
  408. }
  409. }
  410. ```
  411. **In `oauth` mode**, set `REDMINE_OAUTH_DISCOVERY_AS=self` on the MCP server. Cursor looks for authorization server metadata at its own canonical well-known location, which the default (`redmine`) discovery profile does not serve, so the flow stalls without it ([#188](https://github.com/jztan/redmine-mcp-server/issues/188)). See [Cursor and self-AS discovery](docs/oauth-setup.md#cursor-and-self-as-discovery).
  412. </details>
  413. <details>
  414. <summary><strong>Codex CLI</strong></summary>
  415. Add to Codex CLI using the command:
  416. ```bash
  417. codex mcp add redmine -- npx -y mcp-client-http http://127.0.0.1:8000/mcp
  418. ```
  419. Or configure manually in `~/.codex/config.toml`:
  420. ```toml
  421. [mcp_servers.redmine]
  422. command = "npx"
  423. args = ["-y", "mcp-client-http", "http://127.0.0.1:8000/mcp"]
  424. ```
  425. **Note:** Codex CLI primarily supports stdio-based MCP servers. The above uses `mcp-client-http` as a bridge for HTTP transport.
  426. </details>
  427. <details>
  428. <summary><strong>Kiro</strong></summary>
  429. Kiro primarily supports stdio-based MCP servers. For HTTP servers, use an HTTP-to-stdio bridge:
  430. 1. Create or edit `.kiro/settings/mcp.json` in your workspace:
  431. ```json
  432. {
  433. "mcpServers": {
  434. "redmine": {
  435. "command": "npx",
  436. "args": [
  437. "-y",
  438. "mcp-client-http",
  439. "http://127.0.0.1:8000/mcp"
  440. ],
  441. "disabled": false
  442. }
  443. }
  444. }
  445. ```
  446. 2. Save the file and restart Kiro. The Redmine tools will appear in the MCP panel.
  447. **Note:** Direct HTTP transport support in Kiro is limited. The above configuration uses `mcp-client-http` as a bridge to connect to HTTP MCP servers.
  448. </details>
  449. <details>
  450. <summary><strong>Generic MCP Clients</strong></summary>
  451. Most MCP clients use a standard configuration format. For HTTP servers:
  452. ```json
  453. {
  454. "mcpServers": {
  455. "redmine": {
  456. "type": "http",
  457. "url": "http://127.0.0.1:8000/mcp"
  458. }
  459. }
  460. }
  461. ```
  462. For clients that require a command-based approach with HTTP bridge:
  463. ```json
  464. {
  465. "mcpServers": {
  466. "redmine": {
  467. "command": "npx",
  468. "args": ["-y", "mcp-client-http", "http://127.0.0.1:8000/mcp"]
  469. }
  470. }
  471. }
  472. ```
  473. </details>
  474. ### stdio transport
  475. With `REDMINE_MCP_TRANSPORT=stdio` the client starts the server as its own process and talks to it over stdin/stdout. Nothing listens on a port, and the HTTP bridges above are not needed. This works in `legacy` mode only, since the other modes authenticate each HTTP request.
  476. Claude Code:
  477. ```bash
  478. claude mcp add redmine \
  479. -e REDMINE_URL=https://your-redmine-server.com \
  480. -e REDMINE_API_KEY=your_api_key \
  481. -e REDMINE_MCP_TRANSPORT=stdio \
  482. -e ATTACHMENTS_DIR=/absolute/path/to/redmine-attachments \
  483. -- uvx redmine-mcp-server
  484. ```
  485. Claude Desktop, Codex CLI, Kiro and other command-based clients:
  486. ```json
  487. {
  488. "mcpServers": {
  489. "redmine": {
  490. "command": "uvx",
  491. "args": ["redmine-mcp-server"],
  492. "env": {
  493. "REDMINE_URL": "https://your-redmine-server.com",
  494. "REDMINE_API_KEY": "your_api_key",
  495. "REDMINE_MCP_TRANSPORT": "stdio",
  496. "ATTACHMENTS_DIR": "/absolute/path/to/redmine-attachments"
  497. }
  498. }
  499. }
  500. }
  501. ```
  502. Without an HTTP server there are no URLs to hand out, so `get_redmine_attachment` returns a local `file_path` and `create_upload_ticket` declines; attach local files with `file_path` instead (allowed folders: `ATTACHMENTS_DIR` plus `REDMINE_MCP_UPLOAD_FILE_ROOTS`). Set `ATTACHMENTS_DIR` to an absolute path: the default `./attachments` is relative to the folder the client starts the server in, which is often the project you have open.
  503. ### Testing Your Setup
  504. ```bash
  505. # Test connection by checking health endpoint
  506. curl http://localhost:8000/health
  507. ```
  508. ## Supported Redmine Plugins
  509. The server works against a stock Redmine instance. Six optional plugins add
  510. more, shown as nine rows below because Products' orders, CRM's deals and
  511. Helpdesk's tickets carry their own flags. To
  512. use one, install it on your Redmine server and set the matching env var.
  513. Skipping a plugin costs you only that plugin's features.
  514. Plugin tools appear in the client's tool list only when their env var is set; with the flag off they are not registered on the MCP surface at all.
  515. | Plugin | Vendor | Env var | What it adds |
  516. |---|---|---|---|
  517. | [Agile](https://www.redmineup.com/pages/plugins/agile) | RedmineUP | `REDMINE_AGILE_ENABLED` | `get_redmine_issue` returns `story_points`, `agile_sprint_id`, `agile_position`; `update_redmine_issue` accepts `story_points` |
  518. | [Checklists](https://www.redmineup.com/pages/plugins/checklists) | RedmineUP (Pro) | `REDMINE_CHECKLISTS_ENABLED` | 3 tools: `get_checklist`, `create_checklist_item`, `update_checklist_item` |
  519. | [Products](https://www.redmineup.com/pages/plugins/products) | RedmineUP | `REDMINE_PRODUCTS_ENABLED` | 1 tool: `manage_product`; with `REDMINE_DEALS_ENABLED` also `add_deal_product` |
  520. | [Products orders](https://www.redmineup.com/pages/plugins/products) | RedmineUP | `REDMINE_ORDERS_ENABLED` | 1 tool: `manage_order` (read-only). Same plugin as Products, with its own flag because orders are a separate project module and the flag adds OAuth scopes |
  521. | [CRM](https://www.redmineup.com/pages/plugins/crm) | RedmineUP | `REDMINE_CRM_ENABLED` | 2 tools: `manage_contact`, `list_contact_tags`; plus the 2 shared CRM tools `manage_crm_note` and `list_crm_queries`, which either CRM flag enables (adds the `*_contacts` and note scopes to OAuth discovery when enabled) |
  522. | [CRM deals](https://www.redmineup.com/pages/plugins/crm) | RedmineUP (Pro) | `REDMINE_DEALS_ENABLED` | 3 tools: `manage_deal`, `list_deal_statuses`, `manage_deal_category`; plus the 2 shared CRM tools above, and `add_deal_product` when `REDMINE_PRODUCTS_ENABLED` is also set (adds the `*_deals` and note scopes to OAuth discovery when enabled). Same plugin as CRM, but the Light edition has no deals |
  523. | [DMSF](https://github.com/danmunn/redmine_dmsf) | danmunn (open source) | `REDMINE_DMSF_ENABLED` | 1 tool: `manage_document` |
  524. | [Helpdesk](https://www.redmineup.com/pages/plugins/helpdesk) | RedmineUP | `REDMINE_HELPDESK_ENABLED` | 1 tool: `send_helpdesk_email_reply` |
  525. | [Helpdesk tickets](https://www.redmineup.com/pages/plugins/helpdesk) | RedmineUP | `REDMINE_HELPDESK_TICKETS_ENABLED` | 1 tool: `manage_helpdesk_ticket`. Same plugin as Helpdesk, with its own flag because it adds OAuth scopes |
  526. | [Additional Tags](https://github.com/alphanodes/additional_tags) | AlphaNodes (open source) | `REDMINE_TAGS_ENABLED` | `get_redmine_issue` returns a `tags` array; `create_redmine_issue` / `update_redmine_issue` accept `tag_list` |
  527. Agile and Additional Tags add fields to tools you already have, so they
  528. register no new tools. The other eight bring their own, which appear in
  529. `tools/list` either way but return a feature-disabled error until you set the
  530. flag. Tags also needs the `view_issue_tags`, `create_issue_tags`, and
  531. `edit_issue_tags` permissions on the Redmine server.
  532. Tools for a Redmine plugin written in house can be added from a separate package without forking this server; see [Extensions](docs/extensions.md).
  533. ## Available Tools
  534. A deployment can expose a subset of these with `REDMINE_MCP_ALLOW_TOOLS`; everything else disappears from `tools/list` and is refused by `call_tool`.
  535. This MCP server provides 53 core tools for interacting with Redmine, plus 16 plugin tools that are listed only when the matching `REDMINE_*_ENABLED` flag is set (69 in total), and 1 operator tool exposed by `REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true` (maximum of 70). A client connected to a vanilla Redmine sees just the 53 core tools. For full documentation of every tool, see the [Tool Reference](./docs/tool-reference.md).
  536. **Core tools (53, always available):** Project Management (10), Issue Operations (13), Time Tracking (4), Discovery / Enumeration (7), Search & Wiki (2), News (4), File Operations (5), Gantt (1), Interactive Apps (6), Meta (1).
  537. **Plugin-gated tools (16, listed only when their flag is set):** Checklists (3), Products (1), Products orders (1), Contacts / CRM (2), Deals / CRM (3), shared CRM notes and saved queries (2, either CRM flag), deal product lines (1, deals plus products), Documents / DMSF (1), Helpdesk (1), Helpdesk tickets (1). Each requires the matching Redmine plugin installed **and** its env flag set; with the flag off the tools are not registered on the MCP surface.
  538. **Operator tools (1, admin-gated):** `cleanup_attachment_files`, registered only when `REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true`.
  539. <details>
  540. <summary><strong>Full tool list with descriptions</strong></summary>
  541. ### Core tools (53, always available)
  542. These tools require only a Redmine instance and credentials, with no extra plugins or feature flags.
  543. - **Project Management** (10 tools)
  544. - [`list_redmine_projects`](docs/tool-reference.md#list_redmine_projects) - List accessible projects (active only unless `filters` asks for more), narrowed server-side and optionally paginated
  545. - [`list_project_issue_custom_fields`](docs/tool-reference.md#list_project_issue_custom_fields) - List issue custom fields configured for a project
  546. - [`list_redmine_versions`](docs/tool-reference.md#list_redmine_versions) - List versions/milestones for a project
  547. - [`manage_redmine_version`](docs/tool-reference.md#manage_redmine_version) - Create, update, or delete a version/milestone
  548. - [`manage_redmine_project`](docs/tool-reference.md#manage_redmine_project) - Create a project, edit its settings, or close and reopen it
  549. - [`list_project_members`](docs/tool-reference.md#list_project_members) - List members and roles of a project
  550. - [`summarize_project_status`](docs/tool-reference.md#summarize_project_status) - Get comprehensive project status summary
  551. - [`list_redmine_roles`](docs/tool-reference.md#list_redmine_roles) - List all roles defined in the Redmine instance (for discovering valid `role_ids`)
  552. - [`get_project_modules`](docs/tool-reference.md#get_project_modules) - Retrieve the enabled modules for a project
  553. - [`manage_project_member`](docs/tool-reference.md#manage_project_member) - Add, update, or remove a project membership
  554. - **Issue Operations** (13 tools)
  555. - [`get_redmine_issue`](docs/tool-reference.md#get_redmine_issue) - Retrieve detailed issue information (supports journal pagination, watchers, relations, children)
  556. - [`list_redmine_issues`](docs/tool-reference.md#list_redmine_issues) - List issues with flexible filtering (project, status, assignee, etc.)
  557. - [`search_redmine_issues`](docs/tool-reference.md#search_redmine_issues) - Search issues by text query
  558. - [`create_redmine_issue`](docs/tool-reference.md#create_redmine_issue) - Create new issues, with optional file attachments via the `uploads` parameter
  559. - [`update_redmine_issue`](docs/tool-reference.md#update_redmine_issue) - Update existing issues, with optional file attachments via the `uploads` parameter (combine with `notes` to attach files to a journal note)
  560. - [`delete_redmine_issue`](docs/tool-reference.md#delete_redmine_issue) - Hard-delete an issue with required confirmation flags and a cascade-impact preview before irreversible deletion.
  561. - [`copy_issue`](docs/tool-reference.md#copy_issue) - Duplicate an existing issue with optional field overrides
  562. - [`list_subtasks`](docs/tool-reference.md#list_subtasks) - List subtasks (child issues) of a given parent
  563. - [`get_private_notes`](docs/tool-reference.md#get_private_notes) - Retrieve private notes on an issue
  564. - [`manage_issue_relation`](docs/tool-reference.md#manage_issue_relation) - List, create, or delete issue relations
  565. - [`manage_issue_watcher`](docs/tool-reference.md#manage_issue_watcher) - Add or remove a watcher on an issue
  566. - [`manage_issue_note`](docs/tool-reference.md#manage_issue_note) - Edit a journal note's text or toggle its privacy
  567. - [`manage_issue_category`](docs/tool-reference.md#manage_issue_category) - List, create, update, or delete issue categories
  568. - Note: `get_redmine_issue` can include `custom_fields` and `update_redmine_issue` can update custom fields by name (for example `{"size": "S"}`).
  569. - **Time Tracking** (4 tools)
  570. - [`list_time_entries`](docs/tool-reference.md#list_time_entries) - List time entries with filtering by project, issue, user, and date range
  571. - [`manage_time_entry`](docs/tool-reference.md#manage_time_entry) - Create or update a time entry (use `user_id` to log on behalf of another user)
  572. - [`list_time_entry_activities`](docs/tool-reference.md#list_time_entry_activities) - Discover available activity types for time entries
  573. - [`import_time_entries`](docs/tool-reference.md#import_time_entries) - Bulk import time entries via sequential API calls with per-entry error reporting
  574. - **Discovery / Enumeration** (7 tools): help LLMs find valid IDs before calling create/update tools
  575. - [`list_redmine_trackers`](docs/tool-reference.md#list_redmine_trackers) - List all trackers (Bug, Feature, Support, etc.)
  576. - [`list_project_trackers`](docs/tool-reference.md#list_project_trackers) - List the trackers enabled for a specific project
  577. - [`list_redmine_issue_statuses`](docs/tool-reference.md#list_redmine_issue_statuses) - List all issue statuses with their `is_closed` flag
  578. - [`list_redmine_issue_priorities`](docs/tool-reference.md#list_redmine_issue_priorities) - List all priority levels
  579. - [`list_redmine_users`](docs/tool-reference.md#list_redmine_users) - Filter/list users (admin-only; supports name and group filters)
  580. - [`get_current_user`](docs/tool-reference.md#get_current_user) - Get the authenticated user's profile (works for non-admins)
  581. - [`list_redmine_queries`](docs/tool-reference.md#list_redmine_queries) - List saved custom queries (read-only)
  582. - **Search & Wiki** (2 tools)
  583. - [`search_entire_redmine`](docs/tool-reference.md#search_entire_redmine) - Global search across issues and wiki pages (Redmine 3.3.0+)
  584. - [`manage_redmine_wiki_page`](docs/tool-reference.md#manage_redmine_wiki_page) - List, get, create, update, delete, or rename wiki pages
  585. - **News** (4 tools): project announcements -- release notes, maintenance windows
  586. - [`list_redmine_news`](docs/tool-reference.md#list_redmine_news) - List news, optionally for one project
  587. - [`get_redmine_news`](docs/tool-reference.md#get_redmine_news) - Read one news item with its comments and attachments
  588. - [`manage_redmine_news`](docs/tool-reference.md#manage_redmine_news) - Create or update a news item (Redmine 4.1+)
  589. - [`delete_redmine_news`](docs/tool-reference.md#delete_redmine_news) - Delete a news item, with confirmation (Redmine 4.1+)
  590. - **File Operations** (5 tools)
  591. - [`list_files`](docs/tool-reference.md#list_files) - List files uploaded to a project's Files section
  592. - [`create_upload_ticket`](docs/tool-reference.md#create_upload_ticket) - Reserve an upload slot and return a single-use URL, so a file on the caller's machine reaches the server without its bytes passing through the model
  593. - [`upload_file`](docs/tool-reference.md#upload_file) - Upload a new file to a project (from a staged `upload_id`, a URL, base64 content, or a server-side `file_path`), optionally tied to a version
  594. - [`delete_file`](docs/tool-reference.md#delete_file) - Delete a file from a project
  595. - [`get_redmine_attachment`](docs/tool-reference.md#get_redmine_attachment) - Download an attachment (works in both HTTP and stdio mode)
  596. - **Gantt** (1 tool)
  597. - [`get_gantt_chart`](docs/tool-reference.md#get_gantt_chart) - Retrieve project timeline data: issues with dates, dependencies, and milestones
  598. - **Interactive Apps** (4 tools): render live UI in the chat via the [MCP Apps extension](https://github.com/modelcontextprotocol/ext-apps) (requires a client that supports it)
  599. - [`show_triage_board`](docs/tool-reference.md#show_triage_board) - Render a project's issues as an interactive Kanban board grouped by status, with drag-to-change-status write-back
  600. - [`get_triage_board_data`](docs/tool-reference.md#get_triage_board_data) - Board data source backing the board's Refresh action
  601. - [`show_project_dashboard`](docs/tool-reference.md#show_project_dashboard) - Render a live project snapshot (open/closed, overdue, due this week, open-by-priority, recent activity) as an interactive dashboard, with click-through drill-ins to matching issue lists
  602. - [`get_project_dashboard_data`](docs/tool-reference.md#get_project_dashboard_data) - App-only data source backing the dashboard's Refresh action
  603. - [`show_project_timeline`](docs/tool-reference.md#show_project_timeline) - Render a project's schedule as an interactive timeline: issue bars by version, milestone diamonds, and a Today line
  604. - [`get_project_timeline_data`](docs/tool-reference.md#get_project_timeline_data) - App-only data source backing the timeline's Refresh action
  605. - **Meta** (1 tool)
  606. - [`get_mcp_server_info`](docs/tool-reference.md#get_mcp_server_info) - Report server version, auth mode, read-only state, the authenticated user (`current_user`), and which plugin-gated tool families are enabled. Use to detect deployment lag before relying on a recently-shipped fix, or to confirm who `assigned_to_id="me"` resolves to.
  607. ### Plugin-gated tools (16, opt in via env var)
  608. These tools require a corresponding Redmine plugin installed on the server **and** the matching environment variable set to `true` on the MCP server. They are listed in `tools/list` only when their flag is set; with the flag off they are not registered on the MCP surface (and a direct call still returns a feature-disabled error).
  609. - **Checklists** (3 tools): set `REDMINE_CHECKLISTS_ENABLED=true`; requires the [RedmineUP Checklists Pro plugin](https://www.redmineup.com/pages/plugins/checklists)
  610. - [`get_checklist`](docs/tool-reference.md#get_checklist) - Retrieve all checklist items for an issue
  611. - [`create_checklist_item`](docs/tool-reference.md#create_checklist_item) - Add a new checklist item to an issue
  612. - [`update_checklist_item`](docs/tool-reference.md#update_checklist_item) - Update a checklist item's text, done state, or position
  613. - **Products** (1 tool): set `REDMINE_PRODUCTS_ENABLED=true`; requires the [RedmineUP Products plugin](https://www.redmineup.com/pages/plugins/products)
  614. - [`manage_product`](docs/tool-reference.md#manage_product) - List, get, create, or update products
  615. - **Products orders** (1 tool): set `REDMINE_ORDERS_ENABLED=true`; requires the [RedmineUP Products plugin](https://www.redmineup.com/pages/plugins/products) and its `orders` project module. In OAuth mode the flag also adds `view_orders` and `view_orders_list` to the advertised scopes, so grant them on the OAuth application
  616. - [`manage_order`](docs/tool-reference.md#manage_order) - List or read orders, with their product lines, comments and attachments (read-only)
  617. - **Contacts (CRM)** (2 tools): set `REDMINE_CRM_ENABLED=true`; requires the [RedmineUP CRM plugin](https://www.redmineup.com/pages/plugins/crm). In OAuth mode the flag also adds the CRM permissions to the advertised scopes, so grant them on the OAuth application and have users re-consent. Set `REDMINE_CRM_EDITION=pro` on a Pro install to allow the contact `list` filters the Light build does not register
  618. - [`manage_contact`](docs/tool-reference.md#manage_contact) - List, get, create, update, delete, or assign/remove project association for contacts
  619. - [`list_contact_tags`](docs/tool-reference.md#list_contact_tags) - Tags in use on contacts, with colors, for the `tags` filter and `tag_list`
  620. - **Deals (CRM)** (3 tools): set `REDMINE_DEALS_ENABLED=true`; requires the **Pro** edition of the same CRM plugin, and the `deals` project module enabled on the project. Deals have their own flag because the Light edition defines none of the deal permissions, so advertising them would break consent for Light deployments
  621. - [`manage_deal`](docs/tool-reference.md#manage_deal) - List, get, create, update, or delete deals
  622. - [`list_deal_statuses`](docs/tool-reference.md#list_deal_statuses) - Deal statuses (admin-only on the plugin side) and a project's deal categories, for use before creating a deal
  623. - [`manage_deal_category`](docs/tool-reference.md#manage_deal_category) - List, create, rename, or delete a project's deal categories
  624. - **CRM notes and saved queries** (2 tools, shared): available when either `REDMINE_CRM_ENABLED` or `REDMINE_DEALS_ENABLED` is set; each call is gated on the flag matching the note's or query's source. On CRM PRO 4.5.1 and later, OAuth deployments also need `REDMINE_CRM_NOTE_EDIT_SCOPES=true` to edit notes
  625. - [`manage_crm_note`](docs/tool-reference.md#manage_crm_note) - Get, create, update, or delete CRM notes on contacts and deals
  626. - [`list_crm_queries`](docs/tool-reference.md#list_crm_queries) - Saved contact or deal queries
  627. - **Deal product lines** (1 tool): needs both `REDMINE_DEALS_ENABLED=true` and `REDMINE_PRODUCTS_ENABLED=true`; the endpoint exists only when the Products plugin is installed next to CRM
  628. - [`add_deal_product`](docs/tool-reference.md#add_deal_product) - Add a catalogue or free-form product line to a deal
  629. - **Documents (DMSF)** (1 tool): set `REDMINE_DMSF_ENABLED=true`; requires the [`redmine_dmsf` plugin](https://github.com/danmunn/redmine_dmsf)
  630. - [`manage_document`](docs/tool-reference.md#manage_document) - List, get, create (upload), or update (new revision) DMSF documents
  631. - **Helpdesk** (1 tool): set `REDMINE_HELPDESK_ENABLED=true`; requires the [RedmineUP Helpdesk plugin](https://www.redmineup.com/pages/plugins/helpdesk)
  632. - [`send_helpdesk_email_reply`](docs/tool-reference.md#send_helpdesk_email_reply) - Email a reply to a Helpdesk ticket's customer, optionally changing the ticket status
  633. - **Helpdesk tickets** (1 tool): set `REDMINE_HELPDESK_TICKETS_ENABLED=true`; requires the [RedmineUP Helpdesk plugin](https://www.redmineup.com/pages/plugins/helpdesk) and the RedmineUP CRM plugin
  634. - [`manage_helpdesk_ticket`](docs/tool-reference.md#manage_helpdesk_ticket) - Read a ticket's Helpdesk data, open a ticket for an existing contact, or move a ticket to another contact
  635. ### Operator tools (1, admin-gated)
  636. Hidden from `tools/list` by default. Set `REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true` to register them on the MCP surface. The underlying background tasks run regardless of this flag; exposing them only adds the option to drive them through MCP.
  637. - [`cleanup_attachment_files`](docs/tool-reference.md#cleanup_attachment_files) - Manually trigger cleanup of expired attachment files (the background cleanup task runs automatically regardless)
  638. </details>
  639. ## Docker Deployment
  640. ### Quick Start with Docker
  641. ```bash
  642. # Configure environment
  643. cp .env.docker.example .env.docker
  644. # Edit .env.docker with your Redmine settings
  645. # Run with docker-compose
  646. docker-compose up --build
  647. # Or run directly
  648. docker build -t redmine-mcp-server .
  649. docker run -p 8000:8000 --env-file .env.docker redmine-mcp-server
  650. ```
  651. ### Use the Published Image
  652. Prebuilt multi-architecture images (`linux/amd64`, `linux/arm64`) are published to
  653. the GitHub Container Registry on each release, so you can run the server without
  654. building it yourself:
  655. ```bash
  656. docker pull ghcr.io/jztan/redmine-mcp-server:latest
  657. docker run -p 8000:8000 --env-file .env.docker ghcr.io/jztan/redmine-mcp-server:latest
  658. ```
  659. Pin to an exact version (e.g. `ghcr.io/jztan/redmine-mcp-server:2.2.0`) or track a
  660. minor series (e.g. `:2.2`). Published images are available starting from the next
  661. release.
  662. ### Production Deployment
  663. Use the automated deployment script:
  664. ```bash
  665. chmod +x deploy.sh
  666. ./deploy.sh
  667. ```
  668. ## Troubleshooting
  669. If you run into any issues, checkout our [troubleshooting guide](./docs/troubleshooting.md).
  670. ## Roadmap
  671. See the [roadmap](docs/roadmap.md) for planned features and future development.
  672. ## Contributing
  673. Contributions are welcome! Please see our [contributing guide](./docs/contributing.md) for details.
  674. ## Contributors
  675. Thank you to everyone who has helped improve this project through code, reviews, testing, and feature requests:
  676. <!-- contributors:start -->
  677. [@sebastianelsner](https://github.com/sebastianelsner) · [@mihajlovicjj](https://github.com/mihajlovicjj) · [@timcomport](https://github.com/timcomport) · [@aadnehovda](https://github.com/aadnehovda) · [@Vitexus](https://github.com/Vitexus) · [@Bricklou](https://github.com/Bricklou) · [@martindglaser](https://github.com/martindglaser) · [@LaurensRietveld](https://github.com/LaurensRietveld) · [@pdostal](https://github.com/pdostal) · [@stevehollis-orderflow](https://github.com/stevehollis-orderflow) · [@knasiotis](https://github.com/knasiotis) · [@azelcs](https://github.com/azelcs) · [@fionnb](https://github.com/fionnb) · [@goizper](https://github.com/goizper) · [@mmahmed](https://github.com/mmahmed) · [@andilem](https://github.com/andilem) · [@gino8080](https://github.com/gino8080) · [@siva01c](https://github.com/siva01c) · [@chesterXalan](https://github.com/chesterXalan) · [@mliebischer](https://github.com/mliebischer) · [@slidonnici](https://github.com/slidonnici) · [@mival](https://github.com/mival)
  678. <!-- contributors:end -->
  679. <a href="https://github.com/jztan/redmine-mcp-server/graphs/contributors">
  680. <img src="https://contrib.rocks/image?repo=jztan/redmine-mcp-server" alt="Contributors" />
  681. </a>
  682. Per-release contributor credits are listed in the [Changelog](./CHANGELOG.md).
  683. Thanks also to [RedmineUP](https://www.redmineup.com) for providing evaluation copies of CRM PRO and Helpdesk PRO, which let the CRM and Helpdesk tools be verified against real Pro instances.
  684. ## License
  685. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  686. ## Blog posts
  687. **The story behind the releases.** Building this server keeps surprising me: full API access that turned out to be a mistake, 69 tools that had to become 43, an OAuth scope bug that only surfaced when a contributor ran the flow against a real Redmine 6 instance. Plenty of the sharpest lessons arrived from other people's deployments rather than mine. I write about that thinking in [The Dispatch](https://blog.jztan.com/newsletter/?utm_source=github&utm_medium=referral&utm_campaign=redmine-mcp-server). Come along if that's your kind of thing.
  688. Background, design notes, and postmortems from building this server:
  689. **Getting started**
  690. - [Redmine MCP Server: Give AI Agents Live Project Data](https://blog.jztan.com/redmine-mcp-server-for-ai-agents/?utm_source=github&utm_medium=referral&utm_campaign=redmine-mcp-server): What the server does, why the tool surface is curated rather than a full API mirror, and how to choose a Redmine MCP server
  691. - [How I linked a legacy system to a modern AI agent with MCP](https://blog.jztan.com/how-i-linked-a-legacy-system-to-a-modern-ai-agent/?utm_source=github&utm_medium=referral&utm_campaign=redmine-mcp-server): The problem that started this project, and the first two read-only tools
  692. **Tool design & architecture**
  693. - [Designing Reliable MCP Servers: 3 Hard Lessons in Agentic Architecture](https://blog.jztan.com/i-gave-my-ai-agent-full-api-access-it-was-a-mistak/?utm_source=github&utm_medium=referral&utm_campaign=redmine-mcp-server): Why full API access to an agent was a mistake, and what replaced it
  694. - [MCP Tool Sprawl: How I Cut 69 Tools to 43 With a Decorator](https://blog.jztan.com/mcp-tool-sprawl-consolidation/?utm_source=github&utm_medium=referral&utm_campaign=redmine-mcp-server): The v2 consolidation that cut context overhead and sharpened agent tool selection
  695. **Production**
  696. - [MCP File Upload: Why Base64 Tool Arguments Can Corrupt Files](https://blog.jztan.com/mcp-file-upload-base64-corruption/?utm_source=github&utm_medium=referral&utm_campaign=redmine-mcp-server): Why a 3 KB PNG silently lost 32 characters when the model retyped its base64, and the side-channel upload with SHA-256 checks that replaced it
  697. - [How to Evaluate an MCP Server With an LLM: 17 Bugs Found and Fixed](https://blog.jztan.com/evaluate-mcp-server-with-llm/?utm_source=github&utm_medium=referral&utm_campaign=redmine-mcp-server): Driving the server with an agent surfaced 17 problems the test suite missed, including a `role_ids=[True]` bug that quietly assigned an elevated role
  698. - [What It Actually Takes to Ship a Production MCP Server for Redmine](https://blog.jztan.com/what-it-actually-takes-to-ship-a-production-mcp-server-for-redmine/?utm_source=github&utm_medium=referral&utm_campaign=redmine-mcp-server): The full journey from prototype to production

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.