Labsco
cdmx1 logo

iTop MCP Server

★ 19

from cdmx1

An MCP server for interacting with iTop ITSM systems via its REST API.

🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#automation#database#git#maps#security

iTop MCP Server

A Model Context Protocol (MCP) server for integrating with iTop ITSM (IT Service Management) systems. This server provides AI assistants with the ability to interact with iTop through its REST API, enabling operations like ticket management, CI (Configuration Item) management, and more.

🚀 Features

The iTop MCP server provides the following tools:

🧠 Smart Query Processor V2 (New Enhanced Version):

  • smart_query_v2: Revolutionary natural language query processor with class-specific intelligence
    • Automatic Class Detection: Intelligently detects target iTop class from natural language
    • 12+ Specialized Handlers: Dedicated processors for UserRequest, Ticket, Change, Incident, Problem, Server, PC, VirtualMachine, NetworkDevice, Person, Team, Organization
    • Advanced Query Features: Grouping, filtering, SLA analysis, deadline tracking, and statistical breakdowns
    • Smart Field Mapping: User-friendly field aliases automatically mapped to iTop schema
    • Fuzzy Matching: Intelligent name matching for servers, people, and other entities
    • Real-time Schema Discovery: Uses *+ fields for automatic field detection
    • Enhanced Formatting: Class-specific output with icons, detailed/summary modes, and grouped results

Core iTop Operations:

  • list_operations: List all available iTop REST API operations
  • smart_query_v2: Process natural language queries with intelligent class detection and specialized handlers

Legacy Support (Deprecated):

  • Note: Previous versions included additional tools (get_objects, create_object, update_object, delete_object, apply_stimulus, get_related_objects, check_credentials) which have been streamlined in favor of the more powerful smart_query_v2 approach

🧠 Smart Query Processor V2

The Smart Query Processor V2 represents a major advancement in natural language query processing for iTop. It features class-specific handlers that understand the unique characteristics and relationships of different iTop object types.

Supported Classes & Handlers

🎫 Ticket Management

  • UserRequest: User service requests with SLA tracking
  • Ticket: Generic ticket operations
  • Change: Change management tickets
  • Incident: Incident management
  • Problem: Problem management

🖥️ Infrastructure

  • Server: Physical servers with hardware details
  • PC: Personal computers and workstations
  • VirtualMachine: Virtual machine management
  • NetworkDevice: Network equipment (switches, routers, firewalls)

👥 People & Organization

  • Person: Individual contacts and users
  • Team: Team management and assignments
  • Organization: Organizational structure

Key Features

🎯 Automatic Class Detection

The system intelligently detects which iTop class you're querying:

"Show me all critical servers" → Detects: Server class
"List user requests from last week" → Detects: UserRequest class
"Find network switches in production" → Detects: NetworkDevice class

🔍 Advanced Query Capabilities

  • Grouping & Breakdown: "Show servers grouped by organization"
  • SLA Analysis: "Find tickets with SLA breaches"
  • Status Filtering: "List production servers"
  • Multi-criteria: "Critical VMs owned by Database team"
  • Fuzzy Matching: Handles typos and variations in names

📊 Enhanced Output Formatting

Each class handler provides:

  • Class-specific icons (🖥️ for servers, 🎫 for tickets, etc.)
  • Relevant field selection based on query context
  • Statistical summaries for grouping queries
  • Detailed vs summary modes based on query type
  • Rich metadata including applied filters and query details

🔧 Smart Field Mapping

User-friendly terms are automatically mapped to iTop schema fields:

"organization" → "org_name"
"owner" → "owner_friendlyname"  
"critical" → "business_criticity = critical"
"production" → "status = production"

Example Queries

Infrastructure Queries

"Show all production servers"
"List critical VMs by organization" 
"Find network switches in Datacenter A"
"Count PCs by location"
"Show servers with Windows OS"

Ticket Management

"Show high priority user requests"
"List incidents created this week"
"Find changes scheduled for next month"
"Group tickets by status"
"Show SLA breached requests"

People & Organization

"List active people in IT department"
"Show teams by organization"
"Find managers in Engineering"
"Count users by location"

Advanced Features

🎯 Software Focus Mode

For infrastructure queries, automatic detection of software-related intent:

"Show software on Server2" → Returns installed applications
"List applications on production servers" → Software-focused output

📈 Statistical Analysis

Automatic grouping and statistical breakdowns:

"Servers by organization" → Groups servers and shows counts per org
"Ticket status breakdown" → Shows distribution across statuses
"SLA compliance by team" → Analyzes SLA performance by team

🔄 Fallback Support

  • Generic handler for classes without specific implementations
  • Intelligent field detection for unknown classes
  • Graceful degradation with helpful error messages

🧪 Development & Testing

Running Tests

# Run all tests
python tests/run_tests.py

# Run specific test types
python tests/run_tests.py --unit        # Unit tests only
python tests/run_tests.py --live        # Live tests only (requires iTop instance)
python tests/run_tests.py --nodejs      # Node.js tests only
python tests/run_tests.py --lint        # Linting only

# Auto-fix linting issues
python tests/run_tests.py --fix

Code Quality

The project includes comprehensive linting and formatting:

  • Black: Code formatting
  • isort: Import sorting
  • Flake8: Code linting
  • mypy: Type checking (Python)
  • ESLint: TypeScript linting (Node.js)

Live Testing

Set environment variables and run live tests against your iTop instance:

export ITOP_BASE_URL="https://your-itop-instance.com"
export ITOP_USER="your-username"
export ITOP_PASSWORD="your-password"

python tests/test_live.py

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests: python tests/run_tests.py
  5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

  1. Configure iTop connection:

    # Copy the example configuration
cp .env.example .env

# Edit the .env file with your iTop details
nano .env

    Required environment variables:

    • ITOP_BASE_URL: Your iTop instance URL (e.g., https://itop.yourcompany.com)
    • ITOP_USER: Username with REST Services User profile
    • ITOP_PASSWORD: Password for the user
    • ITOP_VERSION: API version (optional, default: 1.4)

iTop Class Examples

Common iTop classes you can work with:

  • UserRequest: User requests/tickets
  • Incident: Incident tickets
  • Person: Users and contacts
  • Organization: Organizations/companies
  • Server: Server configuration items
  • Application: Application configuration items
  • Service: IT services
  • Contract: Contracts and SLAs

Advanced Features (Updated July 2025)

This server now supports advanced, AI-powered natural language queries and smart schema discovery. Key features include:

  • Smart Query Processor: Use natural language to ask for any iTop data (e.g., "Show all virtual machines running", "List all servers in production", "Tickets closed vs not closed on time based on SLA").
  • Automatic Class & Field Detection: The server dynamically discovers iTop classes and fields, so you don't need to hardcode field names.
  • Flexible Output: Results can be formatted as tables, summaries, JSON, or detailed views.
  • SLA & Time Analysis: Supports queries about SLA compliance, overdue tickets, and on-time completion.
  • Multi-Query Comparison: Easily compare stats (e.g., closed vs not closed, completed on time vs not on time).
  • Relationship & Grouping: Group results by status, organization, or any field, and link related objects (e.g., network devices with locations).
  • Extensible Tools: Add new tools by decorating async functions with @mcp.tool().

Example Smart Queries

  • "Get me PC count"
  • "Give me status-based stats for the PCs"
  • "Get me active tickets generated by PC-wise"
  • "Change requests completed vs not completed on time"
  • "Tickets closed vs not closed on time based on SLA"
  • "List all servers in the production environment"
  • "Show me all virtual machines running"

How it Works

  • The main server logic is in main.py.
  • Uses a class taxonomy and dynamic schema discovery to map natural language to iTop REST API queries.
  • Handles errors gracefully and provides suggestions if a query returns no results.
  • Supports both simple and complex queries, including grouping, filtering, and comparisons.

Security Notes

  • Always use HTTPS for your iTop instance in production
  • Store credentials securely (use environment variables, not hardcoded values)
  • The user account should have minimal necessary permissions
  • Test operations in a development environment first
  • Use simulation mode for delete operations until you're confident

Development

To extend the server:

  1. Add new tools by creating functions decorated with @mcp.tool()
  2. Follow the iTop REST API documentation for available operations
  3. Handle errors gracefully and provide informative messages
  4. Test thoroughly in a development environment
  5. Use the smart query processor for rapid prototyping and testing of new query types

References