LudusMCP

Model Context Protocol server for managing Ludus lab environments through natural language commands.

Prerequisites

For detailed information, please refer to the wiki

System Requirements

Node.js 18.0.0 or higher
npm package manager
Ludus CLI binary installed and in PATH on host with the mcp-client(ex. claude desktop)
Active Ludus server environment
Network connectivity to Ludus server via WireGuard VPN or SSH

Ludus Server Access

Ensure you have:

Ludus server SSH access credentials
Ludus API key (obtain via ludus user apikey command)
WireGuard configuration file OR SSH tunnel capabilities (obtain wireguard conf from Ludus CLI)
Admin USERID for Ludus server.

Installation

NOTE Installation of the MCP server IS NOT on the Ludus server. It will be installed on a device with an MCP client (ex Claude Desktop) that has access to the Ludus server.

Global Installation (Recommended)

Install the package globally to make the ludus-mcp command available system-wide:

npm install -g ludus-mcp@latest
ludus-mcp --setup-keyring

What happens during installation:

Downloads source code and dependencies
Compiles native dependencies (keytar) for your platform (Windows/Linux/macOS)
Builds TypeScript source to JavaScript (src/ → dist/)
Creates global ludus-mcp command in your PATH

This is a one-time installation process that compiles everything for your specific platform.

From Source (Development)

git clone https://github.com/NocteDefensor/LudusMCP.git
cd LudusMCP
From within LudusMCP directory
npm install    # Installs dependencies and builds automatically
npx ludus-mcp --setup-keyring  # Use npx for local from source installations by running it from within clone/install directory

Installation Requirements

The package includes native dependencies that require compilation during installation:

Build tools: Node.js build tools (automatically installed)
Platform libraries: OS credential manager libraries (Windows Credential Manager, macOS Keychain, Linux libsecret)

If installation fails, ensure you have proper build tools for your platform.

Updating

NPM Global Install

npm install -g ludus-mcp@latest

Local Development Install

cd LudusMCP
git pull origin main
npm install
npm run build

Configuration

Initial Setup

Run the setup wizard to configure credentials securely: (from within cloned directory if installing from source)

npx ludus-mcp --setup-keyring

The setup wizard will prompt for:

Connection Method: WireGuard VPN or SSH tunnel
Ludus Admin Username: Your Ludus admin account USER ID
API Key: Ludus API key from ludus user apikey command.
SSH Credentials: Host, username, and authentication method
WireGuard Config: Path to .conf file (if using WireGuard)

NOTE Do not use quotes or single quotes around any values during the keyring setup or renew operations.

Credentials are stored securely in your OS credential manager (Windows Credential Manager, macOS Keychain, Linux Secret Service).

Update Credentials (from within cloned directory if installing from source)

To modify existing credentials:

npx ludus-mcp --renew-keyring

Connection Methods

WireGuard VPN

Direct connection to Ludus server for non admin functions via VPN tunnel
Requires WireGuard client and configuration file
Must be manually started before using MCP client
Will still use SSH tunnel for ADMIN ops due to ADMIN API only available localhost on Ludus Server.

SSH Tunnel

Port forwarding through SSH connection
Fallback option when WireGuard unavailable
Automatically managed by MCP server
SSH tunnel will always be used for ADMIN API

MCP Client Integration

Setup Process Overview

Install Package (one-time) - Compiles for your platform
Configure Credentials (one-time) - Run setup wizard
Configure MCP Client (one-time) - Add to client config
Daily Usage - Start MCP client, server auto-connects

Claude Desktop Configuration

Find your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ludus": {
      "command": "ludus-mcp"
    }
  },
  "isUsingBuiltInNodeForMcp": true
}

Development/Source Installation

If running from source:

{
  "mcpServers": {
    "ludus": {
      "command": "node",
      "args": ["/path/to/LudusMCP/dist/server.js"]
    }
  },
  "isUsingBuiltInNodeForMcp": false
}

Usage

Normal Operation

When you start your MCP client (Claude Desktop), it automatically:

Launches the pre-compiled ludus-mcp server
Server loads credentials from OS keyring
Downloads fresh configurations from GitHub
Downloads updated schemas and documentation
Tests connectivity to Ludus server
Starts MCP protocol for tool communication

No manual server startup required - your MCP client handles everything.

Manual Server Testing (Optional)

For troubleshooting or testing the server independently: NOTE You do not need to manually start server prior to running your mcp client such as claude desktop. MCP client will automatically start the MCP server. This manual start below is for testing only.

ludus-mcp  # If globally installed
# OR
npx ludus-mcp  # run from cloned directory if locally installed

Server Startup Process:

Load Credentials - Retrieves stored credentials from OS keyring
Download Assets - Updates base configurations, schemas, and documentation from GitHub
Connectivity Test - Verifies connection to Ludus server via WireGuard/SSH
MCP Protocol - Starts Model Context Protocol server for tool communication

Available Prompts

create-ludus-range Complete guided workflow for range creation from requirements to deployment.

execute-ludus-cmd Safe execution of Ludus CLI commands with destructive action protection.

To use prompts with Claude Desktop hunt for the "plus" + button near your chat bar.
- Click "add from ludus and you will see both prompts. Select the one you want.

Available Tools

Range Management

deploy_range - Deploy virtualized training environment
get_range_status - Check deployment status and VM states
list_user_ranges - List all ranges for user
get_connection_info - Download RDP/VPN connection files
destroy_range - Permanently delete range and VMs
range_abort - Stop stuck deployments
ludus_power - Start/stop range VMs

Configuration Management

read_range_config - Read configuration files
write_range_config - Create/modify range configurations
validate_range_config - Validate YAML syntax and schema
list_range_configs - Browse available templates
get_range_config - Get currently active configuration
set_range_config - Set active configuration for deployment

Documentation & Research

ludus_docs_search - Search Ludus documentation
ludus_range_planner - Intelligent range planning assistant
ludus_roles_search - Search available Ludus roles
ludus_environment_guides_search - Find environment setup guides
ludus_networking_search - Network configuration help
ludus_read_range_config_schema - View configuration schema
ludus_range_config_check_against_plan - Validate against requirements
ludus_read_role_collection_schema - View role schemas
ludus_list_role_collection_schemas - List all available role/collection schemas

Utility & Administration

ludus_cli_execute - Execute arbitrary Ludus CLI commands
ludus_help - Get help for Ludus commands
list_all_users - List all Ludus users (admin only)
get_credential_from_user - Securely collect credentials
insert_creds_range_config - Inject credentials into configurations (note: the LLM doesn't actually interact with OS credential management/keyring at all. It passes the name the credential is stored under to the function. The function retrieves the credential and replaces placeholder with cred.

Role and Collection Schemas

The MCP server maintains detailed schemas for all available Ludus roles and collections to help the LLM understand role capabilities, variables, and requirements during range planning.

Schema Location Official schemas are stored in ~/.ludus-mcp/schemas/ as individual YAML files, one per role or collection. These are automatically downloaded and updated from the GitHub repository on server startup.

Schema Tools

ludus_list_role_collection_schemas - List all available role/collection schema files
ludus_read_role_collection_schema - Read schema data (all schemas or specific files)

Adding Custom Schemas To add schemas for custom roles or third-party roles not in the official repository:

Create a YAML file in ~/.ludus-mcp/schemas/ following the standard format
Use a distinctive name to avoid conflicts (e.g., company.custom_role.yaml)
Include all required fields: name, type, description, variables
Refer to Sample-schema.yaml in the schemas directory for proper formatting and structure

Schema Persistence Custom schemas are preserved during server restarts. The update process only overwrites official schemas from the repository, leaving your custom files intact.

Filtered Reading Use ludus_read_role_collection_schema with the file_names parameter to read specific schemas instead of all schemas at once.

Recommended Workflow

Plan Your Range Use the create-ludus-range prompt for guided range creation:
```
Requirements: "AD environment with SCCM and 3 workstations"
```
Review Configuration Use list_range_configs to see available templates and read_range_config to examine them.
Validate Before Deployment Always run validate_range_config before setting configuration.
Set Active Configuration Use set_range_config to make configuration active for deployment.
Deploy Range Use deploy_range to create the virtualized environment.
Get Connection Info Use get_connection_info to download RDP files and access VMs.

Extensive or Advanced CLI Operations

For operations not covered by specific tools, use the execute-ludus-cmd prompt:

Command Intent: "Check detailed logs for deployment issues"

File Locations

Configuration files and data are stored in ~/.ludus-mcp/:

~/.ludus-mcp/
├── range-config-templates/
│   └── base-configs/           # GitHub templates (auto-updated)
├── schemas/                    # Role/collection schemas (auto-updated)
│   ├── Sample-schema.yaml     # Template for custom schemas
│   ├── ludus_sccm.yaml        # Individual role schemas
│   ├── badsectorlabs.ludus_vulhub.yaml
│   ├── custom_role.yaml       # Your custom schemas (preserved)
│   └── range-config.json      # Range configuration schema
└── ludus-docs/                 # Cached documentation (auto-updated)
    ├── environment-guides/
    ├── quick-start/
    └── troubleshooting/

Official project files are automatically downloaded and updated on server startup. Custom files you create are preserved.

Security

This is for lab use only. Security is marginal. Some attempts have been made to limit OS command injection or path traversal. Additionally, credentials are handled via OS credential manager.

Credential Management

External service credentials (API keys, SaaS tokens) use placeholder format: {{LudusCredName-<user>-<name>}}
Range-internal credentials (AD passwords, domain accounts) included directly
All credentials stored in OS credential manager
Secure dialogs for credential collection

Networking

WireGuard VPN for server communication
SSH tunnel fallback or SSH primary with key-based or password based authentication

Operational Safety

Destructive operations should require explicit confirmation but highly recommend you don't "always allow" access to dangerous tools such as destroy_range and you closely observe usage. Its an LLM and sometimes it does weird stuff.
Should automatically validate configurations before deployment. It will definitely go through syntax/range schema validation as part of write process.

Troubleshooting

Logs are stored in ~/.ludus-mcp/logs

Connection Issues

Verify WireGuard tunnel is active: wg show
Test SSH connectivity: ssh user@ludus-host
Check API key: ludus --url https://your-server:8080 version

Configuration Problems

Run validate_range_config to check syntax
Use ludus_read_range_config_schema to verify structure
Check logs for specific error messages

Credential Issues

Re-run setup: npx ludus-mcp --renew-keyring
Verify OS credential manager access
Check file permissions on WireGuard config

Common Errors

"No configuration available": Run --setup-keyring
"Range operations connectivity failed": Check WireGuard/SSH
"Schema validation failed": Use validate_range_config tool

Help

For additional help:

Use ludus_help tool for Ludus CLI documentation
Use ludus_docs_search for comprehensive guides
Review generated configurations with read_range_config
Check GitHub repository for issues and updates

References:

Ludus Documentation - https://docs.ludus.cloud/docs/intro

Coming Changes

May switch to Desktop Extension setup vs the current homegrown keyring config/renew functions.
May make a remote mcp server version to be able to interact with ludus from any device on network regardless of having ludus cli present etc.
Will add more sample reference templates.
Will attempt to keep up with new roles by adding them to the schema for LLM reference.

Credits

Ludus - @badsectorlabs
Claude - Wouldn't quite call this project vibe coding but maybe 4 beers deep in the passenger seat shouting out navigation commands.
Reddit MCP channel for lots of researching
MCP documentation - https://modelcontextprotocol.io/introduction
Anthropic MCP docs - https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector
MCP in VS Code - https://code.visualstudio.com/docs/copilot/chat/mcp-servers

License

GNU General Public License v3.0