¶ osTicket MCP Server
¶ Table of Contents
¶ Overview
The osTicket MCP Server enables Claude to interact directly with your osTicket instance through the REST API. Manage support tickets without leaving your development environment.
Model Context Protocol (MCP) is an open protocol that enables AI assistants like Claude to interact with external tools and services. This MCP server provides 11 tools for complete osTicket ticket management including subticket relationships.
What makes this MCP server essential:
- ❌ Without MCP: Switch between osTicket UI and Claude Code, copy ticket details manually
- ❌ Without MCP: No automated ticket updates, time-consuming manual work
- ✅ With MCP: Manage tickets directly from Claude, full context while developing, automated workflows
¶ Key Features
- ✅ Get Tickets - Retrieve complete tickets with all messages
- ✅ List Tickets - List tickets with filters (status, department, pagination)
- ✅ Search Tickets - Full-text search across ticket subjects and numbers
- ✅ Statistics - Get aggregated ticket stats (total, open, closed, overdue)
- ✅ Create Tickets - Create new tickets with Markdown support
- ✅ Update Tickets - Modify ticket properties (status, department, assignee, etc.)
- ✅ Delete Tickets - Permanently delete tickets
- ✅ Subticket Management - Create and manage parent-child ticket relationships
- ✅ MCP Protocol Compliant - Works with Claude Desktop, Claude CLI, and other MCP clients
- ✅ Smart ID Resolution - Use names instead of IDs (status, department, topic, SLA, staff)
¶ Use Cases
- Automated Support Ticket Management - List, search, update tickets without leaving Claude
- Context-Aware Development - Access ticket details while coding fixes
- Ticket Creation from Code Issues - Create tickets with technical details in Markdown
- Batch Operations - Update multiple tickets efficiently
- Hierarchical Ticket Organization - Manage complex issues with parent-child ticket relationships
¶ Requirements
| Requirement | Version | Notes |
|---|---|---|
| Node.js | 18+ | Recommended: Node.js 20 LTS for best compatibility |
| npm | 9+ | Or pnpm 8+ / yarn 3+ |
| Claude Desktop | Latest | Or Claude CLI / other MCP-compatible client |
| osTicket | 1.18.x | With REST API enabled |
| API Endpoints Plugin | Latest | Required for extended API operations |
| Subticket Manager Plugin | Latest | Required for subticket management tools |
¶ Installation
¶ Step 1: Install API Endpoints Plugin
⚠️ This MCP server requires the API Endpoints Plugin installed on your osTicket instance.
cd /path/to/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-plugins.git
ln -s osticket-plugins/api-endpoints api-endpoints
# Enable in osTicket Admin Panel
# Admin Panel → Manage → Plugins → API Endpoints → Click "Enable"
¶ Step 1b: Install Subticket Manager Plugin (Optional but Recommended)
⚠️ For subticket management features, you must install the Subticket Manager Plugin.
cd /path/to/osticket/include/plugins
ln -s osticket-plugins/subticket-manager subticket-manager
# Enable in osTicket Admin Panel
# Admin Panel → Manage → Plugins → Subticket Manager → Click "Enable"
Without this plugin, the following tools will return HTTP 501 errors:
get_parent_ticketget_child_ticketscreate_subticket_linkunlink_subticket
¶ Step 2: Install MCP Server
# Create MCP server directory
mkdir -p ~/.claude/mcp-servers/osticket
# Clone repository
git clone https://github.com/markus-michalski/claude-mcp-osTicket.git ~/.claude/mcp-servers/osticket
# Install dependencies
cd ~/.claude/mcp-servers/osticket
npm install
# Build TypeScript
npm run build
¶ Step 3: Create osTicket API Key
- Login to osTicket Admin Panel
- Navigate to Admin Panel → Manage → API Keys
- Click Add New API Key
- Configure:
- IP Address:
- Without api-key-wildcard plugin: Enter your server's specific IP
- With api-key-wildcard plugin: Can use
0.0.0.0
- Enable API: ✅ Yes
- Can Create Tickets: ✅ Yes
- IP Address:
- Click Add Key and copy the generated API key
¶ Step 4: Configure API Endpoints Plugin Permissions
- Navigate to Admin Panel → Manage → Plugins
- Find API Endpoints → Click Configure
- Select your API key from dropdown
- Check required permissions:
- ✅
can_read_tickets - ✅
can_search_tickets - ✅
can_update_tickets - ✅
can_delete_tickets - ✅
can_read_stats - ✅
can_manage_subtickets(if Subticket Manager Plugin is installed)
- ✅
- Click Save
¶ Step 5: Configure Environment Variables
Create .env file:
cd ~/.claude/mcp-servers/osticket
cp .env.example .env
Edit .env:
# Required
OSTICKET_API_URL=https://tickets.example.com
OSTICKET_API_KEY=YOUR_API_KEY_HERE
OSTICKET_API_REJECT_UNAUTHORIZED=false # true for production with valid SSL
# Optional defaults for ticket creation
OSTICKET_DEFAULT_NAME=Claude AI
OSTICKET_DEFAULT_EMAIL=claude@example.com
OSTICKET_DEFAULT_TOPIC_ID=1
# Logging
LOG_LEVEL=info # debug, info, warn, error
¶ Step 6: Add to Claude Desktop
Edit ~/.claude/config.json (or Claude Desktop config):
{
"mcpServers": {
"osticket": {
"command": "node",
"args": ["/Users/yourname/.claude/mcp-servers/osticket/dist/index.js"]
}
}
}
Note: The .env file is automatically loaded by the server.
¶ Step 7: Restart Claude
Restart Claude Desktop or Claude CLI. Verify with /mcp - you should see "osticket" with status "✓ connected".
¶ Configuration
¶ Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
OSTICKET_API_URL |
✅ Yes | - | Base URL of your osTicket instance |
OSTICKET_API_KEY |
✅ Yes | - | API key for authentication |
OSTICKET_API_REJECT_UNAUTHORIZED |
❌ No | false |
Validate SSL certificates (set to true for production) |
OSTICKET_DEFAULT_NAME |
❌ No | - | Default user name for ticket creation |
OSTICKET_DEFAULT_EMAIL |
❌ No | - | Default user email for ticket creation |
OSTICKET_DEFAULT_TOPIC_ID |
❌ No | - | Default help topic ID for ticket creation |
LOG_LEVEL |
❌ No | info |
Logging level: debug, info, warn, error |
¶ Usage
¶ Basic Commands
In Claude Desktop/CLI, you can now use:
"Show me all open tickets"
"Search for tickets about Dashboard Widget"
"Get ticket #123456"
"Create a ticket about the bug I just found"
"Update ticket #123456 to Closed"
"Show me all child tickets of #123456"
"Link ticket #234567 as child of #123456"
The MCP server automatically handles API calls and returns formatted results.
¶ Example Workflow
Search and fix bug:
You: "Search osTicket for tickets about Dashboard Widget"
Claude: *Searches via search_tickets*
Found 3 tickets:
- #123456 "Dashboard Widget not loading" (Open)
- #234567 "Widget shows wrong data" (Open)
- #345678 "Widget performance issue" (Closed)
You: "Show me ticket #123456 in detail"
Claude: *Retrieves via get_ticket*
Displays complete ticket with all messages
You: "I found the issue. Update to In Progress and assign to me"
Claude: *Updates via update_ticket*
✅ Ticket #123456 updated
¶ Available Tools
¶ Tool Overview
| Tool | Description | Required Permission | Plugin Required |
|---|---|---|---|
get_ticket |
Get single ticket with all messages | can_read_tickets |
API Endpoints |
list_tickets |
List tickets with filters | can_read_tickets |
API Endpoints |
search_tickets |
Full-text search | can_search_tickets |
API Endpoints |
get_ticket_stats |
Get ticket statistics | can_read_stats |
API Endpoints |
create_ticket |
Create new ticket | can_create_tickets (native) |
- |
update_ticket |
Update ticket properties | can_update_tickets |
API Endpoints |
delete_ticket |
Delete ticket permanently | can_delete_tickets |
API Endpoints |
get_parent_ticket |
Get parent of subticket | can_manage_subtickets |
API Endpoints, Subticket Manager |
get_child_tickets |
Get list of child tickets | can_manage_subtickets |
API Endpoints, Subticket Manager |
create_subticket_link |
Create parent-child relationship | can_manage_subtickets |
API Endpoints, Subticket Manager |
unlink_subticket |
Remove parent-child relationship | can_manage_subtickets |
API Endpoints, Subticket Manager |
¶ get_ticket
Purpose: Retrieve a complete ticket with all messages
Parameters:
number(optional) - Ticket number (e.g., "123456")id(optional) - Ticket ID
Example:
{
"number": "123456"
}
¶ list_tickets
Purpose: List tickets with optional filters and pagination
Parameters:
status(optional) - Filter by status (e.g., "open", "closed")departmentId(optional) - Filter by department IDlimit(optional) - Maximum results (default: 20)offset(optional) - Pagination offset (default: 0)
Example:
{
"status": "open",
"limit": 50
}
¶ search_tickets
Purpose: Full-text search across ticket subjects and numbers
Parameters:
query(required) - Search querylimit(optional) - Maximum results (default: 20)
Example:
{
"query": "Dashboard Widget",
"limit": 10
}
¶ get_ticket_stats
Purpose: Get aggregated ticket statistics
Parameters: None (empty object {})
Example:
{}
¶ create_ticket
Purpose: Create a new osTicket ticket
Parameters:
name(optional) - User name (usesOSTICKET_DEFAULT_NAMEif not provided)email(optional) - User email (usesOSTICKET_DEFAULT_EMAILif not provided)subject(required) - Ticket subjectmessage(required) - Ticket message/descriptionformat(optional) - Message format:"markdown"(default),"html", or"text"topicId(optional) - Help Topic ID (usesOSTICKET_DEFAULT_TOPIC_IDif not provided)
Markdown Support:
Requires markdown-support plugin. Without it, content is treated as HTML.
Example:
{
"subject": "Bug Report",
"message": "## Critical Bug\\n\\n**Issue:** Payment calculation error\\n\\n```php\\n$total = calculateTotal();\\n```"
}
¶ update_ticket
Purpose: Update ticket properties
Parameters:
number(required) - Ticket numberdepartmentId(optional) - Department ID or namestatusId(optional) - Status ID or nametopicId(optional) - Help Topic ID or namestaffId(optional) - Staff ID or usernameslaId(optional) - SLA Plan ID or nameparentTicketNumber(optional) - Parent ticket numbernote(optional) - Add internal notenoteTitle(optional) - Title for note (default: "API Update")noteFormat(optional) - Format: "text", "html", "markdown" (default: "markdown")
Smart ID Resolution:
✨ You don't need to memorize IDs! The MCP server dynamically resolves names to IDs by querying your osTicket instance.
Supported for:
- Status: Use "Open", "Closed", "Resolved", "Testing", or your custom status names
- Department: Use department names instead of IDs
- Help Topic: Use topic names instead of IDs
- SLA Plan: Use SLA names instead of IDs
- Staff: Use usernames instead of staff IDs
How it works:
- MCP server loads available statuses/departments/topics from your osTicket API on first use
- Results are cached for the session (fast subsequent lookups)
- Names are matched case-insensitively
- If name not found, you get a helpful error with available options
Example:
{
"number": "123456",
"statusId": "Closed",
"departmentId": "IT Support",
"note": "## Resolution\\n\\nIssue fixed and deployed."
}
Numeric IDs still work:
{
"number": "123456",
"statusId": 3,
"departmentId": 5
}
¶ delete_ticket
Purpose: Permanently delete a ticket
⚠️ Warning: This operation is irreversible!
Parameters:
number(required) - Ticket number
Example:
{
"number": "123456"
}
¶ get_parent_ticket
⚠️ Requires: Subticket Manager Plugin
Purpose: Get the parent ticket of a subticket
Parameters:
number(required) - Child ticket number
Example:
{
"number": "234567"
}
Response:
{
"success": true,
"parent": {
"ticket_id": 78,
"number": "123456",
"subject": "Main Issue",
"status": "Open"
}
}
¶ get_child_tickets
⚠️ Requires: Subticket Manager Plugin
Purpose: Get list of child tickets for a parent ticket
Parameters:
number(required) - Parent ticket number
Example:
{
"number": "123456"
}
Response:
{
"success": true,
"children": [
{
"ticket_id": 79,
"number": "234567",
"subject": "Subtask 1",
"status": "Open"
},
{
"ticket_id": 80,
"number": "345678",
"subject": "Subtask 2",
"status": "Closed"
}
],
"total": 2
}
¶ create_subticket_link
⚠️ Requires: Subticket Manager Plugin
Purpose: Create a parent-child relationship between two tickets
Parameters:
parentNumber(required) - Parent ticket numberchildNumber(required) - Child ticket number or ID
Example:
{
"parentNumber": "123456",
"childNumber": "234567"
}
Response:
{
"success": true,
"parent": {
"ticket_id": 78,
"number": "123456",
"subject": "Main Issue",
"status": "Open"
},
"child": {
"ticket_id": 79,
"number": "234567",
"subject": "Subtask 1",
"status": "Open"
},
"message": "Subticket link created: 234567 is now a child of 123456"
}
¶ unlink_subticket
⚠️ Requires: Subticket Manager Plugin
Purpose: Remove parent-child relationship (make ticket independent again)
Parameters:
number(required) - Child ticket number to unlink
Example:
{
"number": "234567"
}
Response:
{
"success": true,
"child": {
"ticket_id": 79,
"number": "234567",
"subject": "Subtask 1",
"status": "Open"
},
"message": "Subticket 234567 has been unlinked from its parent"
}
¶ Troubleshooting
¶ Problem: MCP server not loading
Symptoms:
- Claude Desktop doesn't show MCP tools
- "Server failed to start" error
Check:
- Node.js version:
node -v(must be 18+) ~/.claude/config.jsonsyntax (valid JSON)- Environment variables in
.env - Claude Desktop logs:
- macOS:
~/Library/Logs/Claude/mcp*.log - Windows:
%APPDATA%\\Claude\\logs\\mcp*.log
- macOS:
Solution:
# Rebuild server
cd ~/.claude/mcp-servers/osticket
npm run build
# Test manually
node dist/index.js
¶ Problem: "HTTP error! status: 401 Unauthorized"
Symptoms: Invalid API key
Check:
- Verify API key in
.env - Check API key in osTicket Admin Panel
- Ensure API key is enabled
- Verify IP address is correct
Solution: Regenerate API key and update .env
¶ Problem: "HTTP error! status: 403 Forbidden"
Symptoms: Missing permissions
Check:
- Admin Panel → Plugins → API Endpoints → Configure
- Select your API key
- Enable required permissions:
- ✅
can_read_tickets - ✅
can_search_tickets - ✅
can_update_tickets - ✅
can_delete_tickets - ✅
can_read_stats - ✅
can_manage_subtickets(if using subticket tools)
- ✅
- Click Save
¶ Problem: "HTTP error! status: 404 Ticket not found"
Symptoms: Ticket does not exist
Solution:
- Verify ticket number is correct
- Check if ticket exists in osTicket Admin Panel
- Ensure you have permission to access the ticket's department
¶ Problem: "HTTP error! status: 501 Not Implemented"
Symptoms: Subticket tools return 501 error
Solution:
- Install Subticket Manager Plugin
- Enable plugin in Admin Panel
- Configure API key permissions (check
can_manage_subtickets)
¶ Problem: "Missing required environment variables"
Symptoms: .env file not found
Solution:
- Ensure
.envexists at~/.claude/mcp-servers/osticket/.env - Copy from
.env.example - Fill in all required variables
¶ Logs for Debugging
View server logs:
# Live tail
tail -f ~/.claude/mcp-servers/osticket/logs/server.log
# Enable debug logging in .env
LOG_LEVEL=debug
¶ Technical Details
¶ Architecture
┌─────────────────────────────────────┐
│ Claude Code │
│ └─ MCP Protocol │
├─────────────────────────────────────┤
│ MCP Server (Node.js/TypeScript) │
│ ├─ Application Layer │
│ │ └─ Tool Handlers │
│ └─ Infrastructure Layer │
│ ├─ HTTP Client │
│ │ └─ Smart ID Resolution │
│ └─ Logger │
├─────────────────────────────────────┤
│ osTicket REST API │
│ └─ API Endpoints Plugin │
│ ├─ tickets-statuses.php │
│ ├─ tickets-subtickets-*.php │
│ └─ Other endpoints │
└─────────────────────────────────────┘
¶ Project Structure
claude-mcp-osTicket/
├── dist/ # Compiled JavaScript
├── src/
│ ├── index.ts # MCP server entry point
│ ├── config/
│ │ └── Configuration.ts # Environment configuration
│ ├── application/
│ │ └── handlers/
│ │ └── ToolHandlers.ts # Tool implementations
│ └── infrastructure/
│ ├── http/
│ │ ├── OsTicketApiClient.ts # REST API client with ID resolution
│ │ └── types/
│ │ └── SubticketTypes.ts # TypeScript types for subtickets
│ └── logging/
│ └── Logger.ts # File-based logger
├── package.json
├── tsconfig.json
├── .env # Configuration (not in Git)
└── .env.example # Template
¶ API Endpoints Used
| Tool | API Endpoint | Method |
|---|---|---|
| get_ticket | /api/tickets-get.php/:number.json |
GET |
| list_tickets | /api/tickets-search.php |
GET |
| search_tickets | /api/tickets-search.php?query=... |
GET |
| get_ticket_stats | /api/tickets-stats.php |
GET |
| create_ticket | /api/tickets.json |
POST |
| update_ticket | /api/tickets-update.php/:number.json |
PATCH |
| delete_ticket | /api/tickets-delete.php/:number.json |
DELETE |
| get_parent_ticket | /api/tickets-subtickets-parent.php/:number.json |
GET |
| get_child_tickets | /api/tickets-subtickets-list.php/:number.json |
GET |
| create_subticket_link | /api/tickets-subtickets-create.php/:parent.json |
POST |
| unlink_subticket | /api/tickets-subtickets-unlink.php/:child.json |
DELETE |
| ID Resolution | /api/tickets-statuses.php |
GET |
¶ Security Features
-
API Key Encryption:
- Stored in environment variables (not in code)
- Transmitted via HTTPS only
-
Input Validation:
- All parameters validated before API calls
- Type checking with TypeScript
-
Permission System:
- Granular permissions per API key
- Configured in API Endpoints Plugin
¶ FAQ
¶ General Questions
Q: What is MCP?
A: MCP (Model Context Protocol) is a standard protocol for connecting AI assistants to external tools. This server implements MCP to allow Claude to interact with osTicket.
Q: Do I need to restart Claude after configuration changes?
A: Yes. Claude Desktop and Claude CLI must be restarted to reload MCP configurations.
Q: Can I use this with other AI assistants?
A: Yes! Any MCP-compatible client can use this server. Primarily tested with Claude Desktop and Claude CLI.
¶ Compatibility
Q: Is it compatible with Node.js 16?
A: No. Requires Node.js 18+ for ESM support and modern JavaScript features.
Q: Does it work on Windows?
A: Yes! Tested on macOS, Linux, and Windows.
Q: Does it work with osTicket 1.17?
A: Not tested. Designed for osTicket 1.18.x. May work with 1.17 but compatibility not guaranteed.
¶ Smart ID Resolution
Q: Can I use status names instead of IDs?
A: Yes! The MCP server automatically resolves status names (like "Open", "Closed", "Testing") to IDs by querying the /api/tickets-statuses.php endpoint. This works with your custom status names.
Q: What happens if I use an invalid status name?
A: You'll get a helpful error message listing all available status names from your osTicket instance.
Q: Does name resolution work for departments, topics, and SLA plans too?
A: Yes! The same smart resolution works for:
- Status names (via
/api/tickets-statuses.php) - Department names
- Help Topic names
- SLA Plan names
- Staff usernames
Q: Are the resolved IDs cached?
A: Yes! Status names are loaded once per MCP server session and cached in memory for fast subsequent lookups.
¶ Subticket Management
Q: What are subtickets?
A: Subtickets allow you to create parent-child relationships between tickets. This is useful for organizing complex issues into main tickets with subtasks.
Q: Do I need the Subticket Manager Plugin for all tools?
A: No. Only for the 4 subticket-specific tools (get_parent_ticket, get_child_tickets, create_subticket_link, unlink_subticket). All other tools work without it.
Q: What happens if I try to use subticket tools without the plugin?
A: You'll receive an HTTP 501 error with message "Subticket plugin not available".
Q: Can a ticket have multiple parents?
A: No. Each ticket can only have one parent. If you try to link a ticket that already has a parent, you'll get an HTTP 422 error.
¶ Security
Q: Is it safe to use 0.0.0.0 as API key IP?
A: Only in development! For production, always use specific IP addresses. The 0.0.0.0 option requires the api-key-wildcard plugin and should only be used behind firewalls.
Q: Where are API keys stored?
A: In the .env file, which is excluded from Git via .gitignore. Never commit API keys to version control.
¶ Troubleshooting
Q: Why am I getting 403 Forbidden errors?
A: Check permissions in Admin Panel → Plugins → API Endpoints → Configure. Ensure all required permissions are checked for your API key.
Q: Can I create read-only API keys?
A: Yes! In API Endpoints Plugin configuration, enable only can_read_tickets, can_search_tickets, and can_read_stats.
¶ 📄 License
This MCP Server is released under the MIT License.
See LICENSE for details.
¶ 💬 Support
For questions or issues, please create an issue on GitHub:
Issue Tracker: https://github.com/markus-michalski/claude-mcp-osTicket/issues
When reporting issues, please include:
- Node.js version (
node -v) - npm version (
npm -v) - osTicket version
- MCP server version
- Claude Desktop/CLI version
- Operating system
- Error messages from logs
- Steps to reproduce
¶ 🤝 Contributing
Developed by Markus Michalski
Contributions welcome!
- Fork the repository
- Create a feature branch
- Submit a pull request
¶ Related Links
- API Endpoints Plugin - Required
- Subticket Manager Plugin - Required for subticket tools
- API Key Wildcard Plugin - Optional (for
0.0.0.0IP) - Markdown Support Plugin - Optional (for rich formatting)
- Model Context Protocol
- MCP Specification
¶ Changelog
See CHANGELOG.md for version history.