Skip to content
Back to search

mcp_redmine

MCP server inside Redmine: AI assistants (Claude, ChatGPT, Copilot) use the whole REST API through OAuth (Redmine 6.1 provider + dynamic client registration), with each user's own permissions. No separate server.

Safety scan

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

Checked today
Badge for your README
findsafeskills safety rating

Markdown

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

HTML

<a href="/listings/gabera--mcp-redmine"><img src="/api/listings/gabera--mcp-redmine/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.

cd /path/to/redmine/plugins
git clone https://github.com/gabera/mcp_redmine.git
# restart Redmine

The directory must be named `mcp_redmine`. The plugin has no migrations and no extra gems.

To update, run `git pull` in the plugin directory and restart Redmine.

Then, in *Administration → Plugins → MCP Redmine → Configure*, set:

| Option | Description | |---|---| | Enable MCP endpoint | Turns on `/mcp`, the OAuth metadata and client registration. Off by default | | Response format | `yaml` (default) or `json` | | Instructions for the model | Guidance such as "use Textile", project ids and required fields. Sent as the MCP server `instructions`, which clients put in the system prompt, and appended to the description of the `redmine_request` and `redmine_write` tools |

The instructions guide the model but do not bind it. Do not rely on them for rules that must hold, such as asking before changing data: use the client's permissions for that (see [Tools](#tools)).

Changes to the instructions take effect without restarting Redmine or disconnecting anyone: - The server `instructions` are read on connect, so they apply to new sessions. - In open sessions, the tool descriptions are updated: the client receives `notifications/tools/list_changed` with the response to its next call. - Claude Desktop ignores that notification and only picks up the new text when it reconnects.

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 · 163 lines
  1. # MCP Redmine
  2. English | [Português](README.pt-BR.md)
  3. A Redmine plugin that runs an [MCP](https://modelcontextprotocol.io) server inside Redmine itself, at `/mcp`. AI
  4. assistants (Claude, Copilot, ChatGPT, etc.) can then use **the whole Redmine REST API** on behalf of each user. For
  5. example, the assistant can:
  6. - search and read projects and issues;
  7. - create and update issues, notes and statuses;
  8. - log time;
  9. - reach the rest of the API.
  10. There is no separate server. Calls run inside Redmine, with the permissions of the user who connected.
  11. ## Requirements
  12. - Redmine 6.1 or later, which ships the built-in OAuth2 provider. Tested on 6.1 and 7.0.
  13. - REST API enabled in *Administration → Settings → API*.
  14. - Redmine at the root of its host (e.g. `https://redmine.example.com`). MCP clients look for the OAuth metadata at
  15. `/.well-known/...` on the host root.
  16. ## Installation
  17. ```bash
  18. cd /path/to/redmine/plugins
  19. git clone https://github.com/gabera/mcp_redmine.git
  20. # restart Redmine
  21. ```
  22. The directory must be named `mcp_redmine`. The plugin has no migrations and no extra gems.
  23. To update, run `git pull` in the plugin directory and restart Redmine.
  24. Then, in *Administration → Plugins → MCP Redmine → Configure*, set:
  25. | Option | Description |
  26. |---|---|
  27. | Enable MCP endpoint | Turns on `/mcp`, the OAuth metadata and client registration. Off by default |
  28. | Response format | `yaml` (default) or `json` |
  29. | Instructions for the model | Guidance such as "use Textile", project ids and required fields. Sent as the MCP server `instructions`, which clients put in the system prompt, and appended to the description of the `redmine_request` and `redmine_write` tools |
  30. The instructions guide the model but do not bind it. Do not rely on them for rules that must hold, such as asking
  31. before changing data: use the client's permissions for that (see [Tools](#tools)).
  32. Changes to the instructions take effect without restarting Redmine or disconnecting anyone:
  33. - The server `instructions` are read on connect, so they apply to new sessions.
  34. - In open sessions, the tool descriptions are updated: the client receives `notifications/tools/list_changed` with
  35. the response to its next call.
  36. - Claude Desktop ignores that notification and only picks up the new text when it reconnects.
  37. ## Connecting clients
  38. All clients only need the URL `https://<your-redmine>/mcp`. On the first connection, the browser opens the Redmine
  39. login and the application authorization page.
  40. - **Claude Code:**
  41. ```bash
  42. claude mcp add --transport http redmine https://<your-redmine>/mcp
  43. ```
  44. Then run `/mcp`, choose `redmine` and click *Authenticate*.
  45. - **Claude Desktop / claude.ai:** *Settings → Connectors → Add custom connector*, with the URL.
  46. - **GitHub Copilot (VS Code):** run *MCP: Open User Configuration* and add
  47. `{ "servers": { "redmine": { "type": "http", "url": "https://<your-redmine>/mcp" } } }`.
  48. - **Without OAuth:** you can also send your personal API key in the `X-Redmine-API-Key` header.
  49. ## How authentication works
  50. The plugin uses Redmine's own OAuth2 provider (Doorkeeper) and adds what MCP clients need:
  51. 1. The client calls `/mcp` and gets `401` with the address of `/.well-known/oauth-protected-resource`.
  52. 2. At `/.well-known/oauth-authorization-server`, the client finds `/oauth/authorize`, `/oauth/token` and
  53. `/mcp/register`.
  54. 3. The client registers itself (dynamic client registration, public client with PKCE). The application shows up in
  55. *Administration → Applications* as `MCP: <client name> (<redirect host>)`, e.g. `MCP: Claude Code (localhost)`.
  56. 4. The user logs in to Redmine and authorizes the application. The token lasts 2 hours and is renewed with the
  57. refresh token. Users can revoke access in *My account → Authorized applications*.
  58. The token gets every Redmine permission as its scope. Even so, the result never goes beyond what the user can do:
  59. Redmine applies the permissions of each user's roles on every call.
  60. **Security.** Anyone can register a client, as MCP requires, so a malicious link could ask a user to authorize an
  61. application that sends the token elsewhere. Two things limit this:
  62. - The consent page shows the host the token goes to, in the application name. Users should only authorize
  63. applications whose host they recognize (`localhost`, `claude.ai`, etc.).
  64. - OAuth tokens never get the `admin` scope, so an administrator who authorizes a client does not hand over admin
  65. rights. Admin-only API calls (creating users, groups, roles, etc.) are not available through OAuth: for them, use
  66. the `X-Redmine-API-Key` header.
  67. Administrators can review and delete the registered applications in *Administration → Applications*.
  68. ## Tools
  69. - **`redmine_request`**: reads from the Redmine API (GET). Marked as read-only.
  70. - Parameters: `path` (e.g. `/issues.json`) and `params` (query string).
  71. - **`redmine_write`**: creates, updates or deletes through the Redmine API. Marked as a write.
  72. - Parameters: `path` (e.g. `/issues/123.json`), `method` (`post`, `put`, `patch` or `delete`), `data` (body)
  73. and `params` (query string).
  74. - **`redmine_download`**: gets an attachment. Marked as read-only.
  75. - Parameter: `attachment_id`.
  76. - Returns the name, type, size, description and the Redmine link of the attachment, so the user can download it in
  77. the browser (logged in).
  78. - Text files up to 1 MB also come with their content, and images up to 5 MB come as an image, so the assistant can
  79. read them. Other types (PDF, zip, etc.) come with the data and the link only.
  80. - **`redmine_upload`**: uploads a file and returns the `token` to attach it. Marked as a write.
  81. - Parameters: `filename`, `file_content`, `encoding` (`text`, the default, or `base64`), `content_type` and
  82. `description`.
  83. - Redmine's limits apply: maximum size and allowed extensions.
  84. - **`redmine_paths_list`**: lists the paths of the Redmine OpenAPI specification.
  85. - **`redmine_paths_info`**: returns the full specification of the given paths (e.g. `["/issues.json"]`).
  86. `redmine_request` and `redmine_write` return `status_code`, `body` and `error`, and only accept API paths ending in
  87. `.json`.
  88. **Attaching files.** Uploading takes two steps, as in the Redmine API:
  89. 1. `redmine_upload` sends the content and returns a `token`.
  90. 2. `redmine_write` attaches the file with `uploads`, for example `PUT /issues/123.json` with
  91. `{"issue": {"uploads": [{"token": "...", "filename": "report.md"}]}}`. The same `uploads` works for wiki pages,
  92. project files, documents, etc.
  93. Files uploaded but never attached stay in Redmine until its prune task removes them (unattached for over a day).
  94. Redmine does not schedule it, so add a daily cron job:
  95. `bundle exec rake redmine:attachments:prune RAILS_ENV=production`.
  96. The content goes inside the tool call, so the assistant can only upload what it generates or can rewrite itself:
  97. text, markdown, csv, code. Binary files on the user's computer (PDF, screenshots, zip) must be attached through the
  98. Redmine web UI, because the plugin runs in Redmine and cannot reach the user's disk.
  99. **Confirmation before changing data.** Reads and writes are separate tools so the client can ask for approval
  100. before every write. In Claude Desktop and claude.ai:
  101. 1. Open *Settings → Connectors* and choose Redmine.
  102. 2. Set the read tools to *Always allow* and `redmine_write` to *Always ask*.
  103. Every write then shows the call, with its data, for the user to approve. This holds even if the model ignores the
  104. instructions.
  105. Example prompts:
  106. - "List the open high-priority issues in project X that have no assignee."
  107. - "Move issue #123 to *In Progress* and add the note: 'Started, due Friday'."
  108. - "Log 3.5 hours on issue #456 today, activity 'Development'."
  109. ## Local development
  110. `docker-compose.yml` starts Redmine 6.1.5 with PostgreSQL and this repository mounted as a plugin:
  111. ```bash
  112. docker compose up -d # http://localhost:3000, login admin/admin
  113. ```
  114. 1. Enable the REST API and the plugin.
  115. 2. Connect the client to `http://localhost:3000/mcp`. `http://localhost` redirect URIs are accepted.
  116. 3. The container runs in production mode and does not reload code: after editing the plugin, run
  117. `docker compose restart redmine`.
  118. ## License and credits
  119. Distributed under the [Apache License 2.0](LICENSE).
  120. Based on [mcp-redmine](https://github.com/runekaagaard/mcp-redmine) by Rune Kaagaard, an MCP server written in
  121. Python. The OpenAPI specification in `config/redmine-openapi.yml` comes from
  122. [d-yoshi/redmine-openapi](https://github.com/d-yoshi/redmine-openapi) (MIT), with descriptions revised for language
  123. models.

Ratings and comments

Sign in to rate this skill.

Sign in

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