Illumio MCP Server

A Model Context Protocol (MCP) server that provides an interface to interact with Illumio PCE (Policy Compute Engine). This server enables programmatic access to Illumio workload management, label operations, and traffic flow analysis.

What can it do?

Use conversational AI to talk to your PCE:

• Create, update and delete workloads
• Create, update and delete labels
• Get traffic summaries and do security analysis on them
• Get PCE health

Prerequisites

• Python 3.8+
• Access to an Illumio PCE instance
• Valid API credentials for the PCE

Installation

1. Clone the repository:

git clone [repository-url]
cd illumio-mcp

2. Install dependencies:

pip install -r requirements.txt

Configuration

You should run this using the uv command, which makes it easier to pass in environment variables and run it in the background.

Using uv and Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json

Add the following to the custom_settings section:

"mcpServers": {
    "illumio-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/alex.goller/git/illumio-mcp",
        "run",
        "illumio-mcp"
      ],
      "env": {
        "PCE_HOST": "your-pce-host",
        "PCE_PORT": "your-pce-port",
        "PCE_ORG_ID": "1", # your org id
        "API_KEY": "api_key",
        "API_SECRET": "api_secret"
      }
    }
  }
}

Features

Resources

Resources are not finished yet and I will look into that later.

• illumio://workloads - Get workloads from the PCE
• illumio://labels - Get all labels from PCE

Tools

Workload Management

• get-workloads - Retrieve all workloads from PCE
• create-workload - Create an unmanaged workload with specified name, IP addresses, and labels
• update-workload - Update an existing workload’s properties
• delete-workload - Remove a workload from PCE by name

Label Operations

• create-label - Create a new label with key-value pair
• delete-label - Remove an existing label by key-value pair
• get-labels - Retrieve all labels from PCE

Traffic Analysis

• get-traffic-flows - Get detailed traffic flow data with comprehensive filtering options:
• Date range filtering
• Source/destination filtering
• Service (port/protocol) filtering
• Policy decision filtering
• Workload and IP list query options

• Results limiting

• get-traffic-flows-summary - Get summarized traffic flow information with the same filtering capabilities as get-traffic-flows

Policy Management

• get-rulesets - Get rulesets from the PCE with optional filtering:
• Filter by name
• Filter by enabled status

IP Lists Management

• get-iplists - Get IP lists from the PCE with optional filtering:
• Filter by name
• Filter by description
• Filter by IP ranges

Connection Testing

• check-pce-connection - Verify PCE connectivity and credentials

Event Management

• get-events - Get events from the PCE with optional filtering:
• Filter by event type (e.g., ‘system_task.expire_service_account_api_keys’)
• Filter by severity (emerg, alert, crit, err, warning, notice, info, debug)
• Filter by status (success, failure)
• Limit number of results returned

Error Handling

The server implements comprehensive error handling and logging:
- PCE connection issues
- API authentication failures
- Resource creation/update failures
- Invalid input validation

All errors are logged with full stack traces and returned as formatted error messages to the client.

Development

Running Tests

Testing is not implemented yet.

python -m pytest tests/

Debug Mode

Set logging level to DEBUG in the code or environment for detailed operation logs.

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

This project is licensed under the GPL-3.0 License. See the LICENSE file for details.

Support

For support, please create an issue.

Examples

Visual Examples

All the examples below were generated by Claude Desktop 3.5 Sonnet and with data obtained through this MCP server. I found out that rendering the data to react components is resulting in beautiful visualizations and results.

Application Analysis

Detailed view of application communication patterns and dependencies

Analysis of traffic patterns between different application tiers

Infrastructure Insights

Overview dashboard showing key infrastructure metrics and status

Detailed analysis of infrastructure service communications

Security Assessment

Comprehensive security analysis report

Security assessment findings for high-risk vulnerabilities

PCI compliance assessment findings

SWIFT compliance assessment findings

Remediation Planning

Overview of security remediation planning

Detailed steps for security remediation implementation

Policy Management

Management interface for IP lists

Overview of ruleset categories and organization

Configuration of application ruleset ordering

Workload Management

Detailed workload analysis and metrics

Identification and analysis of workload traffic patterns

Label Management

Organization of PCE labels by type and category

Service Analysis

Automatic inference of service roles based on traffic patterns

Analysis of top 5 traffic sources and destinations

Project Planning

Project implementation timeline and milestones

Available Prompts

Ringfence Application

The ringfence-application prompt helps create security policies to isolate and protect applications by controlling inbound and outbound traffic.

Required Arguments:
- application_name: Name of the application to ringfence
- application_environment: Environment of the application to ringfence

Features:
- Creates rules for inter-tier communication within the application
- Uses traffic flows to identify required external connections
- Implements inbound traffic restrictions based on source applications
- Creates outbound traffic rules for necessary external communications
- Handles both intra-scope (same app/env) and extra-scope (external) connections
- Creates separate rulesets for remote application connections

Analyze Application Traffic

The analyze-application-traffic prompt provides detailed analysis of application traffic patterns and connectivity.

Required Arguments:
- application_name: Name of the application to analyze
- application_environment: Environment of the application to analyze

Analysis Features:
- Orders traffic by inbound and outbound flows
- Groups by application/environment/role combinations
- Identifies relevant label types and patterns
- Displays results in a React component format
- Shows protocol and port information
- Attempts to identify known service patterns (e.g., Nagios on port 5666)
- Categorizes traffic into infrastructure and application types
- Determines internet exposure
- Displays Illumio role, application, and environment labels

How to use MCP prompts

Step1: Click “Attach from MCP” button in the interface

Step 2: Choose from installed MCP servers

Step 3: Fill in required prompt arguments:

Step 4: Click Submit to send the configured prompt

How prompts work

• The MCP server sends the configured prompt to Claude
• Claude receives context through the Model Context Protocol
• Allows specialized handling of Illumio-specific tasks

This workflow enables automated context sharing between Illumio systems and Claude for application traffic analysis and ringfencing tasks.

Docker

The application is available as a Docker container from the GitHub Container Registry.

Pull the container

docker pull ghcr.io/alexgoller/illumio-mcp-server:latest

You can also use a specific version by replacing latest with a version number:

docker pull ghcr.io/alexgoller/illumio-mcp-server:1.0.0

Run with Claude Desktop

To use the container with Claude Desktop, you’ll need to:

1. Create an environment file (e.g. ~/.illumio-mcp.env) with your PCE credentials:

PCE_HOST=your-pce-host
PCE_PORT=your-pce-port
PCE_ORG_ID=1
API_KEY=your-api-key
API_SECRET=your-api-secret

2. Add the following configuration to your Claude Desktop config file:

On MacOS (~/Library/Application Support/Claude/claude_desktop_config.json):

{
    "mcpServers": {
        "illumio-mcp-docker": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--init",
                "--rm",
                "-v",
                "/Users/YOUR_USERNAME/tmp:/var/log/illumio-mcp",
                "-e",
                "DOCKER_CONTAINER=true",
                "-e",
                "PYTHONWARNINGS=ignore",
                "--env-file",
                "/Users/YOUR_USERNAME/.illumio-mcp.env",
                "illumio-mcp:latest"
            ]
        }
    }
}

Make sure to:
- Replace YOUR_USERNAME with your actual username
- Create the log directory (e.g. ~/tmp)
- Adjust the paths according to your system

Run Standalone

You can also run the container directly:

docker run -i --init --rm \
  -v /path/to/logs:/var/log/illumio-mcp \
  -e DOCKER_CONTAINER=true \
  -e PYTHONWARNINGS=ignore \
  --env-file ~/.illumio-mcp.env \
  ghcr.io/alexgoller/illumio-mcp-server:latest

Docker Compose

For development or testing, you can use Docker Compose. Create a docker-compose.yml file:

version: '3'
services:
  illumio-mcp:
    image: ghcr.io/alexgoller/illumio-mcp-server:latest
    init: true
    volumes:
      - ./logs:/var/log/illumio-mcp
    environment:
      - DOCKER_CONTAINER=true
      - PYTHONWARNINGS=ignore
    env_file:
      - ~/.illumio-mcp.env

Then run:

docker-compose up

Known Issues

When running the container, you may see syntax warnings from the Illumio SDK’s regular expressions. These warnings don’t affect functionality and are automatically suppressed in the container.

If you’re seeing the warnings when running the container, you can manually suppress them by adding:

docker run \
  -e PYTHONWARNINGS=ignore \
  ... other environment variables ...
  ghcr.io/alexgoller/illumio-mcp-server:latest

Or in docker-compose.yml:

services:
  illumio-mcp:
    environment:
      - PYTHONWARNINGS=ignore
      # ... other environment variables ...

Claude Desktop Configuration

For Claude Desktop users, add this configuration to your Claude Desktop config file:

{
    "mcpServers": {
        "illumio-mcp-docker": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--init",
                "--rm",
                "-v",
                "/Users/YOUR_USERNAME/tmp:/var/log/illumio-mcp",
                "-e",
                "DOCKER_CONTAINER=true",
                "-e",
                "PYTHONWARNINGS=ignore",
                "--env-file",
                "/Users/YOUR_USERNAME/.illumio-mcp.env",
                "illumio-mcp:latest"
            ]
        }
    }
}

Make sure to:
1. Replace YOUR_USERNAME with your actual username
2. Create a log directory at ~/tmp (or adjust the path as needed)
3. Create an environment file at ~/.illumio-mcp.env with your PCE credentials:

PCE_HOST=your-pce-host
PCE_PORT=your-pce-port
PCE_ORG_ID=1
API_KEY=your-api-key
API_SECRET=your-api-secret

The configuration:
- Uses Docker to run the container
- Mounts a local directory for logs
- Suppresses Python warnings
- Loads PCE credentials from an environment file
- Enables proper container cleanup with --init and --rm