nks-osticket-mcp

nks-osticket-mcp is an MCP server that lets an AI assistant work with tickets in the osTicket helpdesk. Over time a helpdesk on osTicket fills up with tickets that repeat: the same question, the same answer, the same move to another status. nks-osticket-mcp lets you hand this work to an AI assistant: through it, Claude or any other agent with MCP support lists and searches tickets, reads the whole thread, replies to the customer by email, adds an internal note, changes the status, links related tickets and downloads or attaches a file.

Why osTicket needed its own API

The built-in osTicket API is designed to receive tickets from other systems: a key in a stock installation can only create tickets and run cron. You cannot read tickets, reply to them or change their status through it. That is why the server is built on the nks-osticket-plugin add-on, which adds a single JSON endpoint to osTicket with a full set of ticket actions. The MCP server translates it into terms a language model understands: 14 tools with documented parameters, which the agent calls on its own depending on what it needs to do.

What the agent gets

The whole ticket with its history

osticket_get_ticket returns a ticket with its complete message thread. Each thread entry also lists attachments with their ID, name, type and size, so the agent knows what the customer sent, and osticket_download_attachment downloads the file as base64. The list can be filtered by status and department and paged; search works on the ticket subject.

A reply that is actually sent

osticket_reply_ticket sends the reply to the customer by email, not just as an entry in the thread. The replyTo parameter sets who receives it: everyone, only the requester, or only the other participants. With staffId, both the reply and the internal note are recorded under a specific osTicket agent, so the signature, sender name and automatic ticket assignment all match. The customer gets a reply with the same name and signature as from anyone else on the team.

Attachments from disk

Since version 1.2.0 files can be attached to a reply. The agent passes a path, the server reads the file from its own disk, guesses the MIME type from the extension (jpg, png, gif, webp, pdf, txt, otherwise a generic binary type) and sends it encoded. If the file does not exist, the reply is not sent and the agent gets a read error. The size of each file is limited by the osTicket settings.

Order among related tickets

Four tools work with parent and child tickets: linking, unlinking, listing children and finding the parent. The agent can put ten reports of the same fault under one main ticket. Statistics return the counts of all, open, closed and overdue tickets.

Failures you can read

A request that osTicket does not answer within 30 seconds ends with code 504, a network failure with code 502, and API errors come back with the code and message from osTicket. The agent can tell whether to retry or whether a permission is missing. For test installations with a self-signed certificate, TLS verification can be turned off.

How to set it up

{
  "mcpServers": {
    "osticket": {
      "command": "node",
      "args": ["/absolute/path/to/nks-osticket-mcp/dist/index.js"],
      "env": {
        "NKS_OSTICKET_URL": "https://support.example.com/api/nks-osticket.php",
        "NKS_OSTICKET_API_KEY": "your-api-key"
      }
    }
  }
}

The server runs as a child process of the client over standard input and output and is configured only through environment variables: the add-on endpoint URL, the osTicket API key, and optionally a timeout in milliseconds and certificate verification. The API key is created in the osTicket admin, is bound to the IP address the server runs from, and carries only the permissions the administrator grants it. An agent with a key that has no delete permission cannot delete a ticket, even if someone asks it to.

Where it helps

• Sorting the morning queue: the agent goes through new tickets, answers the repeated questions and adds an internal note with a summary for a person to the rest.
• A reply with supporting material: the agent prepares instructions or a screenshot and sends it to the customer as an attachment right in the thread.
• A service outage: reports from different customers are linked under one main ticket and answered all at once after the fix.
• A summary for management: counts of open and overdue tickets without an export from the admin.

Project status

Version 1.0.0 was released on 5 July 2026 with 14 tools; 1.1.0 followed two days later and added attachment details to the thread. The latest release, 1.2.0 from 28 October 2026, added attachments to replies and the choice of agent and recipients. Attachments need the add-on in version 1.3.0 or later. The project has no automated tests yet; the checks are type checking and the build.

Getting started

git clone https://github.com/nks-hub/nks-osticket-mcp.git
cd nks-osticket-mcp
npm install
npm run build

You need Node.js 18 or later, osTicket with the nks-osticket-plugin add-on installed and an API key with the required permissions. There is no npm package; the server is built from the repository and the client configuration points to dist/index.js. The Releases contain only change notes, not a prebuilt package.

Source code

The code is on GitHub in the nks-hub/nks-osticket-mcp repository under the MIT licence, written in TypeScript 5 on top of the official MCP SDK. Changes by version are described in CHANGELOG.md.