Content
# mcp-itop
MCP Server for **iTop ITSM** — analytics, tickets, comments, knowledge base, CI.
Provides AI-assistants (opencode, Claude Desktop, Cursor) with **19 tools** for working with iTop:
SLA analytics, agent workload, service quality, ticket lifecycle, knowledge base search, impact analysis of CI.
## Capabilities
### Analytics
| Tool | Description |
|------------|----------|
| `itop_sla_report` | SLA report by service for a period (TTO/TTR passed/breached/N/A, median resolution) |
| `itop_agent_workload` | Agent workload: closed/open tickets, time_spent, backlog |
| `itop_idle_agents` | Search for tickets where agent is inactive >N hours without actions |
| `itop_service_quality` | Search for similar tickets assigned to different services |
| `itop_caller_quality` | Quality of service selection by users |
| `itop_agent_correction_rate` | Agents who correct / do not correct services |
| `itop_ticket_summary` | Dashboard: created/resolved/open/SLA breaches |
### Comments
| Tool | Description |
|------------|----------|
| `itop_add_comment` | Add public or private comment to a ticket |
| `itop_get_log` | Read comment history (public_log, private_log) |
### Knowledge Base
| Tool | Description |
|------------|----------|
| `itop_search_kb` | Search knowledge base articles (supports KBEntry and FAQ) |
| `itop_get_kb_article` | Full text of an article |
| `itop_list_kb_categories` | List of knowledge base categories |
### CRUD + Lifecycle
| Tool | Description |
|------------|----------|
| `itop_get` | Search objects (OQL / ID / JSON criteria) |
| `itop_create` | Create object |
| `itop_update` | Update object fields |
| `itop_delete` | Delete with simulate mode |
| `itop_apply_stimulus` | Lifecycle: ev_assign, ev_resolve, ev_close, ev_reopen |
| `itop_get_related` | Impact analysis of CI (impacts/depends on) |
| `itop_describe_class` | Exploration of class fields by existing object |
## Quick Start
### 1. Installation
```bash
pip install mcp[fastmcp] httpx python-dotenv
```
### 2. Configuration (global config)
```bash
mkdir -p ~/.config/mcp-itop
cat > ~/.config/mcp-itop/.env << 'CONFIG'
ITOP_URL=https://your-itop.example.com
# Token or login+password:
ITOP_TOKEN=your_token_here
# ITOP_USER=admin
# ITOP_PASSWORD=secret
ITOP_VERSION=1.3
ITOP_VERIFY_SSL=true
ITOP_TIMEOUT=30
CONFIG
```
### 3. Launch
```bash
python server.py
```
## Integration
### opencode (global config)
Add to `~/.config/opencode/opencode.json`:
```json
"itop": {
"type": "local",
"command": ["python", "/path/to/mcp-itop/server.py"],
"enabled": true
}
```
### opencode (per project)
Add to `opencode.json` project:
```json
{
"mcpServers": {
"itop": {
"command": "python",
"args": ["/path/to/mcp-itop/server.py"],
"env": {
"ITOP_URL": "https://your-itop.example.com",
"ITOP_TOKEN": "your_token"
}
}
}
}
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"itop": {
"command": "python",
"args": ["/path/to/mcp-itop/server.py"]
}
}
}
```
## Request Examples
```
Show SLA for the "Technical Support" service for this month
Who are the overloaded agents?
Which tickets are pending for more than 2 hours?
Find similar tickets with different services
Which users often select the wrong service?
Add a comment to ticket RQ-123
Create a new ticket: Printer does not work
Assign RQ-456 to Ivanov
Find CI related to server srv-web-01
Search knowledge base for VPN
```
## Compatibility
Tested on:
- **iTop** 3.2.1-1-16749 (PHP 8.1.2, MariaDB 10.6)
- Supports Russian locale (yes/no for SLA) and English (true/false)
- Auto-detection of knowledge base module: KBEntry → FAQ
## Requirements
- Python ≥ 3.10
- `mcp[fastmcp]`
- `httpx`
- `python-dotenv`
## Tests
```bash
python -m pytest tests/ -v
```
## Architecture
```
AI-client → MCP (stdio) → server.py → iTop REST API
```
Configuration priority:
1. `~/.config/mcp-itop/.env` (global, highest priority)
2. `.env` (local in project directory)
3. Environment variables
## License
MIT
