Deutsche Version

Back to overview

osTicket MCP Server: Tools

This documentation always describes the latest published version.

The server provides 12 tools. All names carry the prefix osticket_. Successful calls return JSON as text. Errors come back with the error flag set and a line of the form Error: <action> - <hint>, see Troubleshooting.

Overview

In addition, osticket_update_ticket queries the status list through GET /api/tickets-statuses.php when you pass a status name (can_read_stats or can_read_tickets). At startup the server calls GET /api/tickets-stats.php for its health check.

You set the permissions in the osTicket admin panel under Manage → Plugins → API Endpoints → Configure, see the plugin configuration. The subticket tools additionally need the plugin Subticket Manager.

Ticket numbers are strings of 1 to 20 digits in all tools, for example "680284".

osticket_get_ticket

Fetches a ticket with thread, user, staff member and attachment metadata.

If both are given, number wins. Returns { "ticket": { ... } } with the plugin's object.

The server sends an id as a ticket number. The plugin first looks for a ticket with that number and only then falls back to the internal ID. If another ticket happens to carry that number, you get that one.

osticket_list_tickets

Lists ticket summaries without thread.

Returns tickets, count, offset, has_more and, when there are more pages, next_offset. has_more is true when exactly limit entries came back. The tool does not return a total count. If the response was shortened because of the character limit, truncated and truncation_message are included.

The parameter departmentId exists in the tool but does not filter. The server sends it as the query parameter departmentId, while the plugin only reads department. The list therefore comes back unfiltered. Do not rely on this tool to filter by department for now.

The plugin also ignores a status name that matches no status of the instance and then does not filter at all. If a list is unexpectedly large, check the numbers with osticket_get_stats.

osticket_search_tickets

Searches the ticket subject.

Returns tickets, count, total, query and has_more. total is the number of returned hits, not the number of all hits in osTicket. The tool has no offset.

osticket_get_stats

No parameters. Returns { "statistics": { ... } } with the plugin's values: total, open, closed, overdue, by_department and by_staff.

osticket_create_ticket

Creates a ticket through the endpoint /api/wildcard/tickets.json.

If both name and OSTICKET_DEFAULT_NAME are missing, the tool aborts with an error message. The same applies to the email address. The server always sends alert=false and autorespond=false: neither the team nor the sender gets a notification from osTicket.

Returns success, ticketNumber, projectContext (or null), attachments with a summary when files were attached, and message.

The tool text instructs Claude to ask for the project when none is given. The code does not enforce this: without projectContext the ticket is created without a project line.

osticket_update_ticket

Changes ticket properties and can add an internal note.

Only the status is resolved in the server: a name is compared against the osTicket status list, ignoring case, and the list is cached for 5 minutes. A string that starts with a number is treated as an ID. Department, help topic, staff member and SLA must be passed as a number or a numeric string. A name leads to an error.

The schema requires number plus at least one more field, but noteFormat has a default value and therefore always counts as set. A call with only number is not rejected and changes nothing on the ticket.

Returns success, ticket (osTicket's response, which according to the plugin documentation is the ticket number), attachments when files were attached, and message.

osticket_delete_ticket

Deletion is permanent. The ticket and its thread disappear from the database. The permission can_delete_tickets is off by default for every key in the plugin. Moving the ticket to a closed status with osticket_update_ticket is usually the better choice.

Returns success and message.

osticket_get_parent_ticket

Returns success, parent (with ticket_id, number, subject, status, or null without a parent) and message.

osticket_get_child_tickets

Returns success, children (list with ticket_id, number, subject, status), total and message.

osticket_create_subticket_link

Makes an existing ticket the child of another. The server sends the child number as childId.

Returns success, parent, child and message. The plugin rejects linking a ticket to itself with 400, and an existing link or a child with a different parent with 422.

osticket_unlink_subticket

Returns success, child and message. If the ticket has no parent, the plugin answers with 404.

osticket_download_attachment

Downloads an attachment and saves it to the operating system's temporary directory.

Returns success, filePath, filename, size and mime_type. The file name is <8 hex characters>_<file name>, with every character other than letters, digits, dot, underscore and hyphen replaced by _. The server does not delete the file again. osTicket's response contains the file Base64-encoded and may be at most 10 MB, so files from roughly 7.5 MB fail.