List all trackers configured on the Redmine server.

Returns a JSON document describing each tracker (id, name, default status, description). Cached entries are populated as a side effect for use by future schema-validation tools.

Return an enriched schema for one tracker.

Args: tracker: numeric id or name (e.g. "Bug" or "1"). include_observations: if True (default), include the learned workflow graph (allowed/disallowed transitions per role).

Includes available statuses, priorities, and — when include_observations is true — the learned workflow graph from prior API responses. Workflow knowledge is reactive: Redmine does not expose /workflows via REST, so the cache learns by observing the outcome of every status-change attempt.

Return a project description (trackers, modules, issue categories).

Args: project: numeric id or identifier slug (e.g. "claudecode" or "15").

Cache-backed. First call populates the cache.

List projects (paginated, optional substring filter).

Args: query: optional case-insensitive substring filter on name/identifier/description (applied client-side after fetch). limit: page size, max 100. Defaults to 25. offset: skip the first N results. Defaults to 0.

Returns a JSON document with projects, total_count, limit, offset, and filtered_locally (whether the query filter was applied).

Create a new project.

Args: name: required project display name. identifier: required URL slug (lowercase, hyphens, no spaces). description: optional project description. homepage: optional homepage URL. is_public: whether the project is publicly visible (default True). parent_id: optional parent project id (0 for top-level). inherit_members: if True, inherit members from parent. tracker_ids: optional list of tracker ids to enable. enabled_module_names: optional list of modules (e.g. ["issue_tracking", "wiki", "boards"]).

Honors REDMINE_MCP_READ_ONLY.

Update a project. Partial — only supplied fields are sent.

Args: project_id: numeric id or identifier slug. name: optional new display name. description: optional new description. homepage: optional new homepage URL. is_public: project visibility. parent_id: new parent project id (0 for unchanged). inherit_members: whether to inherit members from parent. tracker_ids: optional list of tracker ids to enable. enabled_module_names: optional list of modules.

Returns the refreshed project. Honors REDMINE_MCP_READ_ONLY.

Permanently delete a project and all its data.

Args: project_id: numeric id or identifier slug.

Destructive — cannot be undone. Honors REDMINE_MCP_READ_ONLY.

Archive a project (Redmine 5.0+). Reversible via unarchive.

Args: project_id: numeric id or identifier slug.

Honors REDMINE_MCP_READ_ONLY.

Unarchive a previously archived project (Redmine 5.0+).

Args: project_id: numeric id or identifier slug.

Honors REDMINE_MCP_READ_ONLY.

Drop cached entries for a scope. No HTTP request is made.

Args: scope: one of: - "all" — drop all schema rows (preserves auth fingerprint). - "tracker:<id-or-name>" — drop one tracker + its workflow rows. - "project:<id-or-slug>" — drop one project.

Use after Redmine config changes (new trackers, edited workflow, moved roles). The auth fingerprint is preserved so subsequent calls don't trigger a reconcile-wipe.

Fetch a single issue.

Args: issue_id: numeric Redmine issue id. include: comma-separated includes (default "attachments,journals,relations,watchers"). Pass an empty string to use the default.

Read-only — no validation, no caching.

Create an issue with cache-aware id resolution.

Args: project: numeric id or identifier slug (e.g. "claudecode"). tracker: numeric id or name (e.g. "Bug"). subject: required, must be non-empty. description: optional issue body. priority: optional id or name (e.g. "High"); defaults to tracker default when empty. status: optional id or name. Most fleets force initial status via workflow; this is rarely needed. assigned_to_id: optional Redmine user id; 0 means unassigned. difficulty: optional engagement-mode level for the global Difficulty custom field. Values: "Unclassified" / "Easy" / "Normal" / "Hard". When omitted, the field default-fills with "Unclassified" so auto-callers don't trip the required-field validation. Silently no-ops on fleets that don't have a Difficulty field configured. held: optional boolean. True marks the issue as held (blocks closing). False (default) leaves the Held field unset. held_until: optional ISO-8601 date ("2026-10-01"). Sets the Held Until custom field. Empty leaves it unset. Only meaningful when held is True. due_date: optional ISO-8601 date ("2026-05-17"). Empty leaves it unset. start_date: optional ISO-8601 date. Empty leaves it unset (Redmine defaults to the creation date). done_ratio: optional 0-100 progress percent. -1 (sentinel) means unset; 0 is explicit "no progress yet." custom_fields: optional list of {"id": <int>, "value": <str>} entries for arbitrary custom fields. Accepts either a Python list (preferred — Claude can pass it natively) or a JSON- encoded string. Empty string means no custom-field changes beyond what difficulty sets.

Returns the created issue or a structured validation error. Honors REDMINE_MCP_READ_ONLY.

Update an issue, with reactive workflow validation on status changes.

Args: issue_id: numeric Redmine issue id. subject: optional new subject. description: optional new description. status: optional id or name (e.g. "In Progress"). Triggers workflow pre-flight against the cache. priority: optional id or name. assigned_to_id: optional user id; 0 means unchanged. notes: optional comment to attach with this update (becomes a journal entry). difficulty: optional engagement-mode level for the global Difficulty custom field. Values: "Unclassified" / "Easy" / "Normal" / "Hard". NO default-fill on update — empty means "don't change Difficulty." held: optional boolean. True marks the issue as held (blocks closing). False (default) means unchanged. To clear a held flag, pass held=True is wrong — instead pass custom_fields with {"id": 2, "value": ""} directly, or set held=False won't fire (sentinel is falsy). held_until: optional ISO-8601 date ("2026-10-01"). Sets the Held Until custom field. Empty means unchanged. due_date: optional ISO-8601 date ("2026-05-17"). Empty leaves it unchanged; pass the literal string "" (i.e. just don't send this arg) to leave it untouched. To clear an existing due_date you currently need redmine_request with {"issue": {"due_date": null}} — the MCP can't distinguish "unset" from "leave alone" without explicit null support. start_date: same shape as due_date. done_ratio: optional 0-100 progress percent. -1 (sentinel) means unchanged; 0 is explicit "reset to no progress." fixed_version_id: optional version id (string for id-or-empty). Empty leaves unchanged; explicit "0" clears the version. custom_fields: optional list of {"id": <int>, "value": <str>} entries. Accepts either a Python list (preferred) or a JSON- encoded string. Empty means no custom-field changes.

On a status change the cache pre-flight short-circuits any previously-observed disallowed transition with a :class:WorkflowTransitionDisallowed payload. After a real PUT the outcome is recorded so future calls benefit. Honors REDMINE_MCP_READ_ONLY.

Move an issue to its first is_closed status (defaults to id 5).

Args: issue_id: numeric Redmine issue id. note: optional closing comment (becomes a journal entry). Use actual newline characters for multi-line notes, not backslash-n escape sequences. Redmine renders notes as Markdown (headings, bold, tables, lists all work).

On a workflow-disallowed direct closure, the response is repackaged with a closure-specific hint listing the allowed next states. Honors REDMINE_MCP_READ_ONLY.

Permanently delete an issue. Cannot be undone.

Args: issue_id: numeric Redmine issue id. confirm_destructive: must be True to proceed. Safety gate consistent with other destructive MCP tools.

Returns the deleted issue's id and subject for confirmation. Honors REDMINE_MCP_READ_ONLY.

Search/list issues with optional filters and pagination.

Args: query: substring on issue subject (Redmine subject=~ filter). Empty for unfiltered. project: optional numeric id or identifier slug. status: optional id, name, or one of Redmine's special tokens ("open", "closed", "*"). Lower-case tokens are passed through; named statuses (e.g. "Closed") resolve via the cache. query_id: optional Redmine saved query id (numeric). When set, invokes the saved query and merges any other filters (status, project, etc.) on top per Redmine's standard semantics. 0 (default) means no saved query. limit: page size (capped at 100). offset: skip the first N results.

Returns {issues, total_count, limit, offset, query}.

Append a comment (journal entry) to an existing issue.

Args: issue_id: numeric Redmine issue id. note: comment body. Empty/whitespace-only notes are rejected client-side. Use actual newline characters for multi-line notes, not backslash-n escape sequences (literal \n gets stored as visible text, not a line break). Redmine renders notes as Markdown — headings, bold, tables, and lists all work when separated by blank lines. private: if True, mark as a private journal (visible only to users with the view_private_notes Redmine permission).

Honors REDMINE_MCP_READ_ONLY. Direct PUT — no pre-fetch, no workflow check (comments don't change status).

Return the structured journal entries for an issue.

Args: issue_id: numeric Redmine issue id.

Each journal entry has id, user, created_on, notes (the comment body if any), and details (a list of field-change records). Read-only.

Edit an existing journal entry's notes in place.

Requires Redmine 5.0+. Use redmine_get_journals to find the journal_id to edit.

Args: journal_id: numeric journal id. notes: replacement note text. Pass an empty string to clear the note (deletes the journal if it has no field-change details). Use actual newline characters for multi-line notes, not backslash-n escape sequences. Redmine renders notes as Markdown.

Honors REDMINE_MCP_READ_ONLY. The API user can only edit their own notes unless they have the edit_issue_notes permission.

Upload a file (path-restricted) and optionally attach it to an issue.

Args: file_path: absolute or ~-relative path to a regular file. Must resolve under one of REDMINE_MCP_ALLOWED_DIRECTORIES (default /tmp); symlinks are resolved before checking. issue_id: if non-zero, attach the upload to this issue. Otherwise return the bare upload token for later attachment. description: optional human-readable description for the attachment (only meaningful when attaching).

Honors REDMINE_MCP_READ_ONLY.

Download an attachment by id to a path-restricted location.

Args: attachment_id: numeric Redmine attachment id (visible on issue payloads at attachments[].id). save_to: target file path. Parent directory must exist and resolve under one of REDMINE_MCP_ALLOWED_DIRECTORIES (default /tmp); symlinks are resolved before checking. overwrite: if False (default), refuse to overwrite an existing file at save_to.

Validates downloaded byte count against Redmine's reported filesize before writing — short reads are surfaced as attachment_size_mismatch rather than silently saving a partial file. Read-only-safe (no Redmine writes).

Log a time entry against an issue or project.

Args: hours: required. Decimal (e.g. "2.5") or "H:MM" (e.g. "2:30"). Pre-validated client-side. issue_id: target issue. Either this or project_id is required. project_id: target project (when not logging against a specific issue). Ignored when issue_id is non-zero. activity: optional id or name (e.g. "Development"); resolves against the cached activity enumeration. Empty for the default. spent_on: optional YYYY-MM-DD; defaults to today server-side. comments: optional, max 1024 chars. user_id: admin-only override; otherwise current user.

Honors REDMINE_MCP_READ_ONLY.

List time entries with optional filters.

Args: issue_id, project_id, user_id: filter by reference id (0 for none). spent_on: exact-date filter (YYYY-MM-DD). from_date / to_date: date-range filter. limit: page size (capped at 100). offset: skip the first N results.

Update a time entry. Partial — only supplied fields are sent.

Honors REDMINE_MCP_READ_ONLY.

Delete a time entry. Permanent — no soft-delete in Redmine.

Honors REDMINE_MCP_READ_ONLY.

Add a user as a watcher of an issue.

Args: issue_id: numeric Redmine issue id. user_id: numeric user id to add to the watcher list.

Idempotent on the Redmine side. Honors REDMINE_MCP_READ_ONLY.

Remove a user from an issue's watcher list.

Args: issue_id: numeric Redmine issue id. user_id: numeric user id to remove.

A 404 from Redmine means the watcher wasn't on the list (vs. issue not found — distinguishable by status code on the underlying error payload). Honors REDMINE_MCP_READ_ONLY.

Return the current watcher list for an issue.

Each watcher entry has id and name. Read-only.

Fetch a wiki page (optionally a historical version).

Args: project: numeric id or identifier slug (e.g. "claudecode"). title: wiki page title (URL-encoded automatically; spaces and unicode are fine). version: if non-zero, fetch that specific historical version.

Returns the page (text, version, author, timestamps) or wiki_page_not_found. Read-only.

Create a new wiki page; refuses to overwrite an existing one.

Args: project: numeric id or identifier slug. title: new wiki page title (URL-encoded automatically). text: markdown body. Empty/whitespace-only is rejected client-side. parent_title: optional parent wiki page (for hierarchy). comments: optional revision comment.

Pre-flight: GET first to confirm the page doesn't exist. If it does, returns wiki_page_already_exists with the existing version. Honors REDMINE_MCP_READ_ONLY.

Update an existing wiki page (with optional optimistic concurrency).

Args: project: numeric id or identifier slug. title: target wiki page title. text: new markdown body. Empty is rejected client-side. version: if non-zero, included as the optimistic-lock version. A mismatch surfaces as redmine_api_409 from Redmine. parent_title: optional new parent wiki page. comments: optional revision comment.

Returns the updated page (re-fetched after PUT for fresh metadata). Honors REDMINE_MCP_READ_ONLY.

Permanently delete a wiki page (and all its historical versions).

Args: project: numeric id or identifier slug. title: wiki page title.

Returns {"deleted": true, ...} on success or wiki_page_not_found. Honors REDMINE_MCP_READ_ONLY. No soft-delete in Redmine.

List all relations on an issue (both directions).

Args: issue_id: numeric Redmine issue id.

Each relation has id, issue_id, issue_to_id, relation_type, and delay. Read-only.

Create a relation between two issues.

Args: issue_id: source issue. target_issue_id: the other end of the relation. relation_type: one of relates, blocks, blocked, duplicates, duplicated, precedes, follows, copied_to, copied_from — or a recognized alias (related_to, blocked_by, duplicate_of, duplicated_by, copy_of). delay: only meaningful for precedes / follows — number of days between the issues' due dates. 0 to omit.

Honors REDMINE_MCP_READ_ONLY. Cross-project relations require Redmine's cross_project_issue_relations setting to be enabled.

Delete a relation by its numeric id.

Args: relation_id: id from list_relations output (NOT an issue id).

Honors REDMINE_MCP_READ_ONLY.

Set or clear an issue's parent.

Args: issue_id: issue whose parent is being set. parent_issue_id: numeric id of the new parent. Pass 0 to unparent the issue.

Parent/child is mechanically a field on the issue (parent_issue_id), not a relation record. Honors REDMINE_MCP_READ_ONLY.

Bulk-create issues with subject idempotency.

Args: issues: list of issue spec dicts (≤ 100 per call). Each spec requires project, tracker, subject; optional fields match redmine_create_issue (description, priority, status, assigned_to_id, difficulty, due_date, start_date, done_ratio, custom_fields). on_duplicate: "skip" (default) pre-checks each subject within its project and reports existing matches as skipped with duplicate_of; "fail" reports duplicates as failures; "create_anyway" skips the pre-check entirely. pacing_seconds: sleep between POSTs (default 50ms — empirically the floor for not tripping Redmine's per-issue rate cap on small VMs). Set 0 to disable. stop_on_error: True to bail at first failure; remainder lands in skipped_for_stop_on_error.

Returns {"results": [{subject, status, id?, duplicate_of?, error?, hint?}], "summary": {total, created, skipped, failed}}. Honors REDMINE_MCP_READ_ONLY.

Apply the same field updates to many issues in one call.

Args: issue_ids: list of numeric issue ids (≤ 100 per call). subject, description, status, priority, assigned_to_id, notes: same semantics as redmine_update_issue — at least one must be supplied. custom_fields: raw custom-field entries (list of {"id": N, "value": "..."} dicts). Merged into each issue's PUT. difficulty: convenience for the Difficulty custom field ("Unclassified" / "Easy" / "Normal" / "Hard"). held: True marks every issue as held. False (default) means unchanged. held_until: ISO-8601 date for the Held Until custom field. due_date: ISO-8601 date to set on every issue. start_date: ISO-8601 date to set on every issue. done_ratio: 0-100 progress percent; -1 (default) means unchanged. stop_on_error: if True, halt at the first failure (remaining ids land in skipped); otherwise best-effort across the whole batch.

Returns {total, succeeded, failed, skipped}. Honors REDMINE_MCP_READ_ONLY. Sequential — Redmine has no batch endpoint.

Close many issues in one call (with optional shared note).

Args: issue_ids: list of numeric issue ids (≤ 100 per call). note: optional shared closing comment (becomes a journal on each). stop_on_error: if True, halt on the first workflow-blocked or otherwise-failed closure.

Returns {total, succeeded, failed, skipped}. Honors REDMINE_MCP_READ_ONLY.

List all versions / milestones defined on a project.

Args: project: numeric id or identifier slug.

Each version has id, name, status (open/locked/closed), due_date, sharing, etc. Read-only.

Fetch one version by id.

Returns the version (name, status, due_date, sharing, ...) or version_not_found. Read-only.

Create a version on a project.

Args: project: numeric id or identifier slug. name: required, must be unique within the project. description: optional. status: one of open / locked / closed. due_date: YYYY-MM-DD. sharing: one of none / descendants / hierarchy / tree / system. wiki_page_title: optional linked wiki page.

Honors REDMINE_MCP_READ_ONLY.

Update a version. Partial — only supplied fields are sent.

Returns the refreshed version. Honors REDMINE_MCP_READ_ONLY.

Delete a version by id. Permanent — no soft-delete.

A 422 typically means the version is still referenced by issues; clear those first via redmine_assign_issue_to_version with version_id=0. Honors REDMINE_MCP_READ_ONLY.

Assign (or clear) an issue's target version.

Args: issue_id: numeric issue id. version_id: numeric version id; pass 0 to clear.

Thin wrapper over redmine_update_issue that sets fixed_version_id. Honors REDMINE_MCP_READ_ONLY.

List news entries (global feed, or scoped to a project).

Args: project: numeric id or identifier slug. Empty for the global feed across every project the API key can see. limit: page size (capped server-side at 100). offset: skip the first N results.

Returns {news, total_count, limit, offset, source}. Read-only.

List forum messages on a board.

Args: board_id: numeric Redmine board id (visible in the project's forums URL or via the web UI; redmine_request covers /projects/X/boards.json if the boards module is enabled). limit: page size (capped server-side at 100). offset: skip the first N results.

Returns {messages, total_count, limit, offset, board_id, source}. A 404 typically means the boards module isn't enabled on the parent project, or the board_id doesn't exist. Read-only.

List forum boards for a project.

Args: project_id: numeric id or identifier slug.

Returns {boards, count, project_id}. Read-only.

Create a new forum topic on a board.

Args: board_id: numeric board id. subject: required topic subject. content: optional message body.

Honors REDMINE_MCP_READ_ONLY.

Reply to an existing forum topic.

Args: board_id: board the topic belongs to. topic_id: the parent message/topic id. content: required reply body.

Honors REDMINE_MCP_READ_ONLY.

Delete a forum message. Permanent.

Honors REDMINE_MCP_READ_ONLY.

Create a news entry on a project.

Args: project: numeric id or identifier slug. title: required news title. summary: optional short summary. description: optional full body.

Honors REDMINE_MCP_READ_ONLY.

Update a news entry. Partial — only supplied fields are sent.

Honors REDMINE_MCP_READ_ONLY.

Delete a news entry. Permanent.

Honors REDMINE_MCP_READ_ONLY.

List project members (paginated).

Args: project_id: numeric id or identifier slug. limit: page size (capped at 100). offset: skip the first N results.

Read-only.

Add a member to a project.

Args: project_id: project id or slug. user_id: user or group id to add. role_ids: list of role ids to assign (required, non-empty).

Honors REDMINE_MCP_READ_ONLY.

Update a membership's roles.

Args: membership_id: numeric membership id (from list_memberships). role_ids: new list of role ids (required, non-empty).

Honors REDMINE_MCP_READ_ONLY.

Remove a project membership. Inherited memberships can't be deleted.

Honors REDMINE_MCP_READ_ONLY.

List all groups (admin only). Read-only.

Fetch a group by id.

Args: group_id: numeric group id. include: comma-separated includes: users, memberships.

Read-only.

Create a group (admin only).

Args: name: required group name. user_ids: optional list of user ids as initial members.

Honors REDMINE_MCP_READ_ONLY.

Update a group's name.

Honors REDMINE_MCP_READ_ONLY.

Delete a group (admin only). Permanent.

Honors REDMINE_MCP_READ_ONLY.

Add a user to a group.

Honors REDMINE_MCP_READ_ONLY.

Remove a user from a group.

Honors REDMINE_MCP_READ_ONLY.

List issue categories for a project.

Args: project_id: numeric id or identifier slug.

Read-only.

Create an issue category on a project.

Args: project_id: numeric id or identifier slug. name: required category name. assigned_to_id: optional default assignee. 0 for none.

Honors REDMINE_MCP_READ_ONLY.

Update an issue category. Partial.

Honors REDMINE_MCP_READ_ONLY.

Delete an issue category. Permanent.

Args: category_id: numeric category id. reassign_to_id: optional category id to reassign affected issues. 0 for no reassignment.

Honors REDMINE_MCP_READ_ONLY.

List enumeration values for a given type.

Args: enum_type: one of issue_priorities, time_entry_activities, document_categories.

Read-only reference data.

List all roles. Read-only.

Fetch a role by id, including its permissions list.

Read-only.

List all issue statuses with their is_closed flags.

Read-only reference data.

List all custom field definitions (admin only).

Returns id, name, field_format, customized_type, is_required, is_filter, possible_values, etc. Read-only.

List available saved queries.

Args: project_id: optional project id or slug to scope queries. Empty for all visible queries.

Use the returned query ids with redmine_search_issues(query_id=...) to execute them. Read-only.

List files on a project's Files section.

Args: project_id: numeric id or identifier slug.

Read-only.

Upload a file to a project's Files section.

Args: project_id: project id or slug. file_path: path to file (path-restricted like attachment upload). filename: optional override for the file name. description: optional file description. version_id: optional version to associate. 0 for none.

Honors REDMINE_MCP_READ_ONLY.

Fetch a user by id, or the current API user.

Args: user_id: numeric user id, or "current" (default) for the authenticated API user. include: comma-separated includes: memberships, groups. Empty for none.

Read-only.

List users (admin only).

Args: name: filter by login, firstname, lastname, or mail. group_id: filter by group membership. 0 for no filter. status: filter by user status. -1 (default) for no filter. Values: 0 anonymous, 1 active, 2 registered, 3 locked. limit: page size (capped at 100). offset: skip the first N results.

Read-only. Requires admin privileges.

Full-text search across all Redmine resource types.

Searches issues, wiki pages, news, changesets, messages, projects, and documents. Complements redmine_search_issues which only covers issues with structured filters.

Args: query: search string (required, non-empty). project: optional project id or slug to scope the search. Empty for global search. resource_types: optional list of resource types to include (e.g. ["issues", "wiki_pages"]). Empty searches all. Allowed: issues, news, documents, changesets, wiki_pages, messages, projects. all_words: if True (default), match all words; if False, any. titles_only: if True, only search titles. open_issues: if True, only return open issues (ignored for other resource types). attachments: "0" (description only), "1" (description + attachments), "only" (attachments only). limit: page size (capped at 100). offset: skip the first N results.

Returns {results, total_count, limit, offset}.

ESCAPE HATCH — generic passthrough to any Redmine REST endpoint.

Bypasses redmine-mcp's validation, workflow checks, and schema cache. Every response carries validation_skipped: true so the caller can't accidentally forget. Gated behind REDMINE_MCP_ENABLE_PASSTHROUGH=true — calls return passthrough_disabled if the flag isn't set.

Args: method: HTTP verb. One of GET, POST, PUT, DELETE, PATCH. Case-insensitive. path: must start with /. Joined onto REDMINE_URL by the client. Example: "/custom_fields.json". body: body for POST/PUT/PATCH. Accepted as either a JSON-encoded string (e.g. '{"issue": {"subject": "renamed"}}') or a JSON object passed directly (e.g. {"issue": {"subject": "renamed"}}). Empty string / empty dict means no body. (The dual form is intentional — some MCP transports auto-parse JSON-shaped string args into objects before the tool sees them.) params: query params for GET, in the same dual string/object form.

Honors REDMINE_MCP_READ_ONLY for non-GET methods.