sionna-mcp

MCP server exposing NVIDIA Sionna RT ray-tracing as 15 structured tools for AI agents.

Install

pip install -e ".[dev]"

Requirements: Python 3.11+, sionna>=1.0 (tested with 1.2.2), mcp[cli]>=1.0, PyTorch with CUDA (optional but recommended).

Jetson / no-OptiX note: On NVIDIA Jetson (aarch64) and other systems without OptiX, sionna-mcp automatically falls back to the LLVM CPU backend (llvm_ad_mono_polarized). CUDA-accelerated ray tracing requires OptiX (libnvoptix.so.1), available only on x86_64.

Related MCP server: Hayba

Run

# Direct
python server.py

# As installed CLI (after pip install -e .)
sionna-mcp

The server uses stdio transport (MCP standard). Configure your agent runtime to spawn it as a subprocess.

Built-in Scenes

Pass "builtin:<name>" as scene_path in load_scene to use Sionna's bundled scenes without copying files:

For custom scenes, place the .xml file in SIONNA_SCENES_ROOT and use the filename as scene_path.

Environment Variables

Tools (16)

Environment

• sionna_status — Check Sionna/PyTorch/CUDA availability

Scene Management

• load_scene — Load scene XML at a carrier frequency

• inspect_scene — List objects, nodes, and array configs in a loaded scene

Node Management

• add_transmitter — Place a TX node (position, orientation, power_dbm)

• add_receiver — Place an RX node

• add_drone_receiver — Place a drone RX with velocity + antenna offset

• update_node_pose — Update TX/RX position and orientation

Antenna Arrays

• set_antenna_array — Configure planar array (pattern, polarization, rows×cols) for TX or RX

Ray Tracing

• compute_paths — Run Sionna PathSolver; returns job_id

• extract_cir_tool — Extract CIR (a, tau) as NPZ artifact

• extract_cfr_tool — Extract CFR as NPY artifact

• extract_csi_tool — Extract CSI with shape [N_tx, N_rx, N_sub, N_ant] as complex64

Dataset Generation

• run_trajectory — Loop drone over positions, extract channel per position, save labeled samples; supports micro-Doppler via propeller_rpm/num_blades/propeller_ids

• export_dataset — Bundle all trajectory samples into a single NPZ file

• get_artifact — Retrieve local path + size for a sionna:// URI

Sim-to-Real

• inject_noise — Add AWGN and/or phase jitter to a CSI .npy artifact; accepts single file or dataset directory

Error Codes

Using with an AI Agent

sionna-mcp uses the MCP (Model Context Protocol) stdio transport. Any MCP-compatible agent (Claude Code, Claude Desktop, Cursor, etc.) can drive it.

Claude Code

Add to your project's .claude/mcp.json:

{
  "mcpServers": {
    "sionna-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/sionna-mcp/server.py"],
      "env": {
        "SIONNA_SCENES_ROOT": "/absolute/path/to/scenes",
        "SIONNA_ARTIFACTS_ROOT": "/absolute/path/to/artifacts"
      }
    }
  }
}

Or if installed as a CLI (pip install -e .):

{
  "mcpServers": {
    "sionna-mcp": {
      "command": "sionna-mcp",
      "env": {
        "SIONNA_SCENES_ROOT": "/absolute/path/to/scenes",
        "SIONNA_ARTIFACTS_ROOT": "/absolute/path/to/artifacts"
      }
    }
  }
}

Then start Claude Code in your project — the agent will have all 15 tools available automatically.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "sionna-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/sionna-mcp/server.py"]
    }
  }
}

Restart Claude Desktop after saving.

What to tell the agent

Once connected, you can give the agent natural-language tasks. Examples:

"Load the Munich scene at 3.5 GHz, place a base station TX at [0, 0, 30] and a UE receiver at [50, 0, 1.5], run ray tracing with 3 reflections, and extract CSI with 64 subcarriers."

"Simulate a drone flying 10 positions along the X-axis from [0,0,50] to [90,0,50], collecting channel data at each point and exporting a labeled NPZ dataset."

"Check if Sionna and CUDA are available on this machine."

The agent will call the tools in the correct order, handle job_id / artifact_uri chaining between steps, and return the final file path to you.

Typical tool call sequence

sionna_status            → confirm environment
load_scene               → returns scene_id
set_antenna_array        → configure TX/RX arrays (optional)
add_transmitter          → returns tx_id
add_receiver / add_drone_receiver  → returns rx_id / drone_id
compute_paths            → returns job_id (PathSolver runs here)
extract_csi_tool         → returns artifact_uri  (sionna://...)
get_artifact             → returns local file path + size

For drone datasets:

load_scene → add_transmitter → add_drone_receiver
→ run_trajectory (loops internally over all positions)
→ export_dataset → get_artifact

Example sessions

• examples/urban_single_tx_rx.json — single-link urban simulation (3.5 GHz, 2×2 MIMO)

• examples/drone_trajectory.json — 10-position drone CSI dataset (5.8 GHz)

CSI Shape Convention

CSI has canonical shape [N_tx, N_rx, N_sub, N_ant] in complex64:

• N_tx — number of transmitters

• N_rx — number of receivers

• N_sub — number of subcarriers (equals num_subcarriers parameter)

• N_ant — virtual MIMO antenna product: N_tx_ant × N_rx_ant

Reproducibility (SC-003)

Set seed in compute_paths and ensure diffraction=False for reproducible CSI across runs.

• CUDA backend (x86_64 with OptiX): byte-identical results across runs with the same seed.

• LLVM backend (Jetson / no OptiX): numerically reproducible, max per-element difference < 1e-6.

Running Tests

pytest tests/unit/          # No Sionna required
pytest tests/integration/   # Requires Sionna installed

Tool Contracts

See specs/001-home-jetson-sionna/contracts/tools.md for full JSON schema contracts.