The MCP server is NOT installed on the Ludus server. It is installed on a device with an MCP client (like Claude Desktop) that has network access to the Ludus 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
• Network connectivity to Ludus server via WireGuard VPN or SSH

You must have:

• Ludus server SSH access credentials
• Ludus Admin API key (obtain via ludus user apikey command)
• WireGuard configuration file OR SSH tunnel capabilities (obtain WireGuard config from Ludus CLI)
• Admin or user account on Ludus server (non-admin accounts have same limitations as using Ludus CLI with non-admin account)

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: Windows Credential Manager
  • macOS: Keychain
  • Linux: libsecret

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

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

git clone https://github.com/NocteDefensor/LudusMCP.git
cd LudusMCP
npm install    # Installs dependencies and builds automatically
npx ludus-mcp --setup-keyring    # Use npx for local installations

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 the server executable

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

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

• Choose between WireGuard VPN or SSH tunnel
• WireGuard is recommended for better performance

Ludus Credentials

• Ludus Admin Username: Your Ludus admin account
• ADMIN API Key: Ludus API key from ludus user apikey command as Admin

SSH Connection Details (if using SSH tunnel)

• SSH host address
• SSH username
• Authentication method (password or key)

WireGuard Configuration (if using WireGuard)

• Path to WireGuard .conf file (retrieve this via the Ludus CLI command as an admin user ludus users wireguard)

Important Notes:

• Do NOT use quotes or single quotes around any values during setup
• Credentials are stored securely in your OS credential manager
• The setup only needs to be done once
• If you want to change the credentials run --renew-keyring

To modify existing credentials:

# From within cloned directory if installing from source
npx ludus-mcp --renew-keyring

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

SSH Tunnel

• Port forwarding through SSH connection
• Fallback option when WireGuard unavailable or can be used as standalone
• Automatically managed by MCP server
• SSH tunnel will always be used for admin API operations

This is a one-time setup process:

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

• I highly recommend you read this first. https://modelcontextprotocol.io/quickstart/user

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
}

For Source Installation

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

Replace /full/path/to/LudusMCP/ with the actual path where you cloned the repository.

For troubleshooting or testing the server independently:

# If globally installed (future)
ludus-mcp

# OR from cloned directory (current)
npx ludus-mcp

Server Startup Process:

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

1. Restart Claude Desktop completely
2. Start a new conversation
3. Ask Claude: "Can you list the available Ludus tools?"
4. You should see a list of Ludus MCP tools if everything is working

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

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

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

After installation and first run, the server creates:

~/.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/

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

• Check that npm global bin directory is in your PATH
• If installing from source, use npx ludus-mcp from within the cloned directory
• Try running npm list -g ludus-mcp to verify installation

• Verify your Ludus CLI works: ludus user list
• Check your API key: ludus user apikey
• Test network connectivity to your Ludus server
• If using WireGuard: Verify tunnel is active with wg show
• If using SSH: Test SSH connectivity with ssh user@ludus-host

• Check the config file path and JSON syntax
• Restart Claude Desktop completely
• Verify the command path is correct in the config
• For source installation, ensure the path to dist/server.js is absolute and correct

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

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

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

• "No configuration available": Run --setup-keyring
• "Range operations connectivity failed": Check WireGuard/SSH connection
• "Schema validation failed": Use validate_range_config tool
• Build failures: Ensure you have proper build tools for your platform

This is designed for lab use only. Security is limited but includes:

• Attempts to limit OS command injection and path traversal
• Credentials handled via OS credential manager
• External service credentials use placeholder format (IF the LLM obeys prompts. For non-range specific creds, user should require use of the get_credential_from_user and the insert_creds_range_config tool to securely store credentials and not pass them to LLM.
• Destructive operations require explicit confirmation

• Use ludus_help tool for Ludus CLI documentation
• Use ludus_docs_search for guides
• Check the GitHub repository for issues and updates
• Review Ludus Documentation