Redmine MCP server for Cursor

A small Model Context Protocol (MCP) server that talks to your Redmine instance over its REST API. After you wire it into Cursor, the Agent can list/create/update issues, query projects, log time, and call any documented Redmine endpoint via a generic tool.

This repo runs over stdio (standard MCP transport): Cursor starts node index.js and exchanges JSON-RPC over stdin/stdout. You do not need to expose an HTTP port.

Prerequisites

• Node.js 18+ (includes fetch)

• A Redmine account with an API access key

  • In Redmine: My account → API access key (or your admin’s equivalent)

• Permission to use Redmine’s REST API for the actions you care about (varies by role/project)

Quick setup (for anyone cloning this repo)

1. Install dependencies

cd /path/to/this-repo
npm install

2. Configure environment variables

Create a .env file in the same directory as index.js (the repo root). Do not commit .env to git.

RedmineURL=https://your-redmine.example.com
RedmineAPIKEY=your_api_key_here

Rules:

• RedmineURL — Base URL only, no trailing slash, e.g. https://redmine.company.com

• RedmineAPIKEY — Your personal API key (treat it like a password)

Optional check from the shell (does not print your key):

node -e "require('dotenv').config(); console.log(process.env.RedmineURL ? 'RedmineURL OK' : 'missing RedmineURL')"

3. Smoke test (optional)

The MCP entrypoint is meant to be launched by Cursor. If you run it manually it will wait on stdio:

npm start

You should see no errors on startup if .env is valid. Stop with Ctrl+C.

Connecting Cursor

Option A — Project-only MCP (recommended for teams)

Check in .cursor/mcp.json at the repo root so everyone who opens this project gets the same server definition.

This repo’s .cursor/mcp.json uses ${workspaceFolder} so paths work for any clone location:

{
  "mcpServers": {
    "redmine-all-in-one": {
      "command": "node",
      "args": ["${workspaceFolder}/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Why cwd: dotenv loads .env from the current working directory. cwd must be the folder that contains .env and index.js.

If your Cursor build does not expand ${workspaceFolder}, switch to absolute paths under args and cwd for your machine.

Option B — User-global MCP

Add the same server block under your user MCP settings (Cursor’s global MCP config). Use absolute paths to wherever you cloned this repo.

After editing MCP config:

1. Open Cursor Settings → MCP (or Features → MCP)

2. Confirm redmine-all-in-one appears and is enabled

3. Use Reload / restart Cursor if the server stays disconnected

Using it from chat

1. Use Agent mode (or any chat mode where tools are allowed).

2. Ask clearly that answers should come from Redmine, e.g.

   • “Using Redmine MCP, list my open issues assigned to me.”

   • “Create a Feature in project identifier with subject … for version ….”

3. If the model forgets to use tools, say: “Only use Redmine MCP tools for Redmine data.”

The server authenticates with X-Redmine-API-Key; Redmine treats requests as the user who owns that key.

Tools reference

For endpoint paths and payloads, your installation follows Redmine’s REST API (see Redmine REST API).

Practical notes (save debugging time)

Validation errors (HTTP 422)

Your Redmine may enforce:

• Priority required on create → set priority_id (discover via GET /enumerations/issue_priorities.json).

• Estimated time on certain trackers → set estimated_hours on create/update or in extra_fields_json if using an older MCP schema cache.

Clearing assignee

Some setups accept PUT /issues/:id.json with "assigned_to_id": "". If your Redmine behaves differently, use the UI or check your Redmine version’s REST notes.

Security

• Rotate the API key if it was ever committed or pasted in an insecure channel.

• Prefer per-user keys—not shared accounts.

• Restrict file permissions on .env on shared machines (chmod 600 .env).

MCP schema cache

After upgrading index.js, reload MCP servers in Cursor so new/changed tool arguments appear in the UI.

Development

• Entry: index.js

• Start: npm start → runs node index.js

• Dependencies: @modelcontextprotocol/sdk, dotenv, zod

License

MIT (see LICENSE). Dependencies retain their own licenses; Redmine is a separate project under its own license.