Illio

You can use the Illumio MCP Server to programmatically manage Illumio Policy Compute Engine (PCE) data, including workloads, labels, traffic analysis, and system health. This MCP server exposes a set of tools you can invoke through your MCP client to interact with PCE in a structured, automated way, enabling rapid integration with your workflows and automation pipelines.

How to use

You interact with the Illumio MCP Server through an MCP client to perform common tasks against your PCE. You can create, update, and delete workloads and labels, obtain detailed or summarized traffic flows for security analysis, and check the health of your PCE connection. Use these capabilities to automate workload lifecycle tasks, manage labeling schemes, and perform data-driven security analysis across your environment.

How to install

Prerequisites: You need Python 3.8+ and access to an Illumio PCE instance with valid API credentials.

Step 1 – Clone the MCP server repository and install dependencies. Execute these commands in your terminal:

git clone [repository-url]
cd illumio-mcp

pip install -r requirements.txt

Step 2 – Configure and run the MCP server using uv in the background. Create the required environment variables and start the server with the specified directory and script name.

export PCE_HOST=your-pce-host
export PCE_PORT=your-pce-port
export PCE_ORG_ID=1
export API_KEY=api_key
export API_SECRET=api_secret

uv --directory /path/to/illumio-mcp run illumio-mcp

Step 3 – Optional: cache or store the MCP server configuration in a client helper. The following JSON configuration snippet shows how to define the MCP server for a client that supports the standard MCP config format.

{
  "mcpServers": {
    "illumio_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/illumio-mcp",
        "run",
        "illumio-mcp"
      ],
      "env": {
        "PCE_HOST": "your-pce-host",
        "PCE_PORT": "your-pce-port",
        "PCE_ORG_ID": "1",
        "API_KEY": "api_key",
        "API_SECRET": "api_secret"
      }
    }
  }
}

Configuration and environment

The MCP server is started via a background runner. You supply the directory where the server lives, the script to run, and the necessary PCE credentials through environment variables. Keep these credentials secure and do not expose them in logs or version control.

Important environment variables you will use are:

PCE_HOST: the hostname or IP address of your Illumio PCE instance PCE_PORT: the port for the PCE API PCE_ORG_ID: the Illumio organization identifier API_KEY: your PCE API key API_SECRET: your PCE API secret (or equivalent credentials)

Security and error handling

The server includes comprehensive error handling and logging. It reports issues related to PCE connection problems, API authentication failures, resource creation or updates, and invalid inputs. All errors are logged with full context and returned to clients in structured error messages to facilitate debugging.

Notes on running in production

To keep the MCP server running in production, deploy it behind a process manager or container runtime, ensure secrets are securely managed (e.g., using a secrets manager), and monitor logs for any authentication or connectivity issues with the PCE.

Additional configuration options and usage

You can customize the runtime by setting environment variables as part of your startup configuration or by editing the startup script to pass different PCE credentials or host details.

Troubleshooting tips

If you cannot reach the PCE, verify that the host, port, and credentials are correct. Check that the PCE is accessible from the machine running the MCP server and that network policies allow the connection. Ensure the API credentials have the required permissions for workload, labels, and traffic analysis operations.

Available tools

get-workloads

Retrieve all workloads from the 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 the PCE by name

create-label

Create a new label with a key-value pair

delete-label

Remove an existing label by key-value pair

get-labels

Retrieve all labels from the PCE

get-traffic-flows

Get detailed traffic flow data with filtering options spanning date, source/destination, service, policy decisions, workloads, and IPs

get-traffic-flows-summary

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

get-rulesets

Get rulesets from the PCE with optional filters by name or enabled status

get-iplists

Get IP lists from the PCE with optional filters by name, description, and IP ranges

check-pce-connection

Verify PCE connectivity and credentials

get-events

Get events from the PCE with filtering by type, severity, status, and limit