osTicket MCP Server

The most complete osTicket MCP — 37 tools, zero plugins.

Manage tickets, tasks, users, and organizations from Claude Code, Cursor, Windsurf, or any MCP client.

No API keys. No server modifications. Works with any osTicket v1.18+.

> show me the open tickets
> create a ticket for [email protected] about login issues
> reply to ticket 32 saying we're investigating
> assign it to Sarah and transfer to Sales
> create a follow-up task: "Call client next week"
> list all organizations
> close all automated notification tickets

Why this project?

osTicket doesn't have a usable public API. Existing MCP solutions require installing PHP plugins on your server.

This MCP server reverse-engineers the staff panel — using the same session-based auth as the web UI. It works out of the box with any osTicket installation. No plugins, no API keys, no server modifications.

vs other osTicket MCPs

| Feature | mcp-osticket | Plugin-based MCPs | |---------|:---:|:---:| | Install on server required | No | Yes (PHP plugins) | | Ticket CRUD | 13 tools | 7 tools | | Internal Tasks | 8 tools | 0 | | User management | 5 tools | 0 | | Organizations | 5 tools | 0 | | Search & stats | 6 tools | 2 tools | | Auto session recovery | Yes | N/A | | Total tools | 37 | ~9 |

Quick Start

1. Install

npm install -g mcp-osticket

That's it. No build step, no dependencies to install separately.

2. Configure your editor

Add to your MCP client config:

{
  "mcpServers": {
    "osticket": {
      "command": "mcp-osticket",
      "env": {
        "OSTICKET_URL": "https://helpdesk.example.com",
        "OSTICKET_EMAIL": "[email protected]",
        "OSTICKET_PASSWORD": "your-password"
      }
    }
  }
}

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "osticket": {
      "command": "npx",
      "args": ["-y", "mcp-osticket"],
      "env": {
        "OSTICKET_URL": "https://helpdesk.example.com",
        "OSTICKET_EMAIL": "[email protected]",
        "OSTICKET_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "osticket": {
      "command": "mcp-osticket",
      "env": {
        "OSTICKET_URL": "https://helpdesk.example.com",
        "OSTICKET_EMAIL": "[email protected]",
        "OSTICKET_PASSWORD": "your-password"
      }
    }
  }
}

{
  "mcpServers": {
    "osticket": {
      "command": "mcp-osticket",
      "env": {
        "OSTICKET_URL": "https://helpdesk.example.com",
        "OSTICKET_EMAIL": "[email protected]",
        "OSTICKET_PASSWORD": "your-password"
      }
    }
  }
}

3. Use

Restart your editor. The tools are available immediately — just ask in natural language.

Tools

Tickets (13 tools)

| Tool | Description | |------|-------------| | list_tickets | List tickets by queue with pagination (open, my, closed) | | get_ticket | Full ticket detail with complete conversation thread | | create_ticket | Create a new ticket on behalf of a user | | reply_ticket | Reply with email control (all, user, or none) | | add_note | Add an internal note (not visible to the end user) | | edit_ticket | Edit ticket fields (subject, due date, custom fields) | | change_ticket_status | Change status: open, resolved, or closed | | assign_ticket | Assign to a staff member | | transfer_ticket | Transfer to another department | | claim_ticket | Self-assign an unassigned ticket | | mark_ticket | Mark as answered or unanswered | | merge_tickets | Merge multiple tickets into one | | delete_ticket | Permanently delete a ticket |

Tasks (8 tools)

Internal work items for agents — different from user-facing tickets.

| Tool | Description | |------|-------------| | list_tasks | List tasks (open or closed) | | get_task | Full task detail with thread | | create_task | Create a new internal task | | assign_task | Assign task to an agent | | transfer_task | Transfer task to a department | | close_task | Close a task | | reopen_task | Reopen a closed task | | add_task_note | Add a note to a task |

Users (5 tools)

| Tool | Description | |------|-------------| | search_users | Search by name or email | | get_user | Get detailed user info | | create_user | Create a new user | | update_user | Update user information | | delete_user | Delete a user |

Organizations (5 tools)

| Tool | Description | |------|-------------| | list_organizations | List all organizations | | search_organizations | Search by name | | get_organization | Get organization details | | create_organization | Create a new organization | | delete_organization | Delete an organization |

System (6 tools)

| Tool | Description | |------|-------------| | list_agents | List available staff members | | list_departments | List departments | | list_help_topics | List help topics (for ticket creation) | | search_tickets | Search by keyword, number, or email | | get_queue_counts | Ticket counts per queue | | get_dashboard_stats | Dashboard statistics and metrics |

Examples

Triage your inbox:

> list open tickets page 2 and summarize them by priority

Create and manage tickets:

> create a ticket for [email protected] about "Can't access dashboard", assign to Sales
> reply to ticket 15 with "Fixed in latest deploy" but don't send an email

Internal tasks:

> create a task "Follow up with client about renewal" assigned to Felipe
> list open tasks and close the completed ones

User and org management:

> create a user "John Smith" with email [email protected]
> create organization "Acme Corp"
> find all users with @acme.com emails

Bulk operations:

> close all automated notification tickets
> list tickets from page 1 to 3 and summarize

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OSTICKET_URL | Yes | Base URL of your osTicket instance | | OSTICKET_EMAIL | Yes | Staff agent email for login | | OSTICKET_PASSWORD | Yes | Staff agent password |

How It Works

This server authenticates as a staff agent through osTicket's web panel:

• Session auth — logs in via /scp/login.php, maintains session cookie
• Auto-relogin — detects session expiry and re-authenticates automatically
• CSRF handling — extracts and refreshes CSRF tokens on every request
• Ticket locking — acquires locks before write operations (reply, note)
• Dynamic forms — handles osTicket's per-session hashed field names
• AJAX endpoints — uses /scp/ajax.php/* for assign, transfer, status, tasks
• HTML scraping — parses data from the staff panel using Cheerio
• i18n support — works with English and Spanish osTicket installations

No osTicket plugins, API keys, or server modifications required.

Security

• Credentials are passed via environment variables, never stored
• Session cookies are kept in memory only
• CSRF tokens are refreshed on every request
• The MCP server runs locally — it never exposes your osTicket credentials to third parties
• Uses the same authentication as logging into the web panel

Known limitations:

• Scraping-based approach may break if osTicket significantly changes its HTML structure
• One concurrent session per MCP instance (no parallel requests)
• Some operations (edit, delete org) may not work on all osTicket configurations

Compatibility

| osTicket Version | Status | |------------------|--------| | v1.18.x | Tested (64 integration tests) | | v1.17.x | Should work (not verified) | | v1.15-1.16 | May work with minor differences |

Integration Tests

64 tests covering all 37 tools. Run against a live osTicket instance:

OSTICKET_URL=http://your-osticket \
[email protected] \
OSTICKET_PASSWORD=secret \
npm test

Tests create their own data and clean up after — they never touch existing tickets.

Roadmap

• [x] Ticket CRUD (create, read, reply, note, edit, delete)
• [x] Ticket operations (assign, transfer, claim, mark, merge, status)
• [x] Internal tasks management
• [x] User CRUD
• [x] Organization management
• [x] Pagination support
• [x] Auto session recovery
• [x] 64 integration tests
• [ ] Canned responses (predefined replies)
• [ ] Knowledge Base / FAQ search
• [ ] Ticket export (PDF/CSV)
• [ ] Bulk operations (mass close, mass assign)
• [ ] Webhook/notification support

Contributing

PRs welcome. The main files:

• src/osticket-client.ts — osTicket HTTP client (session, scraping, AJAX)
• src/mcp-server.ts — MCP tool definitions (37 tools)
• src/test-integration.ts — 64 integration tests

License

MIT — Tecnologica Chile