NKS osTicket MCP

A Model Context Protocol server for osTicket. It lets AI agents such as Claude list, search, read, create, update, reply to and delete tickets, plus read stats, manage parent/child subtickets and download attachments.

It talks to the companion NKS osTicket API plugin, which exposes a single JSON endpoint inside osTicket.

---

Features

• 🎫 Ticket CRUD - List, search, read, create, update and delete tickets from an AI agent
• 💬 Replies and notes - Customer-facing replies (emailed) and internal notes, optionally posted as a specific agent (staffId) and with selectable recipients (replyTo)
• 📊 Stats and statuses - Total, open, closed and overdue counts; list of all ticket statuses
• 🌳 Subtickets - Link, unlink and browse parent/child tickets
• 📎 Attachments - Thread entries list their attachments; download any of them as base64
• ⏱️ Error reporting - Requests time out after 30 s by default (504), network failures return 502, and API errors come back to the agent with osTicket's code and message; self-signed TLS can be allowed
• 🧩 14 tools - One MCP server over stdio, configured by environment variables

Requirements

• Node.js 18 or later
• The NKS osTicket API plugin installed on your osTicket instance
• An osTicket API key (Admin → Manage → API Keys) with the permissions your tools need, bound to the source IP this server runs from

Installation

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

Configuration

Set via environment variables (see .env.example):

| Variable | Required | Default | Description | |---|---|---|---| | NKS_OSTICKET_URL | yes | – | URL of the API entry, …/api/nks-osticket.php | | NKS_OSTICKET_API_KEY | yes | – | osTicket API key | | NKS_OSTICKET_TIMEOUT_MS | no | 30000 | Request timeout in ms | | NKS_OSTICKET_REJECT_UNAUTHORIZED | no | true | false allows self-signed TLS |

Usage

Claude Code / Claude Desktop

Add to your MCP server configuration:

{
  "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"
      }
    }
  }
}

Tools

| Tool | Purpose | |---|---| | osticket_list_tickets | List tickets (filter by status/department, paginated) | | osticket_search_tickets | Full-text search by subject | | osticket_get_ticket | One ticket with full message thread | | osticket_get_stats | Total / open / closed / overdue counts | | osticket_list_statuses | All ticket statuses | | osticket_create_ticket | Create a ticket | | osticket_update_ticket | Change status / due date / topic, add internal note (optionally as agent staffId) | | osticket_reply_ticket | Post a customer-facing reply (emailed; optional staffId and replyTo: all, user, collabs) | | osticket_delete_ticket | Delete a ticket (irreversible) | | osticket_link_subticket | Link child under parent | | osticket_unlink_subticket | Remove a child's parent link | | osticket_get_children | List a parent's children | | osticket_get_parent | Get a child's parent | | osticket_download_attachment | Download an attachment (base64) |

Development

npm run dev          # run from source with tsx
npm run type-check   # tsc --noEmit
npm run build        # compile to dist/
npm start            # run the compiled server

The project has no automated test suite yet; npm run type-check and npm run build are the checks. Changes are listed in CHANGELOG.md.

Contributing

Contributions are welcome! For major changes, please open an issue first.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: description')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

• 📧 Email: dev@nks-hub.cz
• 🐛 Bug reports: GitHub Issues

License

MIT License — see LICENSE for details.

---

<p align="center"> Made with ❤️ by <a href="https://github.com/nks-hub">NKS Hub</a> </p>