CyberEdu MCP Server

This is the Oficial Model Context Protocol (MCP) server for the CyberEdu CTF platform (https://cyber-edu.co / https://cyberedu.ro). This server automatically discovers and exposes all methods from the CyberEduClient as MCP tools, making it easy to interact with the CyberEdu platform through MCP-compatible clients.

Features

Dynamic Tool Discovery: Automatically discovers all public methods from CyberEduClient and exposes them as MCP tools
Zero Configuration for New Methods: When new methods are added to CyberEduClient, they automatically become available as MCP tools without any code changes
Type-Safe: Automatically generates JSON schemas from method signatures and type hints
Error Handling: Comprehensive error handling with detailed error messages

CyberEDU Platform Overview

CyberEDU is a cybersecurity training platform that provides hands-on labs, realistic simulations, and competitive environments. It’s designed for enterprise security teams, academic institutions, government agencies, and individual learners.

Core Description

CyberEDU is a comprehensive cybersecurity training platform that provides hands-on labs, realistic simulations, and competitive environments. It's designed for enterprise security teams, academic institutions, government agencies, and individual learners who want to develop practical cybersecurity skills through real-world scenarios.

Key Differentiators

Hands-on approach: Interactive cyber ranges where users attack and defend real infrastructure (not just videos or theory)
MITRE ATT&CK mapping: Scenarios mapped to MITRE ATT&CK, using real malware samples (safely contained)
Better retention: 3.5x better skill retention compared to passive learning
Real-world scenarios: Simulates actual adversary techniques and attack patterns

Platform Components

Cyber Range — Enterprise-scale cyber warfare simulation with complex network topologies
Cyber Labs — 650+ hands-on labs mapped to MITRE ATT&CK, browser-based and auto-graded
Tournament Suite — Gamified competitions (CTFs, Red vs Blue, war games)

Key Statistics

30,000+ active users worldwide
650+ hands-on labs
1,400+ simulation profiles
500+ events hosted
45+ countries served
250+ hours of training content

Target Audiences

Students: Career-focused training with CTF challenges and leaderboards
Academia: Curriculum with LMS integration and auto-grading
Enterprise: Technical hiring assessments, team training, compliance mapping
Government: Air-gapped deployments, OT/SCADA simulation, critical infrastructure defense

Deployment Options

Cloud-hosted SaaS (browser-based, no installation)
On-premise (VMware, Proxmox, bare-metal)
Air-gapped deployments for classified environments

Installation

Clone the Repository

The cyberedu-client is included as a git submodule. Clone with --recursive to get everything:

git clone --recursive https://github.com/CyberEDU-Cyber-Range/cyberedu-mcp.git
cd cyberedu-mcp

If you already cloned without --recursive, initialize the submodule:

git submodule update --init --recursive

Install Packages

Install both packages (client and MCP server):

macOS/Linux:

python3 -m venv venv  
source venv/bin/activate
pip install -e ".[local]"      # Installs with local cyberedu-client submodule
# Or for development:
# pip install -e ".[local,dev]"

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -e ".[local]"      # Installs with local cyberedu-client submodule

Windows (Command Prompt):

python -m venv venv
venv\Scripts\activate.bat
pip install -e ".[local]"

Alternative: Install packages separately:
pip install -e ./cyberedu-client
pip install -e .

Configuration

Session Persistence (Recommended)

The MCP server automatically persists session credentials to disk. This means:

Set your cookie once using the cyberedu_set_session_cookie tool, and it will be remembered across MCP sessions
No environment variables needed after the first authentication
Tenant selection is preserved when you switch tenants

Session file location:

macOS/Linux: ~/.cyberedu-mcp/session.json
Windows: %USERPROFILE%\.cyberedu-mcp\session.json (e.g., C:\Users\YourName\.cyberedu-mcp\session.json)

The file has restricted permissions (owner read/write only) for security on Unix systems.

Environment Variables (Alternative)

You can also use environment variables. The server loads credentials in this priority order:

Persisted credentials from disk (highest priority)
Environment variables
Defaults

Environment variables:

CYBEREDU_SESSION_COOKIE: Your CyberEdu session cookie
- Get this from your browser's developer tools after logging in to https://app.cyber-edu.co
- Look for the cyberedu_session cookie value
CYBEREDU_TENANT: Your tenant identifier (optional, defaults to "cyberedu")

Getting Your Session Cookie

Chrome/Edge:

Open Developer Tools (F12)
Go to Application/Storage tab
Navigate to Cookies → https://app.cyber-edu.co
Find cyberedu_session and copy its value

Firefox:

Open Developer Tools (F12)
Go to Storage tab
Navigate to Cookies → https://app.cyber-edu.co
Find cyberedu_session and copy its value

Usage

Running the MCP Server

The server can be run directly (for testing):

macOS/Linux:

python3 -m venv venv

source venv/bin/activate
python -m cyberedu_mcp

Windows:

python -m venv venv
.\venv\Scripts\Activate.ps1
python -m cyberedu_mcp

MCP Client Configuration

To use this server with an MCP client (Cursor IDE or Claude Desktop), add it to your MCP configuration.

Important: Use the full path to the Python executable in your venv. MCP clients run servers externally and won't have access to an activated virtual environment.

macOS/Linux Examples

Cursor IDE (~/.cursor/mcp.json):

{
  "mcpServers": {
    "cyberedu": {
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "cyberedu": {
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Windows Examples

Cursor IDE (%APPDATA%\Cursor\User\mcp.json or C:\Users\YourName\.cursor\mcp.json):

{
  "mcpServers": {
    "cyberedu": {
      "command": "C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "cyberedu": {
      "command": "C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Cross-Platform Examples

VS Code (.vscode/mcp.json in your workspace):

{
  "servers": {
    "cyberedu": {
      "type": "stdio",
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"]
    }
  }
}

Windows: Use C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe

Antigravity / Windsurf (mcp_config.json - access via MCP store → Manage MCP Servers → View raw config):

{
  "mcpServers": {
    "cyberedu": {
      "command": "/path/to/cyberedu-mcp/venv/bin/python3",
      "args": ["-m", "cyberedu_mcp"],
      "env": {}
    }
  }
}

Windows: Use C:\\path\\to\\cyberedu-mcp\\venv\\Scripts\\python.exe

Note: Session credentials are persisted to ~/.cyberedu-mcp/session.json, so no environment variables are needed after the first authentication via the cyberedu_set_session_cookie tool.

Available Tools

The server automatically exposes all public methods from CyberEduClient as MCP tools. Tools are prefixed with cyberedu_ to avoid naming conflicts.

Session Management Tools

These tools allow you to manage authentication and tenant switching without restarting the MCP server. Credentials are automatically persisted to ~/.cyberedu-mcp/session.json:

cyberedu_get_session_status - Check if authenticated, which tenant is selected, and if credentials are persisted
cyberedu_set_session_cookie - Set/update the session cookie for authentication (persists to disk)
cyberedu_switch_tenant - Switch to a different tenant/organization (persists to disk)
cyberedu_clear_session - Clear stored credentials from disk and memory

Example usage:

Check status: "What's my CyberEdu session status?"
Set cookie: "Set my CyberEdu session cookie to eyJ..." (only needed once, persists!)
Switch tenant: "Switch to tenant myorg"
Clear credentials: "Clear my CyberEdu session"

Authentication & User Tools

cyberedu_check_auth - Verify authentication and get user info
cyberedu_get_user_info - Get full user information
cyberedu_list_tenants - List all available tenants
cyberedu_get_current_tenant_info - Get current tenant information
cyberedu_get_user - Get user information by ID

Challenge Tools (Archive)

cyberedu_list_challenges - List all challenges (with optional filters)
cyberedu_get_challenge - Get challenge details
cyberedu_get_challenge_difficulties - Get available difficulty levels
cyberedu_get_challenge_tags - Get available challenge tags
cyberedu_subscribe_to_challenge - Subscribe to a challenge

Flag & Submission Tools (Archive)

cyberedu_get_flag - Get flag/question information
cyberedu_submit_flag - Submit a flag/answer

File Tools (Archive)

cyberedu_download_file - Download a challenge file (use optional save_path param to save directly to disk)

Service Tools (Archive)

cyberedu_start_service - Start a challenge service
cyberedu_get_service_status - Get service status
cyberedu_extend_service - Extend service time
cyberedu_restart_service - Restart service

Contest Tools

cyberedu_list_contests - List all available contests
cyberedu_get_contest - Get contest details
cyberedu_get_contest_ranks - Get contest leaderboard
cyberedu_get_contest_challenge - Get challenge details within a contest
cyberedu_subscribe_to_contest_challenge - Subscribe to a contest challenge

Contest Flag & Submission Tools

cyberedu_get_contest_flag - Get flag information within a contest
cyberedu_submit_contest_flag - Submit a flag within a contest

Contest File Tools

cyberedu_download_contest_file - Download a file from a contest challenge (use optional save_path param to save directly to disk)

Contest Service Tools

cyberedu_start_contest_service - Start a service within a contest
cyberedu_get_contest_service_status - Get service status within a contest
cyberedu_extend_contest_service - Extend service time within a contest
cyberedu_restart_contest_service - Restart service within a contest

Usage Examples & Prompts

Example prompts for interacting with the CyberEdu MCP server:

Session & Authentication

"Check my CyberEdu session status"
"Set my CyberEdu session cookie to eyJpdiI6Ik..."
"Switch to tenant 'mycompany'"

Challenges (Archive)

"List all web security challenges"
"Show me the easiest challenges from tenant unbreakable/rocsc"
"Show me hard difficulty forensics challenges"
"Get details for challenge abc123"
"Subscribe me to this challenge and start the service"
"Download challenge files to ./downloads/"
"Submit flag 'CTF{i-like-web-security-ctf-challenges}' for this challenge"

Contests

"List available CTF contests"
"Show leaderboard for contest 'defcamp ctf quals 2025'"
"Get challenge abc123 from contest 'rocsc26-quals'"
"Start service for this contest challenge"
"Submit flag 'FLAG{solved}' for contest challenge"

Workflow Example

1. "List easy web challenges from tenant rocsc"
2. "Subscribe to 'why-xor' and start the service"
3. "Download the challenge files"
4. [Solve...]
5. "Submit flag 'CTF{xor-is-not-safe}'"

Architecture

Dynamic Tool Discovery

The server uses Python's inspect module to automatically discover all public methods from the CyberEduClient class. For each method:

Method Discovery: Scans the class for public methods (excluding private methods and helpers)
Schema Generation: Automatically generates JSON schema from method signatures and type hints
Tool Registration: Registers each method as an MCP tool with appropriate metadata

Tool Registry

The ToolRegistry class provides a flexible system for managing tools:

Automatic Discovery: Discovers methods from classes using introspection
Manual Registration: Allows manual registration of custom methods
Category Organization: Automatically categorizes methods (auth, challenges, contests, services, etc.)

Extensibility

To add new functionality:

Add methods to CyberEduClient: Simply add new public methods to the CyberEduClient class
Automatic Exposure: The MCP server will automatically discover and expose the new methods
No MCP Code Changes: No changes needed to the MCP server code

For custom tools that don't map directly to client methods:

from cyberedu_mcp.tool_registry import ToolRegistry

registry = ToolRegistry()

def custom_tool(param1: str, param2: int) -> dict:
    """Custom tool description."""
    return {"result": f"{param1}: {param2}"}

registry.register_method(
    name="custom_tool",
    method=custom_tool,
    description="A custom tool",
    category="custom"
)

Error Handling

The server provides comprehensive error handling:

HTTP Errors: Returns detailed HTTP error information including status codes and response bodies
Validation Errors: Returns clear error messages for missing or invalid parameters
Client Errors: Returns structured error information for all exceptions

Documentation

Additional documentation is available in the docs/ folder:

docs/index.md - Documentation overview and quick reference
docs/architecture.md - Server design, tool discovery, and session management
docs/extending.md - How to add custom tools and modify behavior

License

MIT