Redmine

A Model Context Protocol server that runs inside Redmine as a plugin, so an AI client can read and write Redmine through Redmine's own authentication and permission system. There is no second service to deploy: no extra port, no container, no separate process to supervise.

The endpoint is a single path, POST /mcp. GET and DELETE are routed as well, so clients built for the older session-based transport get a clean response instead of a routing error.

Protocol¶

Three revisions are served, newest first: 2026-07-28, 2025-11-25 and 2025-06-18. The newest is implemented natively, which suits a Rails controller well, because it dropped the initialize handshake and the session id entirely and every request is self-describing. The handshake methods are kept for the two older revisions, since that is what shipped clients still speak.

Tools¶

Eleven, nine read and two write:

Tool	Does
whoami	Which Redmine user this connection is authenticated as
list_projects	Projects visible to that user
get_project	One project, with its enabled modules and trackers
search_issues	Search issues, all filters optional
get_issue	One issue, with description and optionally notes and history
list_wiki_pages	Titles of a project's readable wiki pages
get_wiki_page	Text of one wiki page
list_enumerations	Trackers, statuses and priorities
list_users	Search visible users by name or login
create_issue	Create an issue
add_issue_note	Append a note to an issue

Permissions are Redmine's, not the plugin's¶

Every tool declares the core permission it needs and checks User#allowed_to? before running, as well as reading through Redmine's .visible scopes. Both matter: Redmine's .visible scopes honour a user's roles but do not narrow by OAuth2 token scope, so a scope check alone or a scope-free .visible query alone would each be wrong.

tools/list varies by the credential presented, so a scope-narrowed token is never shown a tool it could not call. The plugin defines no permissions of its own.

Authentication¶

Four modes, each switchable independently in Administration -> Plugins. Every one of them is a path core already uses; the plugin invents no credential format and no token store.

• OAuth2 via Redmine's own provider. The recommended mode: per user, per scope, and revocable from Administration -> Applications. On by default.
• API key, the X-Redmine-API-Key header. Per user, but carries that user's full permissions with no scope narrowing. On by default.
• HTTP Basic. Off by default, because it sends reusable credentials on every request.
• Browser session cookie. Off by default, and Origin-checked when on, because it is the only mode carrying ambient browser credentials and therefore the only one exposed to cross-site request forgery. Clients that send no Origin header at all, which is every non-browser MCP client, are unaffected.

Safe by default¶

• The endpoint is off until an administrator turns it on. Installing the plugin does not open anything.
• Read-only is on by default, which refuses both write tools.
• A configurable cap limits how many rows any single call may return.

Requirements¶

Redmine 6.1.0 or later. 6.1 is the floor because that is where Redmine gained its OAuth2 provider and the token-scope narrowing in User#allowed_to? that this plugin is built around. Developed and run against Redmine 7.0.

Clone into plugins/ and restart Redmine:

cd {REDMINE_ROOT}/plugins
git clone https://github.com/joaoperfig/redmine_mcp_plugin.git

There are no migrations and no assets, so neither redmine:plugins:migrate nor assets:precompile is needed. To uninstall, delete the directory and restart.

Then switch it on¶

Nothing is exposed until you do this.

1. Administration -> Plugins -> Redmine MCP Server -> Configure.
2. Tick Enabled.
3. Leave Read only ticked until you have decided you want writes.
4. Choose the authentication modes you want. At least one must be on.

The REST API must be enabled¶

OAuth2, API key and HTTP Basic all authenticate the way core's API does, so they need Administration -> Settings -> API -> Enable REST web service. Without it those three modes are refused and the plugin says so, rather than failing as anonymous. Session mode does not need it.

For OAuth2, the recommended mode¶

Register the client under Administration -> Applications. Scopes are Redmine permission names, so a token can be narrowed to exactly the permissions a given client should have, and revoked from the same screen.

Point the client at it¶

The endpoint is the single path /mcp on your Redmine, for example https://redmine.example.com/mcp. Serve it over HTTPS: every authentication mode sends a credential on every request.

If a client runs in a browser and you have enabled session mode, add its origin under Allowed origins. The Redmine host itself is always allowed.