LudusMCP

You are setting up and running LudusMCP, a Model Context Protocol server that lets you manage Ludus lab environments through natural language prompts. This MCP server acts as a bridge between your MCP client and Ludus, handling credential management, connectivity, and tool interactions so you can plan, deploy, and control lab deployments with ease.

How to use

Start by installing the MCP server on a device that has access to the Ludus environment. Your MCP client will launch and manage the server automatically once configured. You use your MCP client to interact with the server through the available Ludus tools, which include range deployment, configuration management, and documentation lookups. The server handles authentication, connectivity (WireGuard or SSH), and downloads up-to-date configurations and schemas as needed. You can then deploy ranges, retrieve connection information, and monitor deployment status directly from your MCP client.

How to install

Prerequisites include Node.js 18.0.0 or higher, npm, and a Ludus CLI binary that is accessible on the host. You also need an active Ludus server environment and network access to Ludus via WireGuard VPN or SSH.

Step-by-step installation on a device with an MCP client (for example Claude Desktop):

# Global installation (recommended)
npm install -g ludus-mcp@latest
ludus-mcp --setup-keyring

# What happens during installation:
# 1. Downloads source code and dependencies
# 2. Compiles native dependencies (keytar) for your platform
# 3. Builds TypeScript to JavaScript (dist/)
# 4. Creates global ludus-mcp command in PATH

Configuration and credentials

Configure credentials securely through the setup wizard. This stores credentials in your OS credential manager and configures the connection method, admin identity, API key, and access details.

npx ludus-mcp --setup-keyring

Connection methods

Choose your connection method during setup. WireGuard VPN provides direct access to Ludus for non-admin functions, while an SSH tunnel serves as a fallback and is used for admin operations.

Starting the MCP client

When you start your MCP client, it will automatically launch the Ludus MCP server, load credentials from the OS keyring, fetch the latest configurations and schemas, test connectivity to Ludus, and enable the MCP protocol for tool communication.

Troubleshooting tips

If you encounter issues, re-check the connection method, verify the WireGuard tunnel is active, and confirm the API key and credentials are correctly stored in the OS credential manager.

Usage notes for prompts and tools

You can access a variety of Ludus tools through prompts in your MCP client, including range deployment, configuration management, and documentation search. Use the prompts to plan, validate, and deploy without manually editing configurations.

Available tools

deploy_range

Deploy a virtualized training environment based on a prepared range configuration.

get_range_status

Query the status of a deployed range and its VMs.

list_user_ranges

List all ranges accessible to the current user.

get_connection_info

Download RDP/VPN or other connection files for deployed VMs.

destroy_range

Permanently delete a deployed range and its VMs.

range_abort

Stop a deployment that is stuck in progress.

ludus_power

Start or stop range VMs to manage compute resources.

read_range_config

Read the current range configuration file.

write_range_config

Create or modify a range configuration.

validate_range_config

Validate YAML syntax and schema of a range configuration.

list_range_configs

Browse available range configuration templates.

get_range_config

Get the currently active range configuration.

set_range_config

Set the active configuration used for deployment.

ludus_docs_search

Search Ludus documentation for quick references.

ludus_range_planner

Assist in planning a range with intelligent suggestions.

ludus_roles_search

Search available Ludus roles.

ludus_environment_guides_search

Find environment setup guides.

ludus_networking_search

Get help with network configuration.

ludus_read_range_config_schema

View the schema for range configurations.

ludus_range_config_check_against_plan

Validate configuration against deployment requirements.

ludus_read_role_collection_schema

View role/collection schemas.

ludus_list_role_collection_schemas

List all available role/collection schemas.

ludus_cli_execute

Execute arbitrary Ludus CLI commands.

ludus_help

Get help for Ludus CLI usage.

list_all_users

List all Ludus users (admin only).

get_credential_from_user

Securely collect credentials from the user.

insert_creds_range_config

Inject credentials into range configurations.