* Required when REDMINE_AUTH_MODE=legacy-per-user. † Required when REDMINE_AUTH_MODE=legacy. Either REDMINE_API_KEY or REDMINE_USERNAME+REDMINE_PASSWORD must be set. API key is recommended. ‡ Required when REDMINE_AUTH_MODE=oauth or REDMINE_AUTH_MODE=oauth-proxy. § Required when REDMINE_AUTH_MODE=oauth-proxy. ¶ Required when REDMINE_AUTH_MODE=api-key-login. Secret values can also be supplied with Docker/Kubernetes-style file variables: REDMINE_INTROSPECT_CLIENT_SECRET_FILE, REDMINE_MCP_JWT_SIGNING_KEY_FILE, and REDMINE_OAUTH_CLIENT_SECRET_FILE.

When REDMINE_AUTOFILL_REQUIRED_CUSTOM_FIELDS=true, create_redmine_issue retries once on relevant custom-field validation errors (for example <Field Name> cannot be blank or <Field Name> is not included in the list) and fills values only from:

• the Redmine custom field default_value, or
• REDMINE_REQUIRED_CUSTOM_FIELD_DEFAULTS

In practice only the second one can fire. The server reads project custom fields from GET /projects/{id}.json?include=issue_custom_fields, which Redmine renders as id and name only, so it never sees default_value -- see list_project_issue_custom_fields. Set the env map if you want autofill to have anything to work with.

Example:

REDMINE_AUTOFILL_REQUIRED_CUSTOM_FIELDS=true
REDMINE_REQUIRED_CUSTOM_FIELD_DEFAULTS='{"Required Field A":"Value A","Required Field B":"Value B"}'

If your Redmine server uses a self-signed certificate or internal CA:

# In .env file
REDMINE_URL=https://redmine.company.com
REDMINE_API_KEY=your_api_key
REDMINE_SSL_CERT=/path/to/ca-certificate.crt

Supported certificate formats: .pem, .crt, .cer

For environments requiring client certificate authentication:

# In .env file
REDMINE_URL=https://secure.redmine.com
REDMINE_API_KEY=your_api_key
REDMINE_SSL_CERT=/path/to/ca-bundle.pem
REDMINE_SSL_CLIENT_CERT=/path/to/cert.pem,/path/to/key.pem

Note: Private keys must be unencrypted (Python requests library requirement).

⚠️ WARNING: Only use in development/testing environments!

# In .env file
REDMINE_SSL_VERIFY=false

Disabling SSL verification makes your connection vulnerable to man-in-the-middle attacks.

Each MCP request carries its own Authorization: Bearer <token>, so every user authenticates with their own Redmine account. The server validates each token against Doorkeeper's introspection endpoint before forwarding it, and exposes the OAuth2 discovery and /revoke endpoints clients need.

REDMINE_AUTH_MODE=oauth
REDMINE_URL=https://redmine.example.com
REDMINE_MCP_BASE_URL=https://redmine-mcp.example.com   # public URL of this server

# Confidential OAuth app registered in Redmine admin (see setup guide)
REDMINE_INTROSPECT_CLIENT_ID=...
REDMINE_INTROSPECT_CLIENT_SECRET=...

You register the OAuth app manually in Redmine admin → Applications (no Dynamic Client Registration). Full walkthrough, endpoint reference, and troubleshooting: OAuth2 Setup Guide.

FastMCP acts as the MCP-facing authorization server: it handles DCR for MCP clients, then redirects users to Redmine as the upstream OAuth provider for consent. Use this when clients (e.g. Claude Desktop, VS Code) expect to register themselves.

REDMINE_AUTH_MODE=oauth-proxy
REDMINE_URL=https://redmine.example.com
REDMINE_MCP_BASE_URL=https://redmine-mcp.example.com   # public URL of this server

# Confidential OAuth app registered in Redmine admin (see setup guide)
REDMINE_INTROSPECT_CLIENT_ID=...
REDMINE_INTROSPECT_CLIENT_SECRET=...
REDMINE_MCP_JWT_SIGNING_KEY=...

The upstream Redmine app must register ${REDMINE_MCP_BASE_URL}/auth/callback as its redirect URI. Storage, scaling, and credential-reuse notes are in the OAuth2 Setup Guide.

The server acts as its own OAuth authorization server, so MCP clients connect with nothing but its URL. On first use the client opens a browser, the user pastes their personal Redmine API key into a page this server serves, and every tool call from then on runs as that user. No key goes into any client configuration, and passwords are never asked for.

REDMINE_AUTH_MODE=api-key-login
REDMINE_URL=https://redmine.example.com
REDMINE_MCP_BASE_URL=https://redmine-mcp.example.com   # public https URL of this server
REDMINE_MCP_JWT_SIGNING_KEY=...                        # encrypts the stored keys

The server stores each user's key encrypted below FASTMCP_HOME/api-key-login/, so that directory needs a persistent volume and the mode runs as a single replica. OAuth scopes here are a narrowing the client asks for, not Redmine permissions; Redmine's own permissions stay the boundary. Read the api-key-login guide for the security model, session rules and client setup before enabling it.

For Redmine instances too old for OAuth, each user's MCP client sends its own Redmine API key in an X-Redmine-API-Key header. Each request runs as that user's identity with that user's permissions.

This is an advanced, opt-in mode. It requires TLS end-to-end and a correctly configured reverse proxy. Read docs/legacy-per-user-auth.md for the threat model, firewall guidance, and revocation runbook before enabling it.

mcp-remote (recommended):

{ "mcpServers": { "redmine": {
  "command": "npx",
  "args": ["mcp-remote", "https://your-host/mcp",
           "--header", "X-Redmine-API-Key:${RM_KEY}"],
  "env": { "RM_KEY": "<your redmine api key>" }
}}}

Note the colon with no surrounding spaces in X-Redmine-API-Key:${RM_KEY}. This avoids an arg-escaping bug in Cursor and Claude Desktop on Windows.

VS Code (mcp.json):

Use .vscode/mcp.json (workspace file) or the user profile mcp.json. The workspace .mcp.json silently drops headers (see microsoft/vscode#319528), so do not use that file. Pin VS Code 1.102 or newer.

{
  "servers": {
    "redmine": {
      "type": "http",
      "url": "https://your-host/mcp",
      "headers": { "X-Redmine-API-Key": "${input:rmKey}" },
      "inputs": [{ "id": "rmKey", "type": "promptString",
                   "description": "Redmine API key", "password": true }]
    }
  }
}

Unsupported: any client that cannot set a custom request header, or that reserves the Authorization header for its own OAuth flow.

VS Code has built-in MCP support via GitHub Copilot (requires VS Code 1.102+).

Using CLI (Quickest):

code --add-mcp '{"name":"redmine","type":"http","url":"http://127.0.0.1:8000/mcp"}'

Using Command Palette:

1. Open Command Palette (Cmd/Ctrl+Shift+P)
2. Run MCP: Open User Configuration (for global) or MCP: Open Workspace Folder Configuration (for project-specific)
3. Add the configuration:
   json

   {
     "servers": {
       "redmine": {
         "type": "http",
         "url": "http://127.0.0.1:8000/mcp"
       }
     }
   }
   

4. Save the file. VS Code will automatically load the MCP server.

Manual Configuration: Create .vscode/mcp.json in your workspace (or mcp.json in your user profile directory):

{
  "servers": {
    "redmine": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Add to Claude Code using the CLI command:

claude mcp add --transport http redmine http://127.0.0.1:8000/mcp

Or configure manually in your Claude Code settings file (~/.claude.json):

{
  "mcpServers": {
    "redmine": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Claude Desktop's config file supports stdio transport only. Use FastMCP's proxy via uv to bridge to this HTTP server.

Setup:

1. Open Claude Desktop
2. Click the Claude menu (macOS menu bar / Windows title bar) > Settings...
3. Click the Developer tab > Edit Config
4. Add the following configuration:

{
  "mcpServers": {
    "redmine": {
      "command": "uv",
      "args": [
        "run",
        "--with", "fastmcp",
        "fastmcp",
        "run",
        "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}

5. Save the file, then fully quit and restart Claude Desktop
6. Look for the tools icon in the input area to verify the connection

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Note: The Redmine MCP server must be running before starting Claude Desktop.

Cursor talks to HTTP MCP servers directly, with no bridge.

1. Create ~/.cursor/mcp.json (available in every project) or .cursor/mcp.json in your project root (that project only):
   json

   {
     "mcpServers": {
       "redmine": {
         "url": "http://127.0.0.1:8000/mcp"
       }
     }
   }
   

2. Save the file. Cursor picks the server up automatically; its MCP settings list the server and the tools it loaded.

Note: Cursor identifies a remote server by a bare url and has no type field, unlike the VS Code and Claude Code configs above.

In legacy-per-user mode, add the API key header:

{
  "mcpServers": {
    "redmine": {
      "url": "https://your-host/mcp",
      "headers": { "X-Redmine-API-Key": "<your redmine api key>" }
    }
  }
}

In oauth mode, set REDMINE_OAUTH_DISCOVERY_AS=self on the MCP server. Cursor looks for authorization server metadata at its own canonical well-known location, which the default (redmine) discovery profile does not serve, so the flow stalls without it (#188). See Cursor and self-AS discovery.

Add to Codex CLI using the command:

codex mcp add redmine -- npx -y mcp-client-http http://127.0.0.1:8000/mcp

Or configure manually in ~/.codex/config.toml:

[mcp_servers.redmine]
command = "npx"
args = ["-y", "mcp-client-http", "http://127.0.0.1:8000/mcp"]

Note: Codex CLI primarily supports stdio-based MCP servers. The above uses mcp-client-http as a bridge for HTTP transport.

Kiro primarily supports stdio-based MCP servers. For HTTP servers, use an HTTP-to-stdio bridge:

1. Create or edit .kiro/settings/mcp.json in your workspace:
   json

   {
     "mcpServers": {
       "redmine": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-client-http",
           "http://127.0.0.1:8000/mcp"
         ],
         "disabled": false
       }
     }
   }
   

2. Save the file and restart Kiro. The Redmine tools will appear in the MCP panel.

Note: Direct HTTP transport support in Kiro is limited. The above configuration uses mcp-client-http as a bridge to connect to HTTP MCP servers.

Most MCP clients use a standard configuration format. For HTTP servers:

{
  "mcpServers": {
    "redmine": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

For clients that require a command-based approach with HTTP bridge:

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "mcp-client-http", "http://127.0.0.1:8000/mcp"]
    }
  }
}

Core tools (51, always available)

These tools require only a Redmine instance and credentials, with no extra plugins or feature flags.

• Project Management (10 tools)

  • list_redmine_projects - List accessible projects (active only unless filters asks for more), narrowed server-side and optionally paginated
  • list_project_issue_custom_fields - List issue custom fields configured for a project
  • list_redmine_versions - List versions/milestones for a project
  • manage_redmine_version - Create, update, or delete a version/milestone
  • manage_redmine_project - Create a project, edit its settings, or close and reopen it
  • list_project_members - List members and roles of a project
  • summarize_project_status - Get comprehensive project status summary
  • list_redmine_roles - List all roles defined in the Redmine instance (for discovering valid role_ids)
  • get_project_modules - Retrieve the enabled modules for a project
  • manage_project_member - Add, update, or remove a project membership

• Issue Operations (13 tools)

  • get_redmine_issue - Retrieve detailed issue information (supports journal pagination, watchers, relations, children)
  • list_redmine_issues - List issues with flexible filtering (project, status, assignee, etc.)
  • search_redmine_issues - Search issues by text query
  • create_redmine_issue - Create new issues, with optional file attachments via the uploads parameter
  • update_redmine_issue - Update existing issues, with optional file attachments via the uploads parameter (combine with notes to attach files to a journal note)
  • delete_redmine_issue - Hard-delete an issue with required confirmation flags and a cascade-impact preview before irreversible deletion.
  • copy_issue - Duplicate an existing issue with optional field overrides
  • list_subtasks - List subtasks (child issues) of a given parent
  • get_private_notes - Retrieve private notes on an issue
  • manage_issue_relation - List, create, or delete issue relations
  • manage_issue_watcher - Add or remove a watcher on an issue
  • manage_issue_note - Edit a journal note's text or toggle its privacy
  • manage_issue_category - List, create, update, or delete issue categories
  • Note: get_redmine_issue can include custom_fields and update_redmine_issue can update custom fields by name (for example {"size": "S"}).

• Time Tracking (4 tools)

  • list_time_entries - List time entries with filtering by project, issue, user, and date range
  • manage_time_entry - Create or update a time entry (use user_id to log on behalf of another user)
  • list_time_entry_activities - Discover available activity types for time entries
  • import_time_entries - Bulk import time entries via sequential API calls with per-entry error reporting

• Discovery / Enumeration (7 tools): help LLMs find valid IDs before calling create/update tools

  • list_redmine_trackers - List all trackers (Bug, Feature, Support, etc.)
  • list_project_trackers - List the trackers enabled for a specific project
  • list_redmine_issue_statuses - List all issue statuses with their is_closed flag
  • list_redmine_issue_priorities - List all priority levels
  • list_redmine_users - Filter/list users (admin-only; supports name and group filters)
  • get_current_user - Get the authenticated user's profile (works for non-admins)
  • list_redmine_queries - List saved custom queries (read-only)

• Search & Wiki (2 tools)

  • search_entire_redmine - Global search across issues and wiki pages (Redmine 3.3.0+)
  • manage_redmine_wiki_page - List, get, create, update, delete, or rename wiki pages

• News (4 tools): project announcements -- release notes, maintenance windows

  • list_redmine_news - List news, optionally for one project
  • get_redmine_news - Read one news item with its comments and attachments
  • manage_redmine_news - Create or update a news item (Redmine 4.1+)
  • delete_redmine_news - Delete a news item, with confirmation (Redmine 4.1+)

• File Operations (5 tools)

  • list_files - List files uploaded to a project's Files section
  • create_upload_ticket - Reserve an upload slot and return a single-use URL, so a file on the caller's machine reaches the server without its bytes passing through the model
  • upload_file - Upload a new file to a project (from a staged upload_id, a URL, base64 content, or a server-side file_path), optionally tied to a version
  • delete_file - Delete a file from a project
  • get_redmine_attachment - Download an attachment (works in both HTTP and stdio mode)

• Gantt (1 tool)

  • get_gantt_chart - Retrieve project timeline data: issues with dates, dependencies, and milestones

• Interactive Apps (4 tools): render live UI in the chat via the MCP Apps extension (requires a client that supports it)

  • show_triage_board - Render a project's issues as an interactive Kanban board grouped by status, with drag-to-change-status write-back
  • get_triage_board_data - Board data source backing the board's Refresh action
  • show_project_dashboard - Render a live project snapshot (open/closed, overdue, due this week, open-by-priority, recent activity) as an interactive dashboard, with click-through drill-ins to matching issue lists
  • get_project_dashboard_data - App-only data source backing the dashboard's Refresh action

• Meta (1 tool)

  • get_mcp_server_info - Report server version, auth mode, read-only state, the authenticated user (current_user), and which plugin-gated tool families are enabled. Use to detect deployment lag before relying on a recently-shipped fix, or to confirm who assigned_to_id="me" resolves to.

Plugin-gated tools (13, opt in via env var)

These tools require a corresponding Redmine plugin installed on the server and the matching environment variable set to true on the MCP server. They are listed in tools/list only when their flag is set; with the flag off they are not registered on the MCP surface (and a direct call still returns a feature-disabled error).

• Checklists (3 tools): set REDMINE_CHECKLISTS_ENABLED=true; requires the RedmineUP Checklists Pro plugin

  • get_checklist - Retrieve all checklist items for an issue
  • create_checklist_item - Add a new checklist item to an issue
  • update_checklist_item - Update a checklist item's text, done state, or position

• Products (1 tool): set REDMINE_PRODUCTS_ENABLED=true; requires the RedmineUP Products plugin

  • manage_product - List, get, create, or update products

• Contacts (CRM) (2 tools): set REDMINE_CRM_ENABLED=true; requires the RedmineUP CRM plugin. In OAuth mode the flag also adds the CRM permissions to the advertised scopes, so grant them on the OAuth application and have users re-consent. Set REDMINE_CRM_EDITION=pro on a Pro install to allow the contact list filters the Light build does not register

  • manage_contact - List, get, create, update, delete, or assign/remove project association for contacts
  • list_contact_tags - Tags in use on contacts, with colors, for the tags filter and tag_list

• Deals (CRM) (3 tools): set REDMINE_DEALS_ENABLED=true; requires the Pro edition of the same CRM plugin, and the deals project module enabled on the project. Deals have their own flag because the Light edition defines none of the deal permissions, so advertising them would break consent for Light deployments

  • manage_deal - List, get, create, update, or delete deals
  • list_deal_statuses - Deal statuses (admin-only on the plugin side) and a project's deal categories, for use before creating a deal
  • manage_deal_category - List, create, rename, or delete a project's deal categories

• CRM notes and saved queries (2 tools, shared): available when either REDMINE_CRM_ENABLED or REDMINE_DEALS_ENABLED is set; each call is gated on the flag matching the note's or query's source

  • manage_crm_note - Get, create, update, or delete CRM notes on contacts and deals
  • list_crm_queries - Saved contact or deal queries

• Deal product lines (1 tool): needs both REDMINE_DEALS_ENABLED=true and REDMINE_PRODUCTS_ENABLED=true; the endpoint exists only when the Products plugin is installed next to CRM

  • add_deal_product - Add a catalogue or free-form product line to a deal

• Documents (DMSF) (1 tool): set REDMINE_DMSF_ENABLED=true; requires the redmine_dmsf plugin

  • manage_document - List, get, create (upload), or update (new revision) DMSF documents

Operator tools (1, admin-gated)

Hidden from tools/list by default. Set REDMINE_MCP_EXPOSE_ADMIN_TOOLS=true to register them on the MCP surface. The underlying background tasks run regardless of this flag; exposing them only adds the option to drive them through MCP.

• cleanup_attachment_files - Manually trigger cleanup of expired attachment files (the background cleanup task runs automatically regardless)