Ludusmcp

🚀 LudusMCP

LudusMCP is a Model Context Protocol server that enables the management of Ludus lab environments through natural - language commands, enhancing user - friendliness and efficiency.

🚀 Quick Start

Before starting with LudusMCP, make sure to meet the prerequisites. For detailed information, please refer to the wiki. After that, you can choose an installation method according to your needs and then configure and use the server as described in the following sections.

✨ Features

• Natural Language Management: Manage Ludus lab environments using natural - language commands.
• Multi - Installation Methods: Support both global installation and installation from source.
• Secure Credential Management: Store credentials securely in the OS credential manager.
• Rich Toolset: Provide a variety of tools for range management, configuration management, documentation search, etc.

📦 Installation

NOTE: The MCP server is not installed on the Ludus server. It should be installed on a device with an MCP client (e.g., 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:

1. Downloads source code and dependencies.
2. Compiles native dependencies (keytar) for your platform (Windows/Linux/macOS).
3. Builds TypeScript source to JavaScript (src/ → dist/).
4. Creates a 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.

📚 Documentation

Prerequisites

System Requirements

• Node.js 18.0.0 or higher.
• npm package manager.
• Ludus CLI binary [installed](https://docs.ludus.cloud/docs/quick - start/using - cli - locally) and in PATH on the host with the mcp - client (e.g., claude desktop).
• Active Ludus server environment.
• Network connectivity to the 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 or user account on the Ludus server. Non - admin will be limited in the same ways as using the ludus cli with a non - admin account.

Configuration

Initial Setup

Run the setup wizard to configure credentials securely (from within the 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.
• API Key: Ludus API key from the ludus user apikey command.
• SSH Credentials: Host, username, and authentication method.
• WireGuard Config: Path to the .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 the cloned directory if installing from source)

To modify existing credentials:

npx ludus-mcp --renew-keyring

Connection Methods

WireGuard VPN (Recommended)

• Direct connection to the Ludus server for non - admin functions via VPN tunnel.
• Requires a WireGuard client and configuration file.
• Must be manually started before using the MCP client.

SSH Tunnel

• Port forwarding through an SSH connection.
• Fallback option when WireGuard is unavailable.
• Automatically managed by the MCP server.
• The SSH tunnel will always be used for the ADMIN API.

MCP Client Integration

Setup Process Overview

1. Install Package (one - time): Compiles for your platform.
2. Configure Credentials (one - time): Run the setup wizard.
3. Configure MCP Client (one - time): Add to the client config.
4. Daily Usage: Start the MCP client, and the 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:

1. Launches the pre - compiled ludus - mcp server.
2. The server loads credentials from the OS keyring.
3. Downloads fresh configurations from GitHub.
4. Downloads updated schemas and documentation.
5. Tests connectivity to the Ludus server.
6. Starts the MCP protocol for tool communication.

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

Manual Server Testing (Optional)

For troubleshooting or testing the server independently:

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

Server Startup Process:

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

Available Prompts

create - ludus - range Complete the 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, look 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 a virtualized training environment.
• get_range_status - Check deployment status and VM states.
• list_user_ranges - List all ranges for the user.
• get_connection_info - Download RDP/VPN connection files.
• destroy_range - Permanently delete a 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 the currently active configuration.
• set_range_config - Set the 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 the 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 the placeholder with the 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:

1. Create a YAML file in ~/.ludus - mcp/schemas/ following the standard format.
2. Use a distinctive name to avoid conflicts (e.g., company.custom_role.yaml).
3. Include all required fields: name, type, description, variables.
4. 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

1. Plan Your Range Use the create - ludus - range prompt for guided range creation:

   Requirements: "AD environment with SCCM and 3 workstations"
   

2. Review Configuration Use list_range_configs to see available templates and read_range_config to examine them.
3. Validate Before Deployment Always run validate_range_config before setting the configuration.
4. Set Active Configuration Use set_range_config to make the configuration active for deployment.
5. Deploy Range Use deploy_range to create the virtualized environment.
6. 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 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 the OS credential manager.

Credential Management

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

Network Security

• WireGuard VPN encryption for server communication.
• SSH tunnel fallback with key - based authentication.
• SSL certificate verification (configurable).

Operational Safety

• Destructive operations require explicit confirmation.
• Automatic validation of configurations before deployment.
• Comprehensive logging and error handling.

Troubleshooting

Connection Issues

• Verify the WireGuard tunnel is active: wg show.
• Test SSH connectivity: ssh user@ludus - host.
• Check the 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 the WireGuard config.

Common Errors

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

Help

For additional help:

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

References

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

Coming Changes

• May switch to [Desktop Extension](https://www.anthropic.com/engineering/desktop - extensions) setup instead of the current home - grown keyring config/renew functions.
• May make a remote mcp server version to be able to interact with Ludus from any device on the network regardless of having the 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 research.
• 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