Ludus
A Model Context Protocol (MCP) server for automating Ludus v1 and v2 cyber range environments through AI assistants. 190+ tools for range management, blueprints, groups, templates, scenarios, and SIEM integration.
Ludus FastMCP
A Model Context Protocol (MCP) server for automating Ludus cyber range environments through AI assistants written in Python.
Overview
Ludus FastMCP enables AI-powered management of Ludus cyber ranges through natural language commands. The server exposes 190+ tools across 20 modules for range lifecycle management, scenario deployment, template creation, Ansible role management, and security monitoring integration.
Supports both Ludus v1 and v2 with automatic version detection. All existing v1 tools work unchanged, and v2 adds blueprints, groups, VM console, diagnostics, enhanced range management, and more.
Key Capabilities
| Category | Description |
|---|---|
| Range Management | Create, configure, deploy, and manage virtual lab environments |
| Blueprints | Save, share, and apply reusable range configurations (v2) |
| Groups | Organize users and ranges with group-based access control (v2) |
| Scenario Deployment | Pre-built scenarios for AD, red/blue/purple team, and malware analysis |
| Template Builder | Custom OS templates, skeleton configurations, and YAML generation |
| Role Management | Ansible Galaxy integration, custom roles, and subscription roles |
| SIEM Integration | Wazuh, Splunk, Elastic Stack, and Security Onion support |
| AI Configuration | Natural language to YAML configuration conversion |
| Diagnostics | System health, license info, and migration tools (v2) |
Supported Platforms
Works with any MCP-compatible client including Claude Desktop, VS Code (Cline), OpenWebUI, and AnythingLLM.
Quick Start
Requirements
- Python 3.11+
- Access to a Ludus server instance (v1 or v2)
- Ludus API key or JWT token (for v2 Pro/SSO users)
Installation
# Using pipx (recommended)
pipx install git+https://github.com/tjnull/Ludus-FastMCP
# From source
git clone https://github.com/tjnull/Ludus-FastMCP
cd Ludus-FastMCP
pip install -e .
Setup
Run the interactive setup wizard:
ludus-fastmcp --setup
The wizard configures API credentials, tests connectivity, and generates MCP client configuration files.
For manual configuration options, see the Configuration Guide.
Usage
MCP Server (ludus-fastmcp)
ludus-fastmcp --setup # Interactive setup wizard
ludus-fastmcp --list-tools # List all 190+ available tools
ludus-fastmcp --version # Display version information
ludus-fastmcp # Start MCP server
ludus-fastmcp --daemon # Run as background service
Client CLI (ludus-ai)
ludus-ai setup-llm # Configure local LLM (Ollama)
ludus-ai install anythingllm # Install AnythingLLM interface
ludus-ai tool list-tools # List available tools
ludus-ai tool call-tool <name> # Execute tools directly
Example Interactions
Once connected to an MCP client, interact with your Ludus environment:
Show my current range status
Deploy an Active Directory lab with Wazuh monitoring
Create a snapshot named "pre-attack" for all VMs
Build a lab with 2 domain controllers and 5 workstations
Create a blueprint from my current range and share it with the red-team group
Show system diagnostics and storage usage
List all groups and their members
Examples of using Ludus-FastMCP with grok code through Opencode.
Documentation
| Document | Description |
|---|---|
| Getting Started | Installation, setup, and first deployment |
| Configuration | Environment variables and MCP client setup |
| Tools Reference | Complete documentation for all 190+ tools |
| Scenarios | Pre-built deployment scenarios |
| Troubleshooting | Common issues and solutions |
| Safety | Safety features and best practices |
Ludus Version Compatibility
| Feature | Ludus v1 | Ludus v2 |
|---|---|---|
| Auto-detection | Automatic | Automatic |
| API Key auth | Yes | Yes |
| JWT auth (Pro/SSO) | No | Yes |
| Range management | Yes | Yes |
| Snapshots | Yes | Yes |
| Templates | Yes | Yes (+ subscription roles) |
| Blueprints | No | Yes |
| Groups | No | Yes |
| VM Console | No | Yes |
| Diagnostics | No | Yes |
| Multi-range access | No | Yes |
Version is auto-detected on first API call. Override with LUDUS_API_VERSION=v1 or LUDUS_API_VERSION=v2. v2-only tools return a clear error message when used against a v1 server.
Resources
| Resource | Link |
|---|---|
| Ludus Documentation | docs.ludus.cloud |
| Ludus API Reference | api-docs.ludus.cloud |
| Ludus GitHub | github.com/badsectorlabs/ludus |
| FastMCP Framework | gofastmcp.com |
| MCP Specification | modelcontextprotocol.io |
Support
- GitHub Issues - Bug reports and feature requests
- GitHub Discussions - Questions and community discussion
License
This project is licensed under the MIT License. See LICENSE for details.
Disclaimer
This software is intended for authorized security testing, educational purposes, and research in controlled environments. Users are responsible for compliance with applicable laws and organizational policies. The authors make no warranties and assume no liability for use or misuse of this software.
Acknowledgments
เซิร์ฟเวอร์ที่เกี่ยวข้อง
Alpha Vantage MCP Server
ผู้สนับสนุนAccess financial market data: realtime & historical stock, ETF, options, forex, crypto, commodities, fundamentals, technical indicators, & more
Perfetto
Turn natural language into powerful Perfetto trace analysis. Quickly explain jank, diagnose ANRs, spot CPU hot threads, uncover lock contention, and find memory leaks.
AI Agent Playwright
An AI agent for the Playwright MCP server, enabling automated web testing and interaction.
MCP Memory Gateway (rlhf-feedback-loop)
Local-first RLHF feedback loop for AI agents — capture preference signals, promote memories, block repeated mistakes, export DPO/KTO training pairs
TUUI - Tool Unitary User Interface
A desktop MCP client for tool integration and cross-vendor LLM API orchestration.
Remote MCP Server (Authless)
An example of a remote MCP server deployable on Cloudflare Workers without authentication.
OpenTelemetry Collector MCP Server
An MCP server for dynamically configuring OpenTelemetry Collectors, including receivers, processors, and exporters.
Grovs
MCP server for managing deep links, analytics, and app configuration on Grovs.io. Works with Claude Code, Cursor, Windsurf, and any MCP-compatible client.
Chart
A Model Context Protocol server for generating visual charts using AntV.
Comet Opik
Query and analyze your Opik logs, traces, prompts and all other telemtry data from your LLMs in natural language.
Tauri Development MCP Server
Build, test, and debug mobile and desktop apps with the Tauri framework faster with automated UI interaction, screenshots, DOM state, and console logs from your app under development.