itop-mcp 1.0.2

Model Context Protocol server for iTop ITSM integration

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:

Core iTop Operations:

• list_operations: List all available iTop REST API operations
• get_objects: Search and retrieve iTop objects (tickets, users, CIs, etc.)
• create_object: Create new objects in iTop
• update_object: Update existing objects
• delete_object: Delete objects (with simulation mode for safety)
• apply_stimulus: Apply state transitions to objects (e.g., resolve tickets)
• get_related_objects: Find related objects through impact/dependency relationships
• check_credentials: Verify iTop API credentials

Enhanced Ticket Management:

• get_latest_tickets: Get recent tickets ordered by creation date with status filtering
• search_tickets_by_caller: Find tickets by caller name
• get_ticket_details: Get comprehensive details for a specific ticket
• get_my_assigned_tickets: Get tickets assigned to a specific agent with status grouping
• create_user_request: Streamlined user request creation with smart field resolution

Organization Management:

• get_organizations: List and search organizations with filtering

Installation

Option 1: Install from PyPI (Recommended)

# Install the package
pip install itop-mcp

# Or using uv
uv add itop-mcp

Option 2: Install from Source

1. Prerequisites:

   • Python 3.10 or higher
   • Access to an iTop instance with REST API enabled
   • iTop user account with "REST Services User" profile

2. Install dependencies:

   # Install uv if you haven't already
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Clone and install
   git clone https://github.com/roneydsilva/itop-mcp.git
   cd itop-mcp
   uv sync
   

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

Usage

Running the Server

# Activate the virtual environment
source .venv/bin/activate

# Run the server
uv run main.py

Connecting to Claude Desktop

Option 1: Using PyPI Installation

To use this server with Claude Desktop, add the following to your claude_desktop_config.json:

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

Option 2: Using Source Installation

{
  "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 configured itop-mcp as an entry point in pyproject.toml. You need to run this from the project directory where pyproject.toml is 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"

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

## 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:

```python
# The server will automatically test credentials on startup
# You can also ask the AI assistant: "Check my iTop credentials"

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

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

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

References

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