Overview
The immersive Cyber Ranges MCP server connects your AI assistant (such as Claude Code, Claude Desktop, Cursor or VS Code) to your Cyber Ranges account. Once it's connected, you can ask your assistant in plain language to build and manage ranges for you, including scenarios, flags, labs, systems, networks, templates and events.
This article explains how to install the server, connect it to your AI assistant, and check that it's working.
Note: The Cyber Ranges MCP server is an open-source project provided as-is and supported by its community. To report a bug or suggest a feature, open an issue on the GitHub repository.
Before You Begin
Make sure you have the following:
- A Cyber Ranges account. You can use your immersive platform login or a standalone Cyber Ranges account. The server signs in as you, so it can only do what your account is allowed to do.
- Your account's region. This is EU if you sign in at immersivelabs.online, or US if you sign in at us.immersivelabs.com.
- An MCP-compatible AI assistant, such as Claude Code, Claude Desktop, Cursor or VS Code.
- Python 3.12 or later, with uv installed (recommended), or pipx/pip.
Important: Launching or powering on labs uses cloud resources, which cost money and count towards your account's lab limit. Use read-only mode (see Step 3) while you get familiar with the server.
Step 1: Install the Server
You don't need to install anything ahead of time if you use uvx, because your assistant will download and run the server when it starts.
If you prefer to install it, open a terminal and run one of the following:
(Shell)
pipx install immersive-cre-mcp # installs the command globally
pip install immersive-cre-mcp # installs into an existing Python environment
Step 2: Add the Server to Your AI Assistant
Follow the instructions for your assistant.
Claude Code
- Open a terminal.
- Run the following command, replacing the email address and password with your own Cyber Ranges credentials:
(Shell)
claude mcp add immersive-cre \
-e IMMERSIVE_CRE_USERNAME=you@example.com \
-e IMMERSIVE_CRE_PASSWORD='your-password' \
-- uvx immersive-cre-mcp
- Restart Claude Code.
Claude Desktop, Cursor, VS Code and Other MCP Clients
- Open your assistant's MCP configuration file.
- Claude Desktop: go to Settings > Developer > Edit Config.
- Cursor: go to Settings > MCP > Add new MCP server.
- VS Code: open the Command Palette and select MCP: Add Server.
- Add the following entry, replacing the email address and password with your own:
(Json)
{
"mcpServers": {
"immersive-cre": {
"command": "uvx",
"args": ["immersive-cre-mcp"],
"env": {
"IMMERSIVE_CRE_USERNAME": "you@example.com",
"IMMERSIVE_CRE_PASSWORD": "your-password"
}
}
}
}
- Save the file and restart your assistant.
Tip: If you installed the server with pipx or pip in Step 1, set "command" to "immersive-cre-mcp" and remove the "args" line.
Step 3: Configure Optional Settings
Add any of the following settings alongside your username and password: in the env section of the configuration file, or as extra -e options for Claude Code.
| Setting | What it does | Values |
|---|---|---|
| IMMERSIVE_CRE_REGION | Selects the region your account is in. | eu (default) or us |
| IMMERSIVE_CRE_READ_ONLY | Lets the assistant view your ranges but not change or delete anything. | true or false (default) |
| IMMERSIVE_CRE_AUTH | Selects how the server signs in. Leave this as auto unless told otherwise by support. | auto (default), platform or cognito |
Note: If your account is in the US region, you must set IMMERSIVE_CRE_REGION to us, or the server won't be able to sign in.
Step 4: Check the Connection
- Open a new conversation with your AI assistant.
- Ask it something that only reads information, for example: "List my Cyber Ranges scenarios."
- Check that the assistant returns the scenarios from your account. If it does, the server is set up and ready to use.
What You Can Do
Ask your assistant in plain language. Here are some examples:
- "Create a scenario called Phishing Triage with a short briefing, and add three flags: the sender's IP, the malicious domain, and the payload's SHA256."
- "Rewrite the student walkthrough for scenario 1234 to fix the typos and make step 3 clearer."
- "In my AD Lab, add a DMZ subnet on 10.10.5.0/24 that only accepts TCP 80 and 443 from the attacker subnet."
- "Which labs are running right now, and when do they shut down?"
- "Show the scoreboard for event 42."
Tip: Most assistants ask for your approval before running an action that changes or deletes something. Read each request before you approve it.
Troubleshooting
The assistant can't find any Cyber Ranges tools. Restart your assistant after you save the configuration. Check that the configuration file is valid JSON (look for missing commas or quotation marks).
Sign-in fails or the assistant reports an authentication error.
- Check your username and password by signing in to the Cyber Ranges dashboard in your browser.
- Check that IMMERSIVE_CRE_REGION matches your account's region.
- If you use a standalone Cyber Ranges account (not an immersive platform login), set IMMERSIVE_CRE_AUTH to cognito.
uvx command not found. Install uv, or install the server with pipx and use immersive-cre-mcp as the command (see Step 1).
A tool that used to work has stopped working. The server uses the same API as the Cyber Ranges dashboard, so dashboard updates can occasionally affect it. Update to the latest version of the server. If the problem continues, raise an issue on GitHub.
Security Considerations
- There are no API tokens. The server signs in with your own credentials and has the same permissions as your account.
- Keep your password safe. Your configuration file contains your password, so don't share it or commit it to source control.
- Sign-in sessions are cached locally in a file that only you can read.
- Use read-only mode (IMMERSIVE_CRE_READ_ONLY=true) when you only need to view information.
Further Help
- Full installation and configuration reference: README on GitHub
- Report a bug or request a feature: GitHub issues