MCP tools reference

• Principles
• Context and lookups
• Issues
• Time tracking
• Wiki
• Files and attachments
• Project management and news
• Reports
• Tools of other RedmineUP plugins
• Not included

The list of tools of the Agent MCP server and how to use them.

Mode is sent to the client as tool annotations: read = readOnlyHint, write = additive write, destructive = can change or delete existing data (all manage_* tools). Clients can use it to decide which tools to confirm.

Principles

Names. Verb first: list_ (filter a collection), search_ (full text), get_ (one record by id), create_, update_, delete_, save_, rename_, and manage_ (several actions chosen with action, for example manage_version with create, update, delete).

Projects. project is an identifier or a numeric id. Valid trackers, statuses, priorities, categories and custom fields of a project come from one call, get_project_metadata; use it before create_issue.

Find things.

• To list: list_issues, list_projects, list_versions, list_time_entries with filters (for example status, assigned_to: "me", version_id, from and to dates).
• To find by words in any project: search_redmine (issues, wiki pages, news; type narrows it).
• To reuse a saved filter: list_queries, then list_issues with query_id.
• Plugin lists (contacts, deals, invoices…) take a search string and an optional project.

Pages. Every list_* tool takes limit (1–100, default 25; 0 returns only total_count) and offset. The answer contains total_count, offset and limit; request the next page with offset += limit.

Save tokens: fields and compact. List tools take

• fields: the columns to return, for example ["id","subject","status"] (id is always returned; "-description" excludes a column). An unknown name is an error.
• compact: true: columns are sent once and rows as arrays, repeated {id, name} values go to a refs table: {"columns": [...], "rows": [[...]], "refs": {...}}. Use it for big lists.

One record. get_* tools return the full REST record. get_issue takes include (journals, attachments, relations, children; all by default): ask only for what you need.

Writes. update_* tools change only the arguments that are given. custom_fields are [{"id": 1, "value": "x"}] (the REST format); fields the user cannot edit are ignored by Redmine. Delete tools and manage_* tools are marked destructive; delete_issue returns only the impact, and manage_news with delete refuses, until confirm: true is passed.

Files. Upload with create_upload (base64 content, up to 5 MB) and pass the returned token in uploads: [{"token": "...", "filename": "a.png"}] to create_issue, update_issue, add_note (and the same argument of plugin tools). Read files with read_attachment.

Rights. A tool exists for a client only when the token scopes and the user's roles grant the permission in the Needs column (any of those listed). Plugin tools appear only when the plugin is installed. tools/list is always the definitive list with JSON schemas.

Context and lookups

Tool	Needs	Mode	Description
get_current_user	any user	read	the authenticated user with the server and Redmine versions
list_projects	any user	read	projects you can access
get_project_metadata	view_project	read	trackers, statuses, priorities, categories, time activities, modules and issue custom fields of a project, with ids, in one call
list_users	administrator	read	active users; filter by name or group_id
list_members	view_members	read	project members with roles
list_roles	any user	read	assignable roles with ids
list_versions	view_issues	read	shared and project versions
list_queries	view_issues	read	saved issue queries you can see (use the id as query_id)
search_redmine	search_project	read	full-text search in all visible projects or in one; type narrows to issues, wiki_pages, news…

Issues

Tool	Needs	Mode	Description
list_issues	view_issues	read	filter by project, status (open by default, closed, * or id), assigned_to (me or id), tracker_id, version_id, subject, parent_id, query_id, sort (e.g. updated_on:desc)
get_issue	view_issues	read	an issue with custom fields, journals, attachments, relations and children; private notes need view_private_notes
create_issue	add_issues	write	create an issue (subject, description, tracker, status, priority, assignee, version, dates, custom fields, uploads…)
update_issue	edit_issues or add_issue_notes	write	change fields and optionally add a note
add_note	add_issue_notes	write	add a comment and/or files
delete_issue	delete_issues	destructive	delete an issue; without confirm=true only the impact is returned
manage_issue_note	edit_issue_notes or edit_own_issue_notes	destructive	edit the text or privacy of a note
manage_issue_relation	manage_issue_relations	destructive	action: list, create (issue_to_id, relation_type, delay), delete (relation_id)
manage_issue_watcher	add_issue_watchers or delete_issue_watchers	destructive	action: add or remove (user_id)
manage_issue_category	manage_categories	destructive	action: list, create, update, delete issue categories

There is no copy tool: a client copies an issue with get_issue and create_issue.

Time tracking

Tool	Needs	Mode	Description
list_time_entries	view_time_entries	read	filter by project, issue_id, user_id (me or id), from, to (YYYY-MM-DD)
log_time	log_time	write	log hours on an issue or project (activity_id, comments, spent_on; user_id logs for another user)
update_time_entry	edit_time_entries or edit_own_time_entries	destructive	update a time entry by id

Wiki

Tool	Needs	Mode	Description
list_wiki_pages	view_wiki_pages	read	titles of the wiki pages of a project
get_wiki_page	view_wiki_pages	read	a page by title, optionally an older version
list_wiki_page_versions	view_wiki_edits	read	versions of a page
save_wiki_page	edit_wiki_pages	destructive	create or update a page; pass version from get_wiki_page to detect concurrent edits; parent is a parent page title
rename_wiki_page	rename_wiki_pages	destructive	rename a page; links to the old title are redirected

Files and attachments

Tool	Needs	Mode	Description
read_attachment	view_issues	read	an attachment of an issue, a ticket or a reply: text and .eml are truncated to 100 KB, other files returned as content_base64 up to 5 MB
create_upload	add_issues, edit_issues or add_issue_notes	write	upload a file (content_base64, up to 5 MB) and get a token for uploads
list_files	view_files	read	files of the project Files section, including version files
upload_file	manage_files	write	upload a file to the project Files section, optionally under a version
delete_file	manage_files or edit_issues	destructive	delete an attachment by id (a project file or an issue attachment)

Project management and news

Tool	Needs	Mode	Description
manage_project	add_project, edit_project or close_project	destructive	action: create, update, close, reopen
manage_project_member	manage_members	destructive	action: add (user_id, role_ids), update, remove (member_id)
manage_version	manage_versions	destructive	action: create, update, delete a version
list_news	view_news	read	news, optionally of one project
get_news	view_news	read	a news item with comments and attachments
manage_news	manage_news	destructive	action: create, update, delete (delete needs confirm=true)

Reports

Tool	Needs	Mode	Description
get_gantt_chart	view_gantt	read	issues with dates, relations and version milestones of a project; filter by from and to
summarize_project_status	view_issues	read	issue counts by status, tracker and priority, overdue and recent activity, version progress (days)

Tools of other RedmineUP plugins

These plugins add tools to the same server with the same rules. Each plugin article has the details and examples.

Plugin	Tools
CRM	list_contacts, get_contact, create_contact, update_contact, delete_contact, list_deals, get_deal, create_deal, update_deal, delete_deal, list_crm_notes, add_crm_note, update_crm_note, delete_crm_note
Helpdesk	list_helpdesk_tickets, get_helpdesk_ticket, create_helpdesk_ticket, send_helpdesk_reply
Invoices	list_invoices, get_invoice, create_invoice, update_invoice, delete_invoice, list_invoice_payments, create_invoice_payment, list_invoice_templates, get_invoice_template, create_invoice_template, update_invoice_template, delete_invoice_template
Products	list_products, get_product, create_product, update_product, delete_product, list_product_categories, get_product_category, list_orders, get_order, create_order, update_order, delete_order
Agile	list_agile_sprints, manage_agile_sprint, get_issues_timeline; story_points, agile_sprint_id, agile_color in create_issue / update_issue
Zenedit	list_issue_viewers, manage_issue_draft
Tags	tag_list, add_tag_list, remove_tag_list in create_issue / update_issue, tags in get_issue
Checklists	checklists_attributes in create_issue / update_issue, checklists in get_issue

Not included

There is no batch tool and no generic REST tool: clients call tools in parallel, and for a resource without a tool they use the Redmine REST API directly.