MCP SERVERDeploy a Ludus cyber range, snapshot it before a detonation, roll it back after, and read the packer build log that failed — without leaving the session.
LABSCO SUMMARY
The failures that usually cost an afternoon have their own tools rather than a workaround: handle_adws_recovery for the Active Directory stall, get_vm_console_ticket for a VM that never got a working NIC, list_range_log_history for the log a newer deployment already overwrote. The surface is the trade — 231 tools is more than most clients will hold in context at once, and several of them (delete_range, regenerate_user_apikey, cleanup_old_ranges) do their damage on the first call.
A full-surface client for a Ludus server: 231 tools covering range deployment, VM snapshots, packer template builds, Ansible roles, scenarios and blueprints, SIEM readouts, and the user, group and quota administration behind them.
A reachable Ludus server and LUDUS_API_KEY, or LUDUS_JWT_TOKEN instead if you sign in to Ludus Pro through SSO; Python 3.11+ and pipx to install it from the GitHub repository.
Follow the published steps — pipx install git+https://github.com/tjnull/Ludus-FastMCP
USE CASES
Snapshot the machines you care about, put the range into testing mode so the VMs lose their internet access, then open exactly the domains the sample needs to reach. Roll back when it is over and the lab is where it started.
Check the scenario list, find out which Ansible roles it requires, install the missing ones, then deploy with validation and monitoring rather than firing a bare deployment and watching the log.
Get the current status, tail the deployment log, and compare it against the archived log of the run that worked. Active Directory stalls have their own recovery path rather than a restart.
A machine that failed its domain join or came up with a misconfigured NIC cannot be reached the usual way. Take a console ticket, get the WebSocket URL for it, and diagnose the network path from the server's side while you are in there.
The weekly Kali ISO URL and checksum change, so a pinned template goes stale. Create the template from the current weekly build, queue the packer build, and go read the log — including the one an earlier build overwrote.
Find out who has room before assigning anyone a range, set the budgets per user or per group, and give ranges an idle timeout so forgotten labs power themselves off instead of holding memory.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
abort_and_remove_rangeAbort any active deployment and then remove the range.
This is a convenience function that combines abort_range_deployment() and delete_range(). Equivalent to running:
ludus range abortludus rm (with confirmation)abort_range_deploymentAbort a range deployment.
Stops an active deployment. Use this before deleting a range that is currently deploying. After aborting, you can resume the deployment using deploy_range() with specific tags.
Equivalent to: ludus range abort
abort_template_buildAbort the running packer build(s).
Ludus aborts the user's current template operation; it cannot abort one specific template while leaving others running.
add_ranges_to_groupAdd ranges to a group.
add_sourceRegister a new content source on the Ludus server.
This is how you add a catalog of templates, roles and prebuilt labs that the server does not ship with. Adding a source does not install anything from it — follow with get_source_catalog then install_from_source.
add_templateAdd a packer template to Ludus by uploading a local directory.
Ludus templates are packer build directories, not image URLs. The directory is tarred and uploaded; Windows templates must contain an Autounattend.xml at their root. Adding a template does not build it -- follow with build_template.
add_userAdd a new user to the Ludus system.
Ludus users have no login password of their own; the optional Proxmox credentials below are the hypervisor account tied to the user.
add_users_to_groupAdd users to a group.
allow_testing_domainsAllow specific domains or IPs while the range is in testing mode.
Testing mode blocks a VM's internet access so detonations stay contained; this punches controlled holes in that block, e.g. to let malware reach one C2 domain while everything else stays denied.
apply_adversary_profileApply adversary profile to inject realistic vulnerabilities for red team training.
This tool transforms an existing Ludus configuration by injecting educational vulnerabilities that simulate real-world security weaknesses. Perfect for:
apply_blueprint_to_rangeApply a blueprint to a range.
apply_defender_profileApply defender profile to add monitoring and detection capabilities for blue team training.
This tool enhances an existing Ludus configuration with comprehensive security monitoring, logging, and detection capabilities. Perfect for:
assign_range_to_userAssign range access to a user.
auto_scalingDefine auto-scaling rules based on resource usage.
batch_get_vm_statusGet status of multiple VMs in parallel.
batch_power_off_hostsPower off multiple VMs in parallel.
batch_power_on_hostsPower on multiple VMs in parallel.
batch_remove_snapshotsRemove snapshots from multiple VMs in parallel.
batch_rollback_snapshotsRollback multiple VMs to a snapshot in parallel.
batch_snapshot_hostsCreate snapshots for multiple VMs in parallel.
This is much faster than creating snapshots sequentially, especially for large numbers of VMs.
build_container_based_templateBuild a custom container-based template for applications.
This tool creates templates specifically designed to run Docker containers, perfect for deploying applications like Splunk, Wazuh, Grafana, etc.
build_range_from_descriptionBuild a custom range configuration from a natural language description.
This tool intelligently parses your description and automatically builds a complete range configuration with appropriate VMs, network rules, and SIEM.
build_range_from_scratchBuild a completely custom range configuration from scratch.
This tool allows you to create a range configuration with full control over every VM and network rule, not based on any existing scenario.
build_range_from_skeletonBuild a complete range configuration starting from a skeleton.
Combines the power of skeleton templates with custom modifications. Start with a base skeleton and add/remove VMs as needed.
build_templateStart a packer build for one or more VM templates.
Builds run on the Ludus server and take a long time (tens of minutes to hours each). This returns as soon as the build is queued; poll get_template_status or get_template_logs to follow progress.
bulk_vm_operationsPerform bulk operations on multiple VMs.
capture_network_trafficCapture network traffic on a VM.
check_role_installedCheck if a specific Ansible role is installed.
Uses the ludus CLI with --url when available for reliable remote access. Falls back to HTTP API if CLI is not available. No SSH required.
cleanup_old_rangesDelete all ranges EXCEPT those belonging to specified users.
Useful for cleaning up test/temporary ranges while keeping production ones.
clear_range_accessClear all range access permissions.
clone_and_modify_scenarioClone an existing scenario and modify it to create a new custom scenario.
This is useful for creating variations of existing scenarios (e.g., "ad-basic" with more workstations, or "web-basic" with different applications).
clone_rangeClone the current range to another user.
compliance_checkCheck compliance against security framework.
configure_ssh_role_installationConfigure SSH access for automatic role installation on Ludus server.
This allows the MCP server to automatically clone and install directory-based roles (like ludus-ad-content) directly on the Ludus server via SSH, without manual setup.
Security Note: SSH access requires appropriate permissions. Use SSH keys when possible.
copy_blueprintCopy a blueprint under a new ID.
Copy before editing when you want to keep the original intact, e.g. forking a source-provided lab to customise it.
create_blueprintCreate a blueprint from a range configuration you already have.
Use create_blueprint_from_range instead when you want to capture a deployed range rather than supply the config yourself.
create_blueprint_from_rangeCreate a reusable blueprint from an existing range.
create_container_templateCreate a container-based template.
create_custom_os_templateCreate a custom OS template with specific packages and configuration.
This tool allows you to create custom Ludus templates from ANY operating system by providing an ISO URL. The OS type can be auto-detected from the ISO URL/filename, or explicitly specified. Supports Linux, Windows, BSD, macOS, and any other OS.
create_custom_range_from_scenarioCreate a custom range configuration based on an existing scenario.
This tool takes an existing scenario and allows you to customize it with your own modifications (add/remove VMs, change specs, modify network rules).
create_custom_templateCreate a custom template from scratch.
create_deployment_pipelineCreate a deployment pipeline with multiple stages.
create_groupCreate a new group.
create_kali_weekly_templateCreate a Kali Linux weekly template with automatic latest ISO detection.
Automatically fetches the latest Kali Linux weekly ISO and checksum from https://cdimage.kali.org/kali-weekly/. The ISO URL and checksum change weekly, so this tool always uses the most recent version.
create_new_rangeCreate a new range.
create_scenario_playbookGenerate a red or blue team playbook for a scenario.
delete_blueprintDelete a blueprint.
delete_groupDelete a group.
delete_rangeDelete the entire range.
Permanently removes the range and all associated VMs, snapshots, and data.
Important: If a deployment is in progress, abort it first with abort_range_deployment().
delete_range_by_userDelete a specific user's range (requires confirmation).
This tool allows you to selectively delete a single range by user ID, rather than destroying all ranges. Requires explicit confirmation.
delete_range_objectDelete a range object entirely, removing its configuration too.
This is ludus range rm-range, a different operation from delete_range_by_user, which is ludus range rm:
The API refuses to delete a range that still has VMs unless force=True.
delete_ranges_by_statusDelete all ranges matching a specific status (requires confirmation).
Useful for cleaning up failed deployments or test ranges.
delete_sourceRemove a content source.
This does not uninstall items the source already installed.
delete_templateDelete a template.
deny_testing_domainsRe-block domains or IPs that were previously allowed in testing mode.
deploy_rangeDeploy a range from configuration with optional filters for resuming.
IMPORTANT: For deploying predefined scenarios (redteam-lab-lite, etc.), use deploy_scenario() or smart_deploy() instead. This tool is for:
This tool supports both full deployments and resuming partial deployments.
Full Deployment: deploy_range(config=configuration_dict)
Resume After Pause/Abort: deploy_range(tags="user,domain") # Run specific Ansible tags only deploy_range(limit="DC*") # Deploy only to matching VMs deploy_range(tags="user", limit="WS*") # Combine filters
Common Ansible Tags:
deploy_range_from_blueprintSet up and deploy a whole range from a blueprint in one call.
Runs the full sequence with pre-flight checks that otherwise fail late and cryptically:
Deployment continues in the background; poll get_range for state and get_range_logs for progress. A multi-VM lab such as GOAD takes hours.
deploy_scenarioDeploy a scenario with optional SIEM integration and customization.
IMPORTANT: This tool generates a FRESH configuration for each call. Each deployment builds a new scenario from scratch - no state is reused.
NO FILE UPLOAD REQUIRED: This tool automatically generates the configuration from the scenario parameters. You do NOT need to provide a config file or manual configuration.
CUSTOMIZATION AND RANDOMIZATION:
Recommended Workflow:
Internal Workflow:
Available scenarios:
deployment_timelineGet deployment timeline with progress tracking.
destroy_vmDestroy a specific VM.
diagnose_network_issuesDiagnose network connectivity issues.
ensure_scenario_rolesEnsure all required roles for a scenario are installed, installing missing ones automatically.
This is the recommended MCP tool to use before deploying a scenario. It will:
MCP Workflow:
ensure_scenario_roles() before deploying to ensure all roles are readyconfigure_ssh_role_installation() for automatic directory-based role installationinstall_role() to install individual roles as neededexplain_range_design_decisionsExplain the design decisions and best practices for a range configuration request.
This tool helps users understand WHY certain choices are made when building a cyber range, providing educational value beyond just generating configs.
export_blueprintExport a blueprint to a .tar.gz archive on disk.
The archive can be moved to another Ludus server and loaded there with import_blueprint.
export_lab_guideExport lab guide for training purposes.
The guide is generated from the current range deployment.
export_metricsExport metrics data.
Exports the current range metrics; the Ludus API has no historical metrics range to query, so there is no start/end time filter.
export_range_backupExport a range backup (configuration and snapshot metadata).
export_range_config_to_yamlExport a range configuration to a YAML file for download.
This tool exports range configurations to YAML format that users can download and use with Ludus. The YAML content is provided in the response for easy copying or downloading through the chat interface.
find_range_by_vm_nameFind which range contains a specific VM by name.
generate_config_from_descriptionGenerate a complete Ludus range configuration from natural language description.
This is an enhanced AI-powered version of build_range_from_description that provides:
generate_range_documentationGenerate comprehensive documentation for the range.
get_all_user_quotasGet quotas for every user on the server (admin only).
Use this to see who has room to deploy before assigning them a range.
get_ansible_role_varsGet variables for an Ansible role (Ludus 2.0 only).
get_attack_path_documentationGenerate attack path documentation for an attack technique.
Note that scenario_key names an attack technique ("kerberoasting", "golden-ticket"), not a range scenario like "redteam-lab-lite". There is no default: omitting it returns the list of techniques available.
get_auto_shutdownGet the auto-shutdown timeout for a range.
get_blueprintGet a blueprint's metadata: name, description, version, tags, source.
Use get_blueprint_config for the range configuration it deploys.
get_blueprint_configGet blueprint configuration.
get_common_container_configsGet pre-configured container definitions for common applications.
Returns a dictionary of common application containers (Splunk, Wazuh, ELK, Nginx, PostgreSQL, Redis, Grafana) that can be used with create_container_template.
Returns: Dictionary of application name to container configuration
Example: # Get all common container configs configs = await get_common_container_configs()
# Use Splunk config to create template splunk_config = configs["splunk"] result = await create_container_template( name="ubuntu-splunk", base_os="ubuntu-22.04", containers=[splunk_config] )
get_common_galaxy_rolesGet a list of commonly used Ansible Galaxy roles for Ludus scenarios.
Returns a curated list of Galaxy roles that are frequently used in security lab scenarios, along with their descriptions and example usage.
Returns: Dictionary of common roles organized by category
Example: roles = await get_common_galaxy_roles() # Then install what you need: await install_galaxy_role(role_name="geerlingguy.docker")
get_common_iso_urlsGet common ISO download URLs for popular operating systems.
Returns a reference of ISO download URLs for various operating systems that can be used with create_custom_os_template.
Returns: Dictionary of OS names to ISO download information
Example: # Get common ISO URLs isos = await get_common_iso_urls() # Use one of the URLs result = await create_custom_os_template( name="arch-linux", iso_url=isos["arch_linux"]["url"], description="Arch Linux template" )
get_container_configGet configuration for a common container.
get_cost_estimationGet cost estimation for the range.
get_current_range_config_for_downloadGet the current range configuration and prepare it for download.
This tool retrieves your currently deployed range configuration from Ludus and provides it in YAML format for download. Users can then save this configuration file and modify/redeploy it as needed.
get_default_quotasGet the server-wide default quotas that new users inherit.
get_default_rangeGet user's default range ID.
Returns: Default range information
get_deployment_metricsGet metrics for the current deployment.
get_deployment_statusGet current deployment status with detailed information.
get_detection_summaryGet detection summary from SIEM.
get_diagnosticsGet system diagnostics.
Returns: System diagnostics information
get_group_quotasGet the default quotas configured for each group (admin only).
get_licenseGet license information.
Returns: License information
get_network_topologyGet network topology visualization data.
get_rangeGet current user's range information.
get_range_accessGet range access information.
Returns the LIST of ranges the caller can access, which may be empty. To see who can access a specific range, use list_range_users instead.
get_range_ansible_inventoryGet Ansible inventory for the range.
get_range_by_userGet detailed information about a specific user's range.
get_range_configGet range configuration.
get_range_etchostsGet /etc/hosts entries for the range.
get_range_log_from_historyGet the full contents of one archived range deployment log.
get_range_logsGet deployment logs for the range.
Deployment logs run to tens of thousands of lines, so this returns the last 200 by default. Pass tail=None for the whole log.
get_range_metricsGet comprehensive metrics for the range.
get_range_rdpconfigsGet RDP configuration files for the range.
get_range_skeletonGet a complete range skeleton configuration.
Retrieves a fully-configured range skeleton with all VMs and network rules. Some skeletons support additional customization parameters.
get_range_sshconfigGet SSH config for the range.
get_range_tagsGet available Ansible tags for the current range.
Use this to see what tags are available for resuming/partial deployments. Tags allow you to run specific parts of a deployment without re-running everything.
get_recovery_recommendationGet recovery recommendations for failed deployments.
get_required_roles_for_scenarioGet the list of required Ansible roles for a specific scenario.
Use this MCP tool to check which roles are needed before deploying a scenario. Then use ensure_scenario_roles() to automatically install missing roles.
get_resource_quotasGet resource quotas and current usage.
get_role_infoGet information about a specific role, including installation method and requirements.
Uses the ludus CLI with --url when available for reliable remote access. No SSH required for checking role information.
get_scenario_configGet scenario configuration.
get_scenario_yamlGet scenario configuration as YAML.
get_sdn_migration_statusGet SDN migration status.
Returns: SDN migration status information
get_server_openapi_specFetch the Ludus server's own OpenAPI specification.
Use this to discover what this particular server actually implements, rather than assuming every documented endpoint exists. Ludus serves several features (quotas, auto-shutdown) from optional plugins that may not be loaded, and the published docs cover a superset of any one build.
Returns: The raw spec, or an explanation if this server does not serve one
get_siem_agentsGet SIEM agents for the range.
get_siem_alertsGet SIEM alerts for the range.
get_siem_infoGet SIEM information for the range.
get_sourceGet details for a single content source.
get_source_catalogGet everything a source publishes, with install state for each item.
This is the tool to use when asked what templates, blueprints or roles are available to add to the server.
get_template_dependenciesGet template dependencies.
get_template_log_from_historyGet the full contents of one archived template build log.
get_template_logsGet the latest packer build logs.
Ludus keeps one build log per user, not per template.
get_template_statusGet the status of in-progress packer builds.
Ludus reports build status per user, not per template.
get_userGet information about a specific user.
get_user_membershipsGet current user's group memberships (Ludus 2.0 only).
Returns: List of group memberships
get_user_quotasGet the resource quotas applied to a user.
get_vm_console_ticketGet a console (noVNC) ticket for a VM.
This is the way to reach a VM that has no network access yet — a machine that failed its domain join, or one whose NIC is misconfigured.
get_vm_console_view_urlGet the console WebSocket URL for a ticket from get_vm_console_ticket.
The Ludus console is a WebSocket VNC channel, not a web page. This returns the URL a VNC/noVNC client should connect to. Fetching it over plain HTTP fails with "Failed to upgrade connection to WebSocket".
get_vm_skeletonGet a specific VM skeleton template configuration.
Retrieves a pre-configured VM skeleton that can be used directly in a range configuration or customized further.
get_vulnerability_scanGet vulnerability scan results for the range.
get_wazuh_infoGet Wazuh SIEM information for the range.
get_yaml_exampleGet a ready-to-use YAML configuration example.
Returns the complete YAML content for a specific example configuration. The YAML can be saved directly to a file and deployed with Ludus.
git_syncSync range configurations with a Git repository.
grant_range_accessGrant other users access to your range.
Ludus grants range access per user; there are no per-permission levels.
handle_adws_recoveryHandle Active Directory Web Services (ADWS) recovery for stuck deployments.
ADWS errors are common during Active Directory deployments. This tool:
When to use:
What this does:
health_checkCheck health of Ludus MCP server and Ludus API connectivity.
Uses the ludus CLI if available for more reliable connectivity testing.
Returns: Health status including:
health_checksRun health checks on all VMs in the range.
import_blueprintImport a blueprint from a .tar.gz archive.
import_community_scenarioImport a scenario from the community repository.
import_range_backupImport and restore range from backup.
install_blueprintInstall a blueprint's Ansible role and collection dependencies.
Run this before deploying a blueprint that came from a content source. Without it the deployment fails partway through on missing roles, after the VMs have already been cloned.
install_from_sourceInstall templates, blueprints, roles or collections from a source.
Installing a template makes its packer definition available; it still has to be built with build_template afterwards.
IMPORTANT: the selection REPLACES the source's previous selection, so pass every item you want installed in one call, not one call per item.
install_galaxy_roleInstall an Ansible role directly from Ansible Galaxy.
This is the simplest way to install roles. Provide the Galaxy role name in the format 'namespace.role_name' and it will be installed on the Ludus server.
install_roleInstall an Ansible role on the Ludus server via MCP.
This MCP tool automatically handles:
For directory-based roles: If SSH is configured (via configure_ssh_role_installation), the MCP server will automatically clone the repository on the Ludus server and install it. Otherwise, manual installation instructions will be provided.
install_role_from_urlInstall an Ansible role from a custom Git repository URL.
Use this to install roles from custom Git repositories that are not on Ansible Galaxy. The repository will be cloned on the Ludus server and installed.
install_subscription_rolesInstall subscription roles (Ludus 2.0 Enterprise only).
jira_integrationConfigure JIRA issue creation for failed deployments.
list_accessible_rangesList ranges accessible to current user.
Returns: List of ranges the current user has access to
list_all_ranges_detailedList all ranges with detailed information including identification.
This tool provides comprehensive information about all ranges in the system, making it easy to identify which range belongs to which user or purpose.
Returns: Detailed list of all ranges with:
Example: # List all ranges to see which ones exist result = await list_all_ranges_detailed()
# Output shows: { "total_ranges": 3, "ranges": [ { "user_id": "tjnull", "range_number": "10", "status": "SUCCESS", "vm_count": 5, "last_deployment": "2024-12-11T10:30:00Z", "identifier": "tjnull-range-10" }, ... ] }
list_available_profilesList all available adversary and defender profiles with descriptions.
Returns detailed information about all available security profiles, their capabilities, and use cases.
Returns: Dictionary containing:
Example: profiles = await list_available_profiles() print(profiles['adversary_profiles']['medium']['capabilities'])
list_blueprint_access_groupsList groups with access to a blueprint.
list_blueprint_access_usersList users with access to a blueprint.
list_blueprintsList all available blueprints.
list_common_containersList common container base images.
Returns: Dictionary of common container configurations
list_group_membersList group members.
list_group_rangesList group ranges.
list_groupsList all groups.
Returns: List of all groups
list_hostsList all hosts in range.
list_installed_rolesList all installed Ansible roles on the Ludus server.
Uses the ludus CLI with --url when available for reliable remote access. Falls back to HTTP API if CLI is not available.
Returns: Dictionary with list of installed roles and their details
Example: result = await list_installed_roles() # Returns: {"installed_roles": [...], "count": 15}
list_networksList the networks (VLANs) in a range.
Ludus has no network objects to query -- networks exist implicitly as the distinct VLANs its VMs are assigned to, so they are derived from the range configuration. GET /range carries no network data at all, so reading it there always yields an empty list.
list_range_log_historyList previous range deployment logs, most recent first.
get_range_logs only returns the log for the current or last deployment. This exposes the archive, which is what you want when comparing a failure against the deployment that last worked.
list_range_skeletonsList all available range skeleton templates.
Returns a dictionary of complete range configurations for common scenarios. These provide fully-configured lab environments ready for deployment.
Available range skeletons:
Returns: Dictionary with skeleton names as keys and descriptions as values
Example: ranges = await list_range_skeletons() # Returns: {"basic-ad": "Basic AD lab...", ...}
list_range_usersList users with access to a range.
list_rangesList all ranges (admin only).
list_role_repositoriesList all roles that are available from GitHub repositories (directory-based roles).
These roles must be cloned on the Ludus server before installation.
Returns: Dictionary with available role repositories and their GitHub URLs
Example: result = await list_role_repositories()
list_scenariosList all available scenarios.
Returns: Dictionary of scenario keys and descriptions
list_snapshotsList all snapshots for the range.
list_source_blueprintsList blueprints published by a source (GOAD, AD + Elastic, ...).
list_source_collectionsList Ansible collections published by a source.
list_source_rolesList Ansible roles published by a source.
list_source_templatesList packer templates published by a source.
list_sourcesList content sources configured on the Ludus server.
Returns: Sources with their sourceID, type, url and last sync status
list_subscription_rolesList available subscription roles (Ludus 2.0 Enterprise only).
Returns: List of subscription roles
list_template_log_historyList previous template build logs, most recent first.
Use this to find why an earlier packer build failed once a newer build has already overwritten the live log.
list_templatesList available templates.
list_usersList all users in the Ludus system.
Returns: List of all users with their information
list_vm_skeletonsList all available VM skeleton templates.
Returns a dictionary of VM skeleton names and their descriptions. These skeletons can be used as starting points for building custom VMs.
Categories include:
Returns: Dictionary with skeleton names as keys and descriptions as values
Example: skeletons = await list_vm_skeletons() # Returns: {"dc-2022": "Windows Server 2022 Domain Controller", ...}
list_yaml_examplesList all available YAML configuration examples.
Returns ready-to-use YAML configuration examples that can be directly saved to a file and deployed with Ludus.
Available examples:
Returns: Dictionary with example names and descriptions
Example: examples = await list_yaml_examples() # Then use get_yaml_example("basic_ad") to get the YAML content
migrate_sqlite_to_pocketbaseMigrate from SQLite to PocketBase.
Returns: Migration result
migrate_to_sdnMigrate to SDN networking.
Returns: SDN migration result
monitor_deploymentMonitor deployment progress with periodic updates.
move_ansible_role_scopeMove Ansible roles between user and global scope (Ludus 2.0 only).
A globally scoped role is usable by every user on the server; a user-scoped role is private to its owner. Promoting a role to global is how you make a custom role available to a whole class or team.
optimize_resource_allocationOptimize resource allocation for the range.
optimize_templateOptimize a template for better performance.
power_off_rangePower off all VMs in the range.
power_on_rangePower on all VMs in the range.
preview_profile_changesPreview changes that would be made by applying a profile without modifying the config.
This is a dry-run tool that shows what would happen if you applied a profile, without actually modifying the configuration. Useful for understanding the impact before committing to changes.
preview_scenarioPreview a scenario before deployment with detailed information.
IMPORTANT: Generates a FRESH configuration preview for the specified scenario. Use this BEFORE deploy_scenario to verify what will be deployed.
Shows VMs, network topology, resource requirements, and deployment estimates. Each preview call builds the scenario from scratch with your specified parameters.
provision_oauth2_userProvision an OAuth2 user (Ludus 2.0 only).
publish_scenarioPublish a scenario to the community repository.
quick_statusGet one-line deployment status with emoji indicators.
range_access_logsGet range access logs.
regenerate_user_apikeyDESTRUCTIVE: issue a NEW API key for a user, invalidating the old one.
Ludus has no endpoint that reads back an existing API key - this endpoint always mints a new one, so any client still using the previous key immediately starts getting "Invalid API key". Do not call this to look up or display a key; only call it when the user explicitly asks to rotate or reset their credentials.
remove_ranges_from_groupRemove ranges from a group.
remove_snapshotDelete a snapshot from one or more VMs.
remove_userRemove a user from the Ludus system.
remove_users_from_groupRemove users from a group.
revoke_range_accessRevoke range access from a user.
revoke_range_from_userRevoke range access from a user.
rollback_snapshotRoll one or more VMs back to a snapshot.
rotate_credentialsSuggest new credentials for VMs in the range. DOES NOT APPLY THEM.
Ludus exposes no API for setting VM user passwords, so this only generates strong candidates and explains how to apply them with Ansible. Nothing on any machine is changed. Do not report to a user that credentials have been rotated based on this tool's output.
schedule_maintenance_windowSchedule a maintenance window for the range.
schedule_range_tasksSchedule a recurring task for the range.
schedule_snapshotsSchedule automatic snapshots for VMs.
security_auditRun security audit on the range.
set_auto_shutdownSet how long a range may sit idle before it powers itself off.
This is the main lever for keeping a shared Ludus host from filling up with forgotten running labs.
set_default_rangeSet user's default range.
set_group_quotasSet default quotas for one or more groups (admin only).
Group quotas apply to members who have no explicit per-user quota, which makes them the right tool for handing a class or team a uniform budget.
set_user_quotasSet resource quotas for one or more users (admin only).
Only the quotas you pass are changed; omitted ones keep their current value. Setting a quota below what a user is already consuming does not tear anything down, but blocks their next deployment.
setup_sdnSetup SDN infrastructure.
Returns: SDN setup result
share_blueprint_with_groupsShare a blueprint with groups.
share_blueprint_with_usersShare a blueprint with users.
share_range_configGenerate a shareable copy of the range configuration.
slack_notificationsConfigure Slack notifications for deployment status.
smart_deploySmart deployment with validation, optional snapshot, and auto-monitoring.
RECOMMENDED: This is the preferred method for deploying scenarios as it includes validation, error checking, and monitoring guidance.
NO FILE UPLOAD REQUIRED: This tool automatically generates the configuration from the scenario parameters. You do NOT need to provide a config file.
Workflow:
When to use:
snapshot_hostCreate a snapshot of one or more VMs in the range.
start_testingStart testing state for the range.
stop_testingStop testing state for the range.
suggest_range_enhancementsSuggest enhancements to improve a range configuration.
Given a basic range description, this tool suggests additional components, capabilities, and improvements to make the range more realistic, educational, or aligned with specific training goals.
sync_sourceRe-fetch a source so its catalog reflects the current upstream.
template_diffCompare two templates and show differences.
test_network_connectivityTest network connectivity between VMs.
unshare_blueprint_with_groupsUnshare a blueprint from groups.
unshare_blueprint_with_usersUnshare a blueprint from users.
update_blueprint_configUpdate blueprint configuration.
update_range_configUpdate range configuration.
update_sourceUpdate an existing source's URL, tracked ref, or backing archive.
Changing the ref is how you move a source onto a different branch or pin it to a tag. Follow with sync_source to re-fetch the catalog.
update_testing_vmRe-run Ansible against a VM or group.
Testing mode must be STOPPED first: while a test is in progress Ludus rejects this with HTTP 409 "Testing is enabled; stop testing to update VMs". Call stop_testing before this.
validate_configValidate range configuration before deployment.
validate_templateValidate a template configuration.
webhook_integrationConfigure a webhook for range events.
whoamiTest authentication and get user info.
Returns: Current user information
BEFORE YOU INSTALL
231 tools when we connected.
LUDUS_JWT_TOKEN in your environment
CONTEXT COST
Rated by the size of the 231 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
pipx install git+https://github.com/tjnull/Ludus-FastMCP
ludus-fastmcp --setup
ludus-fastmcp --list-tools{
"mcpServers": {
"ludus": {
"command": "ludus-fastmcp",
"env": {
"LUDUS_API_URL": "https://<YOUR_LUDUS_INSTANCE>:8080",
"LUDUS_API_KEY": "<YOUR_LUDUS_API_KEY>"
}
}
}
}The configuration on this page does not set LUDUS_JWT_TOKEN; the project's instructions set it with an export line. An app opened from its icon or dock does not see variables exported in a terminal, so to supply LUDUS_JWT_TOKEN, use the block's "env" section.
In AnythingLLM open Settings → Agent Configuration → Agent Skills, scroll to MCP Servers and click Add new MCP Server.
Set Transport Type to stdio, Name to ludus and Command to ludus-fastmcp.
Add the environment variables LUDUS_API_URL (your Ludus server URL) and LUDUS_API_KEY (the key ludus user apikey prints on your Ludus server), then save and enable the server.
{
"mcpServers": {
"ludus": {
"transport": "stdio",
"command": "ludus-fastmcp",
"env": {
"LUDUS_API_URL": "https://<YOUR_LUDUS_INSTANCE>:8080",
"LUDUS_API_KEY": "<YOUR_LUDUS_API_KEY>"
}
}
}
}The configuration on this page does not set LUDUS_JWT_TOKEN; the project's instructions set it with an export line. An app opened from its icon or dock does not see variables exported in a terminal, so to supply LUDUS_JWT_TOKEN, use the block's "env" section.
MCP servers
AStheTECH
Sitequest-Software
sibilleb
binadox-public