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

Installation

Option 1: Install from PyPI (Recommended)

# Install from PyPI
pip install itop-mcp

# Or using uv
uv add itop-mcp

Node.js Implementation

# Install from npm (coming soon)
npm install itop-mcp-nodejs

# Or clone and build locally
git clone https://github.com/roneydsilva/itop-mcp.git
cd itop-mcp/nodejs
npm install
npm run build

🔧 MCP Configuration

Prerequisites

1. iTop Instance: Access to an iTop instance with REST API enabled
2. iTop User Account: User account with “REST Services User” profile
3. Environment Variables: Set the following environment variables:

   export ITOP_BASE_URL="https://your-itop-instance.com"
   export ITOP_USER="your-username"
   export ITOP_PASSWORD="your-password"
   export ITOP_VERSION="1.4"  # Optional, defaults to 1.4
   

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

For Python implementation:

{
  "mcpServers": {
    "itop": {
      "command": "python",
      "args": ["-m", "main"],
      "cwd": "/path/to/itop-mcp",
      "env": {
        "ITOP_BASE_URL": "https://your-itop-instance.com",
        "ITOP_USER": "your-username",