home / mcp / ludusmcp mcp server

LudusMCP MCP Server

Provides a Model Context Protocol server to manage Ludus lab environments via natural language prompts and tool support.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "darkstar326-ludusmcp": {
      "command": "ludus-mcp",
      "args": []
    }
  }
}

You run an MCP server locally to manage Ludus lab environments through natural language commands. This server hosts the Model Context Protocol integration, enabling your MCP client to securely access Ludus capabilities from your workstation.

How to use

Start your MCP client (for example Claude Desktop). The client automatically launches the Ludus-MCP server, loads credentials from your OS credential store, fetches latest configurations and schemas, tests connectivity to the Ludus server, and then enables tool communication through the MCP protocol. You can perform range management, configuration changes, and Ludus documentation searches via prompts built into your client.

How to install

Prerequisites you must have before installing the MCP server:

- Node.js 18.0.0 or higher

- npm package manager

- Ludus CLI binary installed and in PATH on the host with the MCP client

- Active Ludus server environment and network access to Ludus server

- WireGuard VPN or SSH access to Ludus server

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

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

If you prefer developing from source, clone the project and install dependencies locally

git clone https://github.com/NocteDefensor/LudusMCP.git
cd LudusMCP
npm install
npx ludus-mcp --setup-keyring

Update the MCP server when new versions are available

npm install -g ludus-mcp@latest

Configuration

Initial setup securely stores credentials and configures how you connect to Ludus. Run the setup wizard to configure credentials:

npx ludus-mcp --setup-keyring

During setup you will be prompted for the connection method (WireGuard VPN or SSH tunnel), your Ludus Admin Username, your Ludus API key, SSH credentials, and optionally the WireGuard config path.

Update existing credentials later if needed

npx ludus-mcp --renew-keyring

Operating modes and usage notes

The MCP client manages connectivity. If WireGuard is available, the server connects directly for non-admin operations. For admin operations, an SSH tunnel is used. If WireGuard is not available, the SSH tunnel remains the fallback and is automatically managed by the MCP server.

Troubleshooting and safety

Common issues include connectivity problems, credential problems, and configuration validation failures. Start by ensuring the WireGuard tunnel is active, verify SSH access, and check the API key. Validate configurations before deployment and inspect logs for detailed error messages.

Security and credentials

All credentials are stored in your OS credential manager. Use secure dialogs for credential collection and avoid exposing sensitive values in command lines.

Tools and prompts availability

You can access a range of Ludus-related prompts, including guided range creation, secure command execution, configuration reading/writing, and documentation searches. Use the MCP prompts available in your client to begin these workflows.

Available tools

deploy_range

Deploy virtualized training environment. Creates and provisions the necessary VMs and resources for the range.

get_range_status

Check deployment status and VM states for a given range.

list_user_ranges

List all ranges available to the current user.

get_connection_info

Download RDP/VPN connection files for accessing deployed VMs.

destroy_range

Permanently delete a deployed range and its virtual machines.

range_abort

Stop a deployment that is stuck or failing.

ludus_power

Start or stop range VMs to control resource usage.

read_range_config

Read the current range configuration.

write_range_config

Create or modify range configurations.

validate_range_config

Validate YAML syntax and schema for a range configuration.

list_range_configs

Browse available range configuration templates.

get_range_config

Get the currently active configuration.

set_range_config

Set an active configuration for deployment.

ludus_docs_search

Search Ludus documentation for quick reference.

ludus_range_planner

Intelligent assistant for planning range requirements and deployments.

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 the schema for range configurations.

ludus_range_config_check_against_plan

Validate a range configuration against deployment requirements.

ludus_read_role_collection_schema

View role/collection schemas.

ludus_list_role_collection_schemas

List all available role/collection schema files.

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 user credentials.

insert_creds_range_config

Inject credentials into configurations (note: credential handling occurs via the OS credential manager).

ludus-mcp_config_read

Read and validate MCP server configuration files.