Content
# Redmine MCP Server
Production-ready [Model Context Protocol](https://modelcontextprotocol.io/) 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
```bash
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
```bash
npm start
```
Verify:
```bash
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.
```json
{
"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:
```json
{
"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
```bash
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)
```bash
cp .env.example .env
# fill in production values
docker compose up -d --build
docker compose logs -f
```
### Option B — PM2 on the host
```bash
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
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available