Redmine MCP Server
Provides tools for interacting with a self-hosted Redmine instance, enabling search, creation, update, and upsert of issues; user detection and auto-assignment; status and date tracking; and time tracking through timers or manual hour logging.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Redmine MCP Server log 2 hours on issue #1234 for fixing the login bug"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@oaxapps/redmine-mcp-server
MCP (Model Context Protocol) server for self-hosted Redmine. Connect your AI coding tools to Redmine to search, create, and update issues directly from your IDE.
Features:
π Search, create, update, and upsert issues
π€ Auto-detect local user β maps to Redmine account (via git config, system user)
β± Time tracking β start/stop timers or log hours, automatically recorded in Redmine
π Automatic date tracking β sets
start_datewhen work begins,due_datewhen resolvedπ Auto-assign issues to the detected user
Works with: Claude Code Β· Google Antigravity Β· Cursor Β· Windsurf Β· OpenCode Β· Claude Desktop Β· VS Code Copilot Β· and any MCP-compatible client.
Prerequisites
Node.js 18+
Redmine REST API enabled:
Administration β Settings β API β Enable REST web serviceAPI key:
My Account β API access key(right sidebar)
Related MCP server: Redmine MCP Server
Installation & Setup
Claude Code
claude mcp add redmine -s user \
-e REDMINE_URL=https://your-redmine.com \
-e REDMINE_API_KEY=your_key \
-e REDMINE_PROJECT_ID=40 \
-- npx -y @oaxapps/redmine-mcp-serverUse
-s userfor all projects or-s localfor current project only.
Google Antigravity
Open the Agent panel β click "..." β MCP Servers
Click "Manage MCP Servers" β "View raw config"
This opens
mcp_config.jsonat:macOS/Linux:
~/.gemini/antigravity/mcp_config.jsonWindows:
C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json
Method 1 β Using npx:
{
"mcpServers": {
"redmine": {
"command": "npx",
"args": ["-y", "@oaxapps/redmine-mcp-server"],
"env": {
"REDMINE_URL": "https://your-redmine.com",
"REDMINE_API_KEY": "your_key",
"REDMINE_PROJECT_ID": "40"
}
}
}
}Method 2 β If you get npx not found in $PATH error:
Find your full paths:
which node
npm root -gInstall globally and use full paths:
npm install -g @oaxapps/redmine-mcp-server{
"mcpServers": {
"redmine": {
"command": "/full/path/to/node",
"args": ["/full/path/to/global/node_modules/@oaxapps/redmine-mcp-server/index.js"],
"env": {
"REDMINE_URL": "https://your-redmine.com",
"REDMINE_API_KEY": "your_key",
"REDMINE_PROJECT_ID": "40"
}
}
}
}Click Refresh on the Manage MCPs page
Cursor / Windsurf
Add to .cursor/mcp.json or your Windsurf MCP config:
{
"mcpServers": {
"redmine": {
"command": "npx",
"args": ["-y", "@oaxapps/redmine-mcp-server"],
"env": {
"REDMINE_URL": "https://your-redmine.com",
"REDMINE_API_KEY": "your_key",
"REDMINE_PROJECT_ID": "40"
}
}
}
}If you get a PATH error, use the full path method described in the Antigravity section above.
OpenCode
Project-level β add to opencode.json in your project root:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"redmine": {
"type": "local",
"command": ["npx", "-y", "@oaxapps/redmine-mcp-server"],
"environment": {
"REDMINE_URL": "https://your-redmine.com",
"REDMINE_API_KEY": "your_key",
"REDMINE_PROJECT_ID": "40"
},
"enabled": true
}
}
}Global (all projects) β add to ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"redmine": {
"type": "local",
"command": ["npx", "-y", "@oaxapps/redmine-mcp-server"],
"environment": {
"REDMINE_URL": "https://your-redmine.com",
"REDMINE_API_KEY": "your_key"
},
"enabled": true
}
}
}When installed globally, omit
REDMINE_PROJECT_IDβ the agent will specify the project per task, or you can set it per-project in the project-levelopencode.json.
If you get a PATH error, use full paths:
which node
npm root -g
npm install -g @oaxapps/redmine-mcp-server{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"redmine": {
"type": "local",
"command": ["/full/path/to/node", "/full/path/to/global/node_modules/@oaxapps/redmine-mcp-server/index.js"],
"environment": {
"REDMINE_URL": "https://your-redmine.com",
"REDMINE_API_KEY": "your_key",
"REDMINE_PROJECT_ID": "40"
},
"enabled": true
}
}
}Verify with opencode mcp list. Optionally add to your AGENTS.md:
When working on tasks, use the `redmine` tools to track progress in Redmine.Claude Desktop
Add to claude_desktop_config.json:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"redmine": {
"command": "npx",
"args": ["-y", "@oaxapps/redmine-mcp-server"],
"env": {
"REDMINE_URL": "https://your-redmine.com",
"REDMINE_API_KEY": "your_key",
"REDMINE_PROJECT_ID": "40"
}
}
}
}Available Tools
Issue Management
Tool | Description |
| List all accessible projects |
| List issue statuses with IDs |
| List trackers (Bug, Feature, Taskβ¦) |
| Search by project, subject, status, assignee |
| Get full issue details by ID |
| Create a new issue (auto-assigns user, auto-sets dates) |
| Update status, done%, notes, assignee (auto-sets dates) |
| Smart upsert β find by subject, update or create |
| Upload a local file (screenshot, log, HAR, PDFβ¦) and attach it to an issue |
User Detection
Tool | Description |
| Detect local user and show matched Redmine account |
Time Tracking
Tool | Description |
| Start a timer when beginning work on an issue |
| Stop the timer and log elapsed time to Redmine (optional |
| Discard a running timer without logging anything |
| Manually log hours spent on an issue |
| List time entries filtered by issue, project, user ( |
| Change hours, activity, comment, date, or issue of a time entry |
| Delete a time entry |
| List available activity types (Development, Designβ¦) |
How Automatic Features Work
π€ User Detection
The server identifies the local user through this priority chain:
1. REDMINE_USER_ID env var β direct match by ID
2. REDMINE_USER_EMAIL env var β match by email
3. git config user.email β match by email in Redmine
4. git config user.name β match by name in Redmine
5. $USER / $USERNAME β match by login in Redmine
6. Fallback β current API key ownerIssues are auto-assigned to the matched user when created. Time entries are automatically attributed to the detected user.
π Automatic Date Tracking
The server manages start_date and due_date based on status changes:
When status changes to... | What happens |
β In Progress (status 2) |
|
β Resolved (status 3) |
|
β Closed (status 5) |
|
New issue created |
|
You can override by passing explicit start_date or due_date values. Disable with REDMINE_AUTO_DATES=false.
β± Time Tracking
Call start_timer when work begins and stop_timer when done. The elapsed time is calculated automatically and logged as a Redmine time entry with the correct user and date.
Environment Variables
Variable | Required | Description |
| β | Base URL of your Redmine (e.g., |
| β | API key from My Account page |
| β | Default project ID (saves you from specifying it every time) |
| β | Override: directly set the Redmine user ID |
| β | Override: match by email instead of auto-detection |
| β | Auto-set start/due dates on status change (default: |
| β | Activity ID for time entries logged without |
Usage Examples
Basic issue management
Show me all open issues in project 40
Update Redmine issue #142 to Resolved with 100% done
Create a bug: "Fix timeout on /users endpoint" with high priorityUser detection
Who am I in Redmine?Time tracking with timer
Start a timer for issue #142, I'm working on the login feature
... (AI works on the task) ...
Stop the timer for issue #142 and log the timeTime tracking with manual hours
Log 2.5 hours on issue #142 for implementing authenticationSmart upsert with time and dates
Mark "User authentication" as done in project 40. Log 1.5 hours spent.
If it doesn't exist, create it.AI Agent Integration (PRD / CLAUDE.md / Skills)
Copy this section into your project's CLAUDE.md (Claude Code), Skills (Antigravity), or PRD file so the AI agent automatically follows the Redmine workflow:
Redmine Integration
This project is tracked in Redmine. All AI agents working on this codebase must keep Redmine in sync.
Connection:
Project ID:
40(change to your project)MCP Server:
@oaxapps/redmine-mcp-server
Status IDs:
ID | Status |
1 | New |
2 | In Progress |
3 | Resolved |
5 | Closed |
User Assignment:
Issues are auto-assigned to the current developer via git config detection.
Do NOT hardcode user IDs β the MCP server detects the correct Redmine user automatically.
Run
detect_userto verify the mapping is correct.
Date Tracking (Automatic):
start_dateis auto-set to today when an issue moves to In Progress (status 2).due_dateis auto-set to today when an issue moves to Resolved (status 3) or Closed (status 5).New issues get today as
start_dateby default.You can override dates by passing
start_dateordue_dateexplicitly.
Time Tracking:
Always call
start_timerwhen beginning work on an issue.Always call
stop_timerwhen the task is completed β this logs the elapsed time to Redmine automatically.If you forget to start a timer, use
log_timewith an estimated duration.Time is attributed to the detected user automatically.
Rules:
Before starting a task: Search Redmine for a matching issue. If it exists, update its status to
In Progress(status_id: 2). Thestart_datewill be set automatically. Then callstart_timer.If no issue exists: Create one using
create_issuewith the appropriate subject, description, tracker, andestimated_hours(estimate how long the task will take). Thestart_dateis set automatically. Then callstart_timer.When a task is completed: Call
stop_timerto log the time. Then update the issue toResolved(status_id: 3) withdone_ratio: 100. Thedue_datewill be set automatically.Always add a note describing what was done, including relevant file names or changes.
Partial progress: If a task is partially done, update
done_ratioto reflect the percentage (e.g., 30, 50, 70). Do NOT stop the timer β leave it running. Do NOT change the status.Bug fixes: Use
update_issueto add a note explaining the fix and set status toResolved.
Required fields checklist (every task must have):
β
start_timercalled at the beginning β logs spent timeβ
stop_timercalled at the end β logs spent timeβ
estimated_hoursset on create (your best estimate)β
done_ratioset to 100 when completeβ
status_id: 2(In Progress) when starting β auto-setsstart_dateβ
status_id: 3(Resolved) when done β auto-setsdue_dateβ
noteswith description of changes and files modified
Example Workflow:
1. User says: "Add password reset feature"
2. Agent searches Redmine:
search_issues(project_id: "40", subject: "password reset")
3. If found β update to In Progress (start_date auto-set):
update_issue(issue_id: 142, status_id: 2, notes: "Starting implementation")
4. If not found β create (start_date auto-set):
create_issue(project_id: "40", subject: "Add password reset feature",
tracker_id: 2, status_id: 2, estimated_hours: 2)
5. Start timer:
start_timer(issue_id: 142, description: "Implementing password reset")
6. Agent implements the feature...
7. Stop timer (logs elapsed time):
stop_timer(issue_id: 142) β logs 0.35h
8. Mark as resolved (due_date auto-set):
update_issue(issue_id: 142, status_id: 3, done_ratio: 100,
notes: "Implemented password reset via email token.
Files: src/auth/reset.ts, src/email/templates/reset.html")
Result in Redmine:
Issue #142: "Add password reset feature"
Status: Resolved
Assigned to: Carlos O. (auto-detected)
Start date: 2026-02-20 (auto-set)
Due date: 2026-02-20 (auto-set)
Estimated time: 2h
Spent time: 0.35h (from stop_timer)
Done: 100%Troubleshooting
Problem | Solution |
| Use full paths to |
| Check API key. Ensure REST API is enabled in Redmine admin settings. |
| Verify status_id, tracker_id, project_id are valid. Use |
| Your Redmine user may lack permissions for that project/action. |
User not detected | Run |
Time not logging | Check that time tracking is enabled in Redmine. Run |
Dates not updating | Ensure |
Server not connecting | Run |
License
MIT
Available Tools
18 toolscancel_timerA
Cancel the running timer for an issue WITHOUT logging any time to Redmine. The elapsed time is discarded.
Inputs: issue_id (required).
create_issueB
Create a new issue in Redmine. Auto-assigns to detected user. Auto-sets start_date if status is In Progress, due_date if Resolved/Closed.
Inputs: subject (required), due_date, status_id, done_ratio, +9 more.
create_or_update_issueB
Find an issue by subject in a project. If it exists, update it. If not, create it. Auto-assigns user, auto-sets dates, and can log time.
Inputs: subject (required), notes, due_date, status_id, +8 more.
delete_time_entryB
Permanently delete a time entry.
Inputs: id (required).
detect_userA
Detect the current local user and find their matching Redmine account. Uses git config, system username, and environment variables to identify the user.
Inputs: no named parameters.
get_issueA
Get full details of a specific Redmine issue by ID
Inputs: issue_id (required), include.
list_projectsB
List all Redmine projects accessible with your API key
Inputs: no named parameters.
list_statusesA
List all available issue statuses in Redmine (useful to get status IDs)
Inputs: no named parameters.
list_time_entriesB
List time entries, optionally filtered by issue, project, user, and date range.
Inputs: to, from, limit, user_id, +2 more.
list_time_entry_activitiesA
List available time entry activities (Development, Design, etc.)
Inputs: no named parameters.
list_trackersA
List all available trackers in Redmine (Bug, Feature, Task, etc.)
Inputs: no named parameters.
log_timeA
Manually log a time entry for an issue (without using start/stop timer). Automatically assigns to the detected user.
Inputs: hours (required), issue_id (required), spent_on, activity_id, +1 more.
search_issuesC
Search Redmine issues by subject, project, status, or assignee. Returns matching issues.
Inputs: limit, status, subject, project_id, +2 more.
start_timerA
Start a timer for an issue. Call this when you BEGIN working on a task. The elapsed time will be logged to Redmine when you call stop_timer.
Inputs: issue_id (required), description.
stop_timerB
Stop the timer for an issue and log the elapsed time to Redmine as a time entry. Automatically detects the current user for the time entry.
Inputs: issue_id (required), hours, activity_id, description.
update_issueB
Update an existing Redmine issue. Auto-sets start_date when moving to In Progress, due_date when moving to Resolved/Closed.
Inputs: issue_id (required), notes, subject, due_date, +7 more.
update_time_entryB
Update an existing time entry. Pass at least one field to change.
Inputs: id (required), hours, comments, issue_id, +2 more.
upload_attachmentA
Upload a local file (screenshot, log, HAR, PDFβ¦) and attach it to an issue.
Inputs: issue_id (required), file_path (required), filename, description.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 18 tools
Most tools target clearly distinct actions (timer controls, time-entry CRUD, issue search/read/create/update, metadata lists). The main ambiguity is between create_issue, update_issue, and create_or_update_issue, which could cause misselection when an agent is unsure whether an issue already exists.
All tool names use snake_case with a leading verb and a clear object, including compound names like create_or_update_issue and list_time_entry_activities. The convention is predictable throughout the set.
Eighteen tools is slightly above the typical sweet spot, but the server covers two related domainsβissue tracking and time trackingβplus supporting metadata and attachments. The tools are reasonably scoped rather than redundant.
Core issue and time-entry workflows are covered, including timer-based and manual logging plus time-entry update/delete. However, the issue surface lacks delete_issue, issue comment/journal operations, and richer project/user retrieval, which are notable gaps for a Redmine integration.
Maintenance
Related MCP Connectors
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Manage Redbooth tasks, task lists, comments, tags and files from Claude and other AI assistants.
Manage Orangescrum projects, tasks, users, sprints, test cases, releases, and risks from AI tools.
Read your tracked time and projects, pause tracking or add a note, from Claude or ChatGPT.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI assistants to interact with Redmine project management systems, providing comprehensive access to issues, projects, time tracking, users, and wiki pages through natural language commands.33499 npm1Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI applications to interact with Redmine project management systems for issue tracking, time logging, and project management through natural language.MIT
- AlicenseCqualityDmaintenanceEnables AI assistants to interact with Redmine instances, managing issues, projects, and metadata through natural language commands.1218 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to create, update, and query Redmine issues and projects directly from conversations.306 npm1MIT