redmine-pm-mcp

An MCP (Model Context Protocol) server that exposes all Redmine REST API endpoints as AI-assistant tools. Use it with VS Code Copilot, Claude Code, Cursor, or any MCP-compatible client to manage issues, projects, time entries, wiki pages, and more — all from natural language.

Prerequisites

| Requirement | Details | |---|---| | Node.js | ≥ 20 LTS | | npm | ≥ 10 (bundled with Node 20) | | Redmine | Any version with REST API enabled (Admin → Settings → API → Enable REST web service) | | Redmine API key | Found in your Redmine account page: My account → API access key |

⚠️ Security Warning

Your Redmine API key grants full access to your Redmine instance. Protect it like a password.

• NEVER hardcode your API key in MCP config files (settings.json, mcp.json, .cursor/mcp.json) — these files are often committed to version control.
• Always supply secrets via environment variables referencing a .env file or your system keychain.

Create a .env file at your project root (never commit this file):

# .env  — DO NOT commit this file
REDMINE_URL=https://your-redmine.example.com
REDMINE_API_KEY=your_api_key_here

Add to your .gitignore:

.env
*.env.local

Installation

VS Code (with GitHub Copilot / MCP Extension)

1. Install the MCP extension for VS Code if it is not already installed.
2. Open Settings (Ctrl+, / Cmd+,) and search for MCP servers.
3. Add the server configuration to your VS Code settings.json (or workspace .vscode/mcp.json):

{
  "mcp": {
    "servers": {
      "redmine": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "redmine-pm-mcp"],
        "env": {
          "REDMINE_URL": "${env:REDMINE_URL}",
          "REDMINE_API_KEY": "${env:REDMINE_API_KEY}"
        }
      }
    }
  }
}

4. Load the environment variables before launching VS Code:

# macOS / Linux — add to ~/.zshrc or ~/.bashrc
export REDMINE_URL=https://your-redmine.example.com
export REDMINE_API_KEY=your_api_key_here

# Or use a .env loader like direnv:
echo 'dotenv' >> .envrc && direnv allow

Claude Code

# Add via CLI
claude mcp add redmine \
  --command "npx" \
  --args "-y,redmine-pm-mcp" \
  --env REDMINE_URL="$REDMINE_URL" \
  --env REDMINE_API_KEY="$REDMINE_API_KEY"

Or add manually to ~/.claude/mcp.json:

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "redmine-pm-mcp"],
      "env": {
        "REDMINE_URL": "${REDMINE_URL}",
        "REDMINE_API_KEY": "${REDMINE_API_KEY}"
      }
    }
  }
}

Cursor

Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "redmine-pm-mcp"],
      "env": {
        "REDMINE_URL": "${env:REDMINE_URL}",
        "REDMINE_API_KEY": "${env:REDMINE_API_KEY}"
      }
    }
  }
}

Cursor reads env vars from your shell session. See the Cursor MCP documentation for details.

Tool Reference

Issues (11 tools)

| Tool | Description | Key Parameters | |---|---|---| | redmine_issues_list | List issues with filters | project_id, status_id, assigned_to_id, tracker_id, offset, limit | | redmine_issue_get | Get a single issue | id, include (journals, attachments, etc.) | | redmine_issue_create | Create an issue | project_id, subject (required); tracker, status, priority, description, assignee optional | | redmine_issue_update | Update an issue | id (required); any field + notes for journal comment | | redmine_issue_delete | Delete an issue | id | | redmine_issue_relations_list | List relations for an issue | issue_id | | redmine_issue_relation_create | Create a relation between issues | issue_id, issue_to_id, relation_type | | redmine_issue_relation_delete | Delete a relation | id (relation ID) | | redmine_issue_watcher_add | Add a watcher to an issue | issue_id, user_id | | redmine_issue_watcher_remove | Remove a watcher from an issue | issue_id, user_id | | redmine_issue_journals_list | List journal entries / comments | issue_id, offset, limit |

Example prompts:

• "List all open bugs assigned to me in project backend"
• "Create a bug: title 'Login fails with SSO', assign to user 42, mark high priority"
• "Close issue #1234 and add a comment saying it was fixed in v2.1"

Projects (7 tools)

| Tool | Description | Key Parameters | |---|---|---| | redmine_projects_list | List all accessible projects | include, offset, limit | | redmine_project_get | Get a project by ID or identifier | id, include | | redmine_project_create | Create a project | name, identifier (required) | | redmine_project_update | Update a project | id + any field | | redmine_project_archive | Archive a project (Redmine 5.0+) | id | | redmine_project_unarchive | Unarchive a project (Redmine 5.0+) | id | | redmine_project_delete | Permanently delete a project | id |

Memberships (4 tools)

| Tool | Description | Key Parameters | |---|---|---| | redmine_memberships_list | List project members | project_id | | redmine_membership_create | Add a user/group to a project | project_id, user_id or group_id, role_ids | | redmine_membership_update | Change member roles | id, role_ids | | redmine_membership_delete | Remove a member | id |

Versions / Milestones (5 tools)

| Tool | Description | Key Parameters | |---|---|---| | redmine_versions_list | List versions in a project | project_id | | redmine_version_get | Get a version | id | | redmine_version_create | Create a version | project_id, name | | redmine_version_update | Update a version | id + fields | | redmine_version_delete | Delete a version | id |

Issue Categories (5 tools)

| Tool | Description | Key Parameters | |---|---|---| | redmine_issue_categories_list | List categories in a project | project_id | | redmine_issue_category_get | Get a category | id | | redmine_issue_category_create | Create a category | project_id, name | | redmine_issue_category_update | Update a category | id + fields | | redmine_issue_category_delete | Delete a category | id |

Users (3 tools)

| Tool | Description | Key Parameters | |---|---|---| | redmine_users_list | List users (admin) | status, name, group_id, offset, limit | | redmine_user_get | Get a user or "current" | id, include | | redmine_my_account_get | Get your own account | — |

Groups (7 tools)

| Tool | Description | Key Parameters | |---|---|---| | redmine_groups_list | List all groups (admin) | offset, limit | | redmine_group_get | Get a group | id, include | | redmine_group_create | Create a group | name, user_ids optional | | redmine_group_update | Rename a group | id, name | | redmine_group_delete | Delete a group | id | | redmine_group_user_add | Add user to group | group_id, user_id | | redmine_group_user_remove | Remove user from group | group_id, user_id |

Time Entries (5 tools)

| Tool | Description | Key Parameters | |---|---|---| | redmine_time_entries_list | List time entries | project_id, issue_id, user_id, from, to | | redmine_time_entry_get | Get a time entry | id | | redmine_time_entry_create | Log time | hours, activity_id (required); issue_id or project_id, spent_on, comments | | redmine_time_entry_update | Edit a time entry | id + fields | | redmine_time_entry_delete | Delete a time entry | id |

Example prompts:

• "Log 2.5 hours of Development work on issue #567 today"
• "Show time entries for project alpha from 2024-01-01 to 2024-01-31"

Wiki (4 tools)

| Tool | Description | Key Parameters | |---|---|---| | redmine_wiki_pages_list | List wiki pages in a project | project_id | | redmine_wiki_page_get | Read a wiki page | project_id, title, version optional | | redmine_wiki_page_update | Create or update a wiki page | project_id, title, text, comments, version | | redmine_wiki_page_delete | Delete a wiki page | project_id, title |

Attachments & Files (4 tools)

| Tool | Description | Key Parameters | |---|---|---| | redmine_attachment_get | Get attachment metadata | id | | redmine_attachment_delete | Delete an attachment | id | | redmine_upload_file | Upload a file (returns token) | file_content_base64, filename | | redmine_project_files_list | List project files | project_id |

Upload workflow: Call redmine_upload_file first to get a token, then pass [{ token, filename, content_type }] in the uploads field of redmine_issue_create or redmine_issue_update.

News (1 tool)

| Tool | Description | Key Parameters | |---|---|---| | redmine_news_list | List news items | project_id optional, offset, limit |

Search (1 tool)

| Tool | Description | Key Parameters | |---|---|---| | redmine_search | Full-text search (Redmine 3.3+) | q (required), scope, titles_only, open_issues |

Reference / Metadata (7 tools)

| Tool | Description | Key Parameters | |---|---|---| | redmine_issue_statuses_list | List all issue statuses | — | | redmine_trackers_list | List all trackers | — | | redmine_enumerations_list | List priorities / activities / doc categories | type (issue_priorities, time_entry_activities, document_categories) | | redmine_roles_list | List all roles | — | | redmine_role_get | Get a role with permissions | id | | redmine_custom_fields_list | List custom fields (admin) | — | | redmine_queries_list | List saved issue queries | offset, limit |

Error Reference

| HTTP Status | Meaning | Resolution | |---|---|---| | 401 Unauthorized | Invalid or missing API key | Verify REDMINE_API_KEY. Find key at My account → API access key. | | 403 Forbidden | Insufficient privileges | Ensure your Redmine account has the required role or permission. | | 404 Not Found | Resource does not exist or is not visible | Check the ID and that your account can access the project. | | 409 Conflict | Concurrent modification conflict | Re-fetch the resource and retry the update. | | 412 Precondition Failed | X-Redmine-Switch-User header rejected | The specified user could not be impersonated; check admin rights. | | 413 Request Entity Too Large | Attachment exceeds maximum file size | Increase the limit at Administration → Settings → Files. | | 422 Unprocessable Entity | Validation error | The error message contains Redmine's field-level errors. Fix the invalid fields. | | 429 Too Many Requests | Rate limit hit | The server retries once automatically after 2 s. If it persists, reduce request frequency. | | 5xx Server Error | Redmine internal error | Check Redmine server logs. | | Network error | Cannot reach Redmine | Verify REDMINE_URL is correct and the server is reachable. |

Docker

Run the MCP server as a container — no local Node.js installation required.

Prerequisites: Docker Desktop ≥ 24 (or Docker Engine ≥ 24 + Compose plugin).

Build the image

docker build -t redmine-pm-mcp .

The image builds natively on both Apple Silicon (arm64) and x86_64 (amd64) — no --platform flag needed.

Run a container

docker run --rm -i \
  -e REDMINE_URL=https://your-redmine.example.com \
  -e REDMINE_API_KEY=your_api_key_here \
  redmine-pm-mcp

The -i flag keeps stdin open, which is required for MCP stdio transport.

License

MIT