Redmine MCP Server

Production-ready Model Context Protocol server that exposes Redmine issue management to AI clients (Cursor, Claude Desktop, etc.) over HTTP + SSE, so your whole team can connect remotely.

Features

• 18 Redmine tools: issues, search, projects, statuses, create/update, time tracking, wiki pages
• SSE transport for remote team access (GET /sse, POST /messages)
• Team gate via x-api-key (TEAM_SECRET on server)
• Per-user Redmine access via x-redmine-api-key in each colleague’s Cursor mcp.json
• Docker and docker-compose for staging/production
• nginx sample config with SSE-friendly proxy settings
• Health endpoint for monitoring

Project structure

redmine-mcp/
├── index.js           # MCP server + Express app
├── package.json
├── .env               # Local secrets (not committed)
├── .env.example
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── nginx.conf         # Reverse proxy template
└── README.md

Local setup

Prerequisites

• Node.js 18+
• A Redmine instance with REST API enabled
• A Redmine API key (My account → API access key)

Install

cd redmine-mcp
cp .env.example .env
# Edit .env with your Redmine URL and team secret (no personal API keys on the server)
npm install

Configure .env

Variable	Description
REDMINE_URL	Shared Redmine base URL for the whole team
TEAM_SECRET	Shared gate secret; clients send as x-api-key
PORT	HTTP port (default 3456)

Each user’s personal Redmine API key is not stored on the server. They put it in Cursor MCP headers as x-redmine-api-key.

Run locally

npm start

Verify:

curl -s http://localhost:3456/health
curl -s -H "x-api-key: YOUR_TEAM_SECRET" http://localhost:3456/health

MCP tools

Tool	Description
get_my_issues	Issues assigned to the API user (id, subject, status, priority, project, description, due_date, estimated_hours)
get_issue	Full issue by ID, including subtasks/children when available
get_subtasks	Child issues of a parent (parent_issue_id)
search_issues	Search by subject keyword; optional project_id
get_project_issues	Fetch all issues for a project by identifier slug
get_projects	List all projects
get_issue_statuses	List workflow statuses
update_issue	Update notes, done_ratio, status_id
create_issue	Create issue (project_id, subject required; optional description, priority, assignee)
log_time	Log hours on an issue; sets billable hours CF (defaults to hours); activity_id defaults to 5
get_time_entries	Time entries for one issue
get_my_time_entries	Current user’s time entries (optional date range)
get_time_activities	List activity types and IDs for log_time
get_project_time_entries	Project time entries with per-user hour summary
get_wiki_pages	List wiki pages for a project
get_wiki_page	Fetch one wiki page by project and title
create_wiki_page	Create a wiki page in a project
update_wiki_page	Update an existing wiki page

Project Issue Tools

get_project_issues

Purpose: Fetch all issues for a project using the project identifier slug.

Parameter	Type	Required	Description
project_slug	string	yes	Redmine project identifier slug
status_id	number or string	no	Status filter (default * for all statuses)
include_subprojects	boolean	no	Include subproject issues (default false)

This tool follows Redmine pagination and returns all matching issues, not just the first page.

Example prompts:

• “Show all issues for project redmine”
• “Fetch all open issues for project my-project-slug”
• “List every issue in project support including subprojects”

Time Tracking Tools

Use these tools to log work hours and review time spent in Redmine. Call get_time_activities first if you need valid activity_id values for log_time.

log_time

Purpose: Log time spent on a Redmine issue.

Parameter	Type	Required	Description
issue_id	number	yes	Issue to log time on
hours	number	yes	Hours spent (must be > 0), e.g. 1.5
activity_id	number	no	Activity type ID (default 5 = Development)
comments	string	no	Worklog comments
spent_on	string	no	Date YYYY-MM-DD (defaults to today)
billable_hours	number	no	Billable hours custom field (defaults to hours)

Billable hours are sent as Redmine custom field 1 by default (BILLABLE_HOURS_CF_ID in .env if your instance uses another ID).

Example prompts:

• “Log 2.5 hours on issue #142 for development activity”
• “Log 1 hour on issue 98, activity_id 9, comments: code review”
• “Log 3 hours on issue 50 with 2 billable hours”

get_time_entries

Purpose: Fetch all time entries for a specific issue.

Parameter	Type	Required	Description
issue_id	number	yes	Issue ID
limit	number	no	Max results (default 25)

Returns: id, issue_id, project, user, activity, hours, comments, spent_on, created_on.

Example prompts:

• “Show me all time entries for issue #98”
• “How much time has been logged on issue 142?”

get_my_time_entries

Purpose: Fetch time entries logged by the connected Redmine user.

Parameter	Type	Required	Description
from_date	string	no	Start date YYYY-MM-DD
to_date	string	no	End date YYYY-MM-DD
limit	number	no	Max results (default 50)

Example prompts:

• “What have I logged this week?”
• “Show my time entries from 2026-05-12 to 2026-05-18”

get_time_activities

Purpose: List available time activity types (Development, Design, Testing, etc.) and their IDs.

No parameters.

Example prompts:

• “What activity types are available for time logging?”
• “List Redmine time entry activities so I can log time”

get_project_time_entries

Purpose: Fetch time entries for an entire project, with a summary grouped by user and total hours.

Parameter	Type	Required	Description
project_id	number or string	yes	Project numeric ID or identifier slug
from_date	string	no	Start date YYYY-MM-DD
to_date	string	no	End date YYYY-MM-DD
limit	number	no	Max results (default 50)

Example prompts:

• “Show all time entries for project redmine slug”
• “Summarize logged hours by user for project 5 this month”

Wiki Tools

Use these tools to read and manage Redmine project wiki pages. project_id can be either the numeric project ID or the project identifier slug.

get_wiki_pages

Purpose: List wiki pages for a project.

Parameter	Type	Required	Description
project_id	number or string	yes	Project numeric ID or identifier slug

Example prompts:

• “List wiki pages for project redmine”
• “Show all wiki pages in project 5”

get_wiki_page

Purpose: Fetch a wiki page by project and title.

Parameter	Type	Required	Description
project_id	number or string	yes	Project numeric ID or identifier slug
title	string	yes	Wiki page title
include_attachments	boolean	no	Include attachments when available

Example prompts:

• “Show the Installation wiki page for project redmine”
• “Get the API Documentation wiki page with attachments”

create_wiki_page

Purpose: Create a wiki page in a project.

Parameter	Type	Required	Description
project_id	number or string	yes	Project numeric ID or identifier slug
title	string	yes	Wiki page title
text	string	yes	Wiki page content
comments	string	no	Version comment
parent_title	string	no	Parent wiki page title

Example prompts:

• “Create a wiki page called Deployment Notes in project redmine”
• “Create a child wiki page under Installation with these setup steps”

update_wiki_page

Purpose: Update an existing wiki page.

Parameter	Type	Required	Description
project_id	number or string	yes	Project numeric ID or identifier slug
title	string	yes	Wiki page title
text	string	yes	Replacement wiki page content
comments	string	no	Version comment
parent_title	string	no	Parent wiki page title

Example prompts:

• “Update the Deployment Notes wiki page in project redmine”
• “Replace the API Documentation wiki page content and add a version comment”

Cursor mcp.json (team members)

Add to ~/.cursor/mcp.json (or project .cursor/mcp.json).

• x-api-key — same TEAM_SECRET for everyone (from admin).
• x-redmine-api-key — each person’s own key from Redmine → My account → API access key.

{
  "mcpServers": {
    "redmine": {
      "url": "https://mcp.yourcompany.com/sse",
      "headers": {
        "x-api-key": "shared_team_secret_from_admin",
        "x-redmine-api-key": "your_personal_redmine_api_key"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "redmine-local": {
      "url": "http://localhost:3456/sse",
      "headers": {
        "x-api-key": "shared_team_secret_from_admin",
        "x-redmine-api-key": "your_personal_redmine_api_key"
      }
    }
  }
}

get_my_issues and other tools use the connected user’s Redmine identity, not an admin key on the server.

Health check

curl -s http://localhost:3456/health | jq

Returns server name, version, Redmine URL (configured), active SSE session count, and uptime. No API key required on /health.

Staging deployment

Option A — Docker (recommended)

cp .env.example .env
# fill in production values
docker compose up -d --build
docker compose logs -f

Option B — PM2 on the host

npm install --omit=dev
npm install -g pm2
pm2 start index.js --name redmine-mcp
pm2 save
pm2 startup

nginx reverse proxy

1. Copy nginx.conf to /etc/nginx/sites-available/redmine-mcp
2. Replace mcp.yourcompany.com with your domain
3. Enable site and reload nginx
4. Run certbot for TLS: certbot --nginx -d mcp.yourcompany.com

Ensure SSE locations keep proxy_buffering off and long proxy_read_timeout.

API endpoints

Method	Path	Auth	Purpose
GET	/sse	x-api-key + x-redmine-api-key	Establish MCP SSE stream (user key bound to session)
POST	/messages?sessionId=...	x-api-key	Client JSON-RPC messages (uses session’s Redmine key)
GET	/health	none	Liveness / status

Security notes

• Rotate TEAM_SECRET if leaked; share only via your team secret manager
• Terminate TLS at nginx; do not expose port 3456 publicly without a proxy
• Each colleague uses their own Redmine API key in Cursor; never commit keys to git
• Rotate TEAM_SECRET if leaked; rotate personal Redmine keys if compromised

License

ISC