immersive-cre-mcp

MCP server for immersive Cyber Ranges (CRE), built for range authors. It covers the whole dashboard: scenarios, flags (with answers), briefing and walkthrough markdown, documents, templates, labs, systems, networking, snapshots, VPN, events and users.

Open source and self-service. This project is provided as-is and supported by its community. Bug reports, feature ideas and pull requests are all welcome: open an issue or send a pull request.

This uses the same public API the CRE web dashboard calls: any registered account can reach it by signing in. It isn't formally documented or versioned (see docs/API.md for the endpoints as observed), so a dashboard release can change it.

Installation

Requires Python 3.12+. Run it without installing via uvx, or install it with pipx or pip:

uvx immersive-cre-mcp            # run on demand, nothing to install
pipx install immersive-cre-mcp   # or install the command globally
pip install immersive-cre-mcp    # or into an existing environment

From git

To use a version that isn't on PyPI, install straight from the repository. Add @<ref> to pin a tag, branch or commit; leave it off to get the latest main.

uvx --from git+https://github.com/Immersive-Labs-Public/immersive-cre-mcp@v0.3.1 immersive-cre-mcp
pipx install git+https://github.com/Immersive-Labs-Public/immersive-cre-mcp@v0.3.1
pip install "immersive-cre-mcp @ git+https://github.com/Immersive-Labs-Public/immersive-cre-mcp@<commit-sha>"

With uvx, pass the same --from in your client config (see Add to a client):

"command": "uvx",
"args": ["--from", "git+https://github.com/Immersive-Labs-Public/immersive-cre-mcp@v0.3.1", "immersive-cre-mcp"]

uvx caches the build, so a pinned tag or commit is fetched only once. For a branch, add --refresh to the uvx arguments to pick up new commits.

Configuration

Settings are read from environment variables, so set them in your MCP client's config (or in a .env file in the server's working directory).

Add to a client

Claude Code:

claude mcp add immersive-cre \
  -e IMMERSIVE_CRE_USERNAME=you@example.com \
  -e IMMERSIVE_CRE_PASSWORD='...' \
  -- uvx immersive-cre-mcp

Claude Desktop, Cursor, VS Code or any other MCP client (JSON config):

{
  "mcpServers": {
    "immersive-cre": {
      "command": "uvx",
      "args": ["immersive-cre-mcp"],
      "env": {
        "IMMERSIVE_CRE_USERNAME": "you@example.com",
        "IMMERSIVE_CRE_PASSWORD": "..."
      }
    }
  }
}

If you installed with pipx or pip, use "command": "immersive-cre-mcp" with no args instead.

Add "IMMERSIVE_CRE_READ_ONLY": "true" to env to explore safely without any write or delete tools.

The server also runs over HTTP with immersive-cre-mcp --transport streamable-http.

Example usage

Once connected, ask your assistant in plain language. For example:

• "List my scenarios and show the flags for the one called Ransomware Response."
• "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."
• "Reorder the flags in my Web App scenario so the easy ones come first, and add a hint to each."
• "In my AD Lab, add a DMZ subnet on 10.10.5.0/24 that accepts only TCP 80 and 443 from the attacker subnet, then add an Ubuntu web server on it at 10.10.5.10."
• "Give the web server a second interface on the internal subnet at 10.10.1.50 so it can reach the domain controller."
• "Lock down the internal subnet: allow RDP and SMB from the user subnet only and drop everything else inbound."
• "Set the lab's DHCP domain to corp.local with 10.10.1.10 as the DNS server, and push the same DNS settings to VPN users."
• "Add the Juice Shop on 10.10.3.59:3000 as an app participants can open from the lab page."
• "Which labs are running right now, and when do they shut down?"
• "Upload network-diagram.pdf as a document on the Phishing Triage scenario."
• "Show the scoreboard for event 42."

Tools (88)

Tools are annotated read / write / destructive, so clients can prompt before destructive calls.

Authoring notes:

• Flags: the API only saves the whole list. The flag tools read, modify and write it back, and generate FlagIds for new flags. Answers, hints and MITRE tags are always returned.
• Markdown: set_markdown uploads to S3, then waits (up to 30s) for the backend to register the new version, so a read straight after a write is current.
• Costs: launching or powering labs spends AWS money and counts against the account's lab limit.

Development

Requires uv.

git clone https://github.com/Immersive-Labs-Public/immersive-cre-mcp.git
cd immersive-cre-mcp
uv sync
cp .env.example .env   # then fill in credentials

A .env in the project root is picked up whatever the working directory, so a client can run your checkout directly:

claude mcp add immersive-cre -- uv run --project /path/to/immersive-cre-mcp immersive-cre-mcp

{"mcpServers": {"immersive-cre": {"command": "uv", "args": ["run", "--project", "/path/to/immersive-cre-mcp", "immersive-cre-mcp"]}}}

To try tools interactively, use the MCP Inspector: npx @modelcontextprotocol/inspector uv run immersive-cre-mcp. Set LOG_LEVEL=DEBUG for more logging.

Checks

CI runs these on every push and pull request; run them locally before opening a PR:

uv run ruff check .   # lint
uv run mypy           # type check
uv run pytest         # unit tests (add --cov for coverage)

The unit tests mock all HTTP, so they need no credentials and never reach the live API. They ignore your .env, and they don't touch the token cache.

Layout

src/immersive_cre_mcp/
  client.py      auth (IL → Hydra OAuth → token cookie, or Cognito), GET/POST transport, S3 upload/download
  cognito.py     Cognito SRP sign-in for standalone CRE accounts
  config.py      settings (environment / .env)
  app.py         MCPServer instance, tool() decorator, shared helpers
  server.py      entry point (immersive-cre-mcp)
  tools/         one module per area (scenarios, flags, content, templates, labs, systems, events, account)
docs/API.md      endpoint reference (as observed from the dashboard)
tests/           unit tests (HTTP mocked with respx)

License

MIT