Content
# 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:
```bash
git clone [repository-url]
cd illumio-mcp
```
2. Install dependencies:
```bash
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:
```json
"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.
```bash
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](LICENSE) file for details.
## Support
For support, please [create an issue](https://github.com/illumio/illumio-mcp/issues).
# 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
```bash
docker pull ghcr.io/alexgoller/illumio-mcp-server:latest
```
You can also use a specific version by replacing `latest` with a version number:
```bash
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:
```env
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`):
```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:
```bash
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:
```yaml
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:
```bash
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:
```bash
docker run \
-e PYTHONWARNINGS=ignore \
... other environment variables ...
ghcr.io/alexgoller/illumio-mcp-server:latest
```
Or in docker-compose.yml:
```yaml
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:
```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:
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:
```env
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`
