iTop MCP Server

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

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.

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

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

- 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

Option 1: Install from PyPI (Recommended)

# Install from PyPI pip install itop-mcp # Or using uv uv add itop-mcp

# 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

- iTop Instance: Access to an iTop instance with REST API enabled
- iTop User Account: User account with "REST Services User" profile
- 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

Add to your Claude Desktop configuration file:

{ "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", "ITOP_PASSWORD": "your-password", "ITOP_VERSION": "1.4" } } } }

{ "mcpServers": { "itop": { "command": "itop-mcp", "env": { "ITOP_BASE_URL": "https://your-itop-instance.com", "ITOP_USER": "your-username", "ITOP_PASSWORD": "your-password", "ITOP_VERSION": "1.4" } } } }

{ "mcpServers": { "itop": { "command": "node", "args": ["dist/index.js"], "cwd": "/path/to/itop-mcp/nodejs", "env": { "ITOP_BASE_URL": "https://your-itop-instance.com", "ITOP_USER": "your-username", "ITOP_PASSWORD": "your-password", "ITOP_VERSION": "1.4" } } } }

For other MCP clients, use similar configuration with the appropriate command and environment variables.

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.

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

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

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

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

- 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

- Class-specific icons(🖥️ for servers, 🎫 for tickets, etc.)
- Relevant field selectionbased on query context
- Statistical summariesfor grouping queries
- Detailed vs summary modesbased on query type
- Rich metadataincluding applied filters and query details

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

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

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

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

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

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

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

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

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

# 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

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)

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

- Fork the repository
- Create a feature branch
- Make your changes
- Run tests:python tests/run_tests.py
- Submit a pull request

- "Show me all new support tickets with SLA status"
- "Get user requests that have breached SLA"
- "List incidents by priority with table format"
- "Find tickets assigned to John Smith"
- "Create a new user request for printer issues"

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

Repository:https://github.com/roneydsilva/itop-mcp

PyPI Package:https://pypi.org/project/itop-mcp/

Issues:https://github.com/roneydsilva/itop-mcp/issues

iTop Documentation:https://www.itophub.io/wiki/page?id=latest%3Aadvancedtopics%3Arest_jsoncurl -LsSfhttps://astral.sh/uv/install.sh| sh

git clonehttps://github.com/roneydsilva/itop-mcp.gitcd itop-mcp uv sync

# Copy the example configuration cp .env.example .env # Edit the .env file with your iTop details nano .env

- 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)

# Activate the virtual environment source .venv/bin/activate # Run the server uv run main.py

{ "mcpServers": { "itop": { "command": "itop-mcp", "env": { "ITOP_BASE_URL": "https://your-itop-instance.com", "ITOP_USER": "your_username", "ITOP_PASSWORD": "your_password" } } } }

{ "mcpServers": { "itop": { "command": "uv", "args": [ "run", "--directory", "/path/to/itop-mcp", "itop-mcp" ], "env": { "ITOP_BASE_URL": "https://your-itop-instance.com", "ITOP_USER": "your_username", "ITOP_PASSWORD": "your_password", "ITOP_VERSION": "1.3" } } } }

Note: This works because we've configureditop-mcpas an entry point inpyproject.toml. You need to run this from the project directory wherepyproject.tomlis located, or uv needs to be able to find the project.

### Example Operations Once connected, you can ask your AI assistant to perform operations like: Basic Operations: - "List all open user requests in iTop" - "Create a new incident ticket for server downtime" - "Find all CIs related to the mail server" - "Update the priority of ticket #123 to high" - "Resolve ticket #456 with resolution details" Enhanced Queries: - "Get the latest 5 tickets created today" - "Show me all tickets assigned to John Smith" - "Find all tickets reported by Jane Doe" - "Get detailed information for ticket R-000123" - "List organizations containing 'Tech' in their name" Smart Ticket Creation: - "Create a new user request for printer issues reported by John from IT Department" AI-Powered 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" ## 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 ## Troubleshooting ### Common Issues 1. Authentication errors: Ensure your user has the "REST Services User" profile in iTop 2. Connection errors: Verify the ITOP_BASE_URL is correct and accessible 3. Permission errors: Check that the user has appropriate rights on the objects you're trying to access ### Testing the Connection Use the check_credentials tool to verify your configuration: 

- Add new tools by creating functions decorated with@mcp.tool()`
- Follow the iTop REST API documentation for available operations
- Handle errors gracefully and provide informative messages
- Test thoroughly in a development environment
- Use the smart query processor for rapid prototyping and testing of new query types
- Fork the repository
- Create a feature branch
- Make your changes
- Test thoroughly
- Submit a pull request

This project is open source. See the LICENSE file for details.

- Model Context Protocol Documentation
- iTop REST API Documentation
- iTop Official Website

Connect AI assistants directly to the HiveFlow automation platform.