Simul MCP Server

MCP (Model Context Protocol) server for simulation and DCC tools with USD operations and simulation control.

Overview

This project provides a comprehensive MCP server implementation for Simul-MCP, enabling AI models to interact with USD scenes, perform simulation control, and capture viewport data. The server supports both headless USD operations and full Isaac Sim runtime integration.

Simul-MCP is designed for multi-engine workflows. Isaac Sim is the primary runtime, with planned adapters for Blender, Unreal, Maya, and 3ds Max. The goal is to expose consistent tools across engines for scale correction, SimReady asset formats, and engine-specific simulation features.

Features

USD Operations: Load, analyze, and manipulate USD files
Scene Analysis: Extract scene information, prim details, and mesh statistics
Bounding Box Computation: Calculate world and local space bounding boxes
Mesh Operations: Analyze mesh topology, materials, and geometry
Isaac Sim Integration: Viewport capture, simulation control, camera management
Flexible Architecture: Works in both headless and Isaac Sim runtime environments
Comprehensive Logging: Structured logging with multiple output formats
Configuration Management: YAML-based configuration with environment variable support

Requirements

Core Requirements

Python 3.8+
USD Python bindings (pxr)
FastMCP
Pydantic v2
PyYAML
NumPy

Isaac Sim Requirements (Optional)

NVIDIA Isaac Sim 5.1.0+
isaacsim.code_editor.vscode extension enabled (TCP port 8226)

Installation

# Clone the repository
git clone https://github.com/kickthemoon0817/simul.git
cd simul

# Install in development mode
pip install -e .

# Or install with all dependencies
pip install -e ".[dev,test]"

Agent Integration

Simul MCP works with any MCP-compatible AI coding agent. Configure your agent to use the simul-mcp server command as an MCP server.

Claude Code

Add to ~/.claude/settings.json under mcpServers:

{
  "mcpServers": {
    "simul": {
      "command": "simul-mcp",
      "args": ["server"]
    }
  }
}

Or use the CLI:

claude mcp add simul -- simul-mcp server

Codex (OpenAI)

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "simul": {
      "command": "simul-mcp",
      "args": ["server"]
    }
  }
}

OpenCode

Add to ~/.config/opencode/config.json under mcpServers:

{
  "mcpServers": {
    "simul": {
      "command": "simul-mcp",
      "args": ["server"]
    }
  }
}

Prerequisites for Isaac Sim Tools

Isaac Sim tools require a running Isaac Sim instance with the isaacsim.code_editor.vscode extension enabled (TCP port 8226). Launch Isaac Sim before using any isaac_* tools. Use ping_isaac to verify connectivity.

Quick Start

1. Start the MCP Server

# Basic startup
simul-mcp server

# With custom configuration
simul-mcp server --config config/custom.yaml --verbose

2. Test USD Operations

# Analyze a USD file
simul-mcp usd info /path/to/scene.usd

# Check server capabilities
simul-mcp info

# View tool usage statistics
simul-mcp stats

3. Use with Isaac Sim

Launch Isaac Sim with the isaacsim.code_editor.vscode extension enabled
Start your AI agent (Claude Code, Codex, or OpenCode) with simul MCP configured
The agent can now use 75+ Isaac Sim tools for scene control, rendering, physics, and more

Usage

Command Line Interface

# Start the MCP server
simul-mcp server

# Start with custom configuration
simul-mcp server --config config/isaac/default.yaml

# Start with verbose logging
simul-mcp server --verbose

# Show server information and capabilities
simul-mcp info

# Test USD file loading and analysis
simul-mcp usd info /path/to/scene.usd

# Validate configuration file
simul-mcp validate-config config/isaac/default.yaml

# Show version information
simul-mcp version

Isaac Sim Extension

Open Isaac Sim
Go to Window → Extensions
Search for "Isaac Sim MCP Server"
Enable the extension
Use the MCP Server panel to start/stop the server

The extension provides:

Server start/stop controls
Configuration options (transport, log level)
Real-time status monitoring
Tool availability display
Log viewer

Python API

from simul_mcp.mcp.server import SimulMCPServer
from simul_mcp.config import get_settings

# Create and run server
settings = get_settings()
server = SimulMCPServer(settings)
await server.run("stdio")

Headless USD Operations

from simul_mcp.adapters import HeadlessUSDAdapter

adapter = HeadlessUSDAdapter()
with adapter.create_session() as session:
    # Load USD file
    stage_id = session.load_stage("/path/to/scene.usd")

    # Get stage information
    stage_info = session.get_stage_info(stage_id)
    print(f"Stage has {stage_info.prim_count} prims")

    # Generate scene summary
    summary = session.summarize_stage(stage_id)
    print(f"Scene summary: {summary.total_prims} prims, {summary.hierarchy_depth} levels deep")

    # Find mesh prims
    meshes = session.find_prims_by_type(stage_id, "Mesh")
    print(f"Found {len(meshes)} mesh prims")

    # Analyze specific mesh
    if meshes:
        mesh_info = session.get_mesh_info(stage_id, meshes[0])
        print(f"Mesh has {mesh_info['vertex_count']} vertices, {mesh_info['face_count']} faces")

Configuration

The server uses YAML configuration files. See config/isaac/default.yaml for all available options:

server:
  name: "Simul - 3D Simulation & DCC Tools"

logging:
  level: "INFO"
  format: "detailed"
  file:
    enabled: true
    path: "logs/simul_mcp.log"
    max_size: "10MB"
    backup_count: 5
  console:
    enabled: true
    colored: true

usd:
  cache:
    enabled: true
    stage_cache_limit: 10
  files:
    max_file_size_mb: 500
    allowed_extensions: [".usd", ".usda", ".usdc", ".usdz"]

viewport:
  capture:
    width: 1920
    height: 1080
    max_size: 2048
    format: "png"

isaac_sim:
  path: "${ISAAC_SIM_PATH}"
  socket_host: "127.0.0.1"
  socket_port: 8226
  socket_timeout: 30.0

Environment Variables

You can override configuration using environment variables:

export LOGGING__LEVEL=DEBUG
export USD__CACHE_ENABLED=false
export VIEWPORT__MAX_SIZE=4096

MCP Tools

The server provides 75+ tools across multiple backends. Key tool categories:

Headless USD (no runtime required)

load_usd_file, validate_usd_file, get_prim_info, search_prims, summarize_scene, get_mesh_info, get_bounding_box, create_prim, delete_prim, update_prim_attributes

Isaac Sim — Scene Inspection

get_isaac_stage_info, list_isaac_prims, get_isaac_prim_info, get_isaac_prim_transform, search_isaac_prims, get_isaac_scene_summary, get_isaac_subtree, get_isaac_prim_ancestors, get_isaac_prim_relationships, get_isaac_prim_variants, get_isaac_scene_stats

Isaac Sim — Prim Manipulation

create_isaac_prim, delete_isaac_prim, set_isaac_prim_transform, set_isaac_prim_visibility, set_isaac_prim_attribute, duplicate_isaac_prim, reparent_isaac_prim

Isaac Sim — Viewport & Camera

list_isaac_cameras, get_isaac_camera_info, set_isaac_camera, capture_isaac_viewport, focus_isaac_viewport, get_isaac_viewport_info

Isaac Sim — Physics

get_isaac_physics_scene, create_isaac_physics_scene, get_isaac_rigid_body_info, add_isaac_rigid_body, add_isaac_collision, get_isaac_collision_info, get_isaac_joint_info, get_isaac_mass_properties, set_isaac_mass_properties, set_isaac_physics_material, list_isaac_physics_objects

Isaac Sim — Simulation Control

get_isaac_simulation_state, start_isaac_simulation, pause_isaac_simulation, stop_isaac_simulation, step_isaac_simulation, reset_isaac_simulation, get_isaac_simulation_time

Isaac Sim — Materials

get_isaac_material_info, list_isaac_materials, assign_isaac_material, set_isaac_material_property, create_isaac_material

Isaac Sim — Rendering & AOVs

read_isaac_aovs, list_isaac_aovs, list_isaac_render_vars, get_isaac_carb_settings, set_isaac_carb_settings

Isaac Sim — USD Schema Queries

query_isaac_typed_prims — find prims by schema type (UsdLux, UsdGeom, UsdShade) and read attributes in one call

Isaac Sim — Extensions & Assets

list_isaac_extensions, enable_isaac_extension, disable_isaac_extension, open_isaac_stage, save_isaac_stage, new_isaac_stage, import_isaac_asset, add_isaac_reference

Isaac Sim — Advanced

execute_isaac_script (custom Python), ping_isaac, raycast_isaac_scene, find_isaac_prims_in_area, get_isaac_texture_dependencies, list_isaac_instances, set_active_isaac_instance

Observability

get_tool_usage_stats, reset_tool_usage_stats — per-tool call counts, success rates, and durations via persistent JSONL log

Blender (when runtime connected)

52 tools for scene objects, materials, rigid bodies, constraints, modifiers, mesh operations, animation, physics baking, viewport capture, and SimReady compliance.

Unreal Engine (when runtime connected)

55 tools for actors, physics, materials, mesh operations, viewport, asset import/export, and procedural generation.

Examples

Basic USD Analysis

# examples/isaac/sample_usd_reader.py
python examples/isaac/sample_usd_reader.py /path/to/scene.usd --verbose

This example demonstrates:

Loading USD files
Extracting stage information
Finding prims by type
Computing bounding boxes
Generating scene summaries
Analyzing mesh statistics

HTTP Client Example

# examples/isaac/http_client_mcp.py
python examples/isaac/http_client_mcp.py --server http://localhost:8000 --usd-file /path/to/scene.usd

This example shows how to:

Connect to MCP server via HTTP
Call MCP tools programmatically
Handle responses and errors
Demonstrate both USD and Isaac Sim operations

MCP Tool Usage

import asyncio
from simul_mcp.mcp.server import SimulMCPServer

async def example():
    server = SimulMCPServer()

    # Load USD file
    result = await server.mcp.tools["load_usd_file"]("/path/to/scene.usd")
    if result.get("success", True):
        stage_id = result["stage_id"]

        # Get scene summary
        summary_result = await server.mcp.tools["summarize_scene"](
            stage_id=stage_id,
            include_meshes=True,
            format="text"
        )

        if summary_result.get("success", True):
            print(summary_result["digest"])

asyncio.run(example())

Development

Project Structure

simul-mcp/
├── pyproject.toml          # Project configuration
├── README.md              # This file
├── .env.example           # Environment variables template
├── .gitignore            # Git ignore rules
├── Makefile              # Development tasks
├── config/               # Configuration files
│   └── isaac/            # Isaac Sim configuration
│       ├── default.yaml  # Default configuration
│       ├── logging.yaml  # Logging configuration
│       └── kits/         # Isaac Sim Kit configurations
├── scripts/              # Shell scripts
│   └── isaac/            # Isaac Sim helpers
│       ├── run_kit_mcp.sh   # Linux/macOS launcher
│       ├── run_kit_mcp.ps1  # Windows launcher
│       └── dev_isort_black.sh # Code formatting
├── src/simul_mcp/        # Main source code
│   ├── __init__.py       # Package initialization
│   ├── config.py         # Configuration management
│   ├── logging.py        # Logging setup
│   ├── usd/             # USD operations
│   ├── adapters/        # Runtime adapters
│   ├── mcp/             # MCP server implementation
│   └── utils/           # Utility modules
├── src/simul_mcp/cli/    # Command-line interface
│   └── main.py          # CLI implementation
├── exts/                # Isaac Sim extension
│   └── khemoo.simul.mcp/ # Extension package
├── tests/               # Test suite
│   └── isaac/           # Isaac Sim tests
├── examples/            # Example scripts
│   └── isaac/           # Isaac Sim examples

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/isaac/test_reader.py

# Run with coverage
pytest --cov=simul_mcp tests/

# Run tests with verbose output
pytest -v tests/

SimulationApp Smoke Test

# Run a minimal Isaac Sim smoke check
/isaac-sim/python.sh scripts/smoke_simulationapp.py

Code Formatting

# Format code using the provided script
./scripts/isaac/dev_isort_black.sh

# Or use make
make format

# Or manually
isort src/ tests/ examples/
black src/ tests/ examples/

Development Tasks

# Install development dependencies
pip install -e ".[dev,test]"

# Run linting
make lint

# Run type checking
make typecheck

# Run all checks
make check

# Clean build artifacts
make clean

Architecture

The project follows a modular architecture with clear separation of concerns:

Core Components

Configuration System: Pydantic-based configuration with YAML support
Logging System: Structured logging with multiple handlers and formatters
USD Operations: Pure pxr-based USD file operations and analysis
Adapter Layer: Abstraction between USD operations and runtime environments
MCP Server: FastMCP-based server with tool registry and connection management

Runtime Environments

Headless Mode: Uses pure pxr library for USD operations without GUI
Isaac Sim Mode: Full integration with Isaac Sim runtime for simulation and viewport operations

Key Design Principles

Modularity: Each component has a single responsibility
Extensibility: Easy to add new tools and capabilities
Error Handling: Comprehensive error handling with proper logging
Performance: Caching and optimization for large USD files
Type Safety: Full type hints and Pydantic validation

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Run the test suite (pytest)
Run code formatting (make format)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow PEP 8 style guidelines
Add type hints to all functions
Write docstrings for all public functions and classes
Add tests for new functionality
Update documentation as needed
Use meaningful commit messages

Troubleshooting

Common Issues

USD Library Not Found
```
ImportError: pxr library not available
```
Solution: Install USD Python bindings or run within Isaac Sim environment
Isaac Sim Not Available
```
Isaac Sim runtime not available
```
Solution: Run the server within Isaac Sim or use headless mode only
Configuration Errors
```
ValidationError: Invalid configuration
```

Solution: Check configuration file syntax and validate with simul-mcp validate-config

Port Already in Use
```
Address already in use
```
Solution: Change the server port or stop the existing server

Debug Mode

Enable debug logging for detailed troubleshooting:

simul-mcp server --log-level DEBUG

Or set environment variable:

export LOGGING__LEVEL=DEBUG

License

This project is licensed under the MIT License. See LICENSE for details.

Support

For issues and questions:

GitHub Issues: https://github.com/kickthemoon0817/simul/issues
Documentation: https://github.com/kickthemoon0817/simul/wiki
Discussions: https://github.com/kickthemoon0817/simul/discussions

Acknowledgments

NVIDIA Isaac Sim team for the simulation platform
Pixar for the USD format and libraries
The MCP community for the protocol specification
Contributors and users of this project

Name		Name	Last commit message	Last commit date
Latest commit History 83 Commits
.claude-plugin		.claude-plugin
.github		.github
agents		agents
commands		commands
config		config
docs/api		docs/api
examples		examples
scripts/isaac		scripts/isaac
skills		skills
src/simul_mcp		src/simul_mcp
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
VERSION		VERSION
pyproject.toml		pyproject.toml
skills.md		skills.md

Folders and files

Latest commit

History

Repository files navigation

Simul MCP Server

Overview

Features

Requirements

Core Requirements

Isaac Sim Requirements (Optional)

Installation

Agent Integration

Claude Code

Codex (OpenAI)

OpenCode

Prerequisites for Isaac Sim Tools

Quick Start

1. Start the MCP Server

2. Test USD Operations

3. Use with Isaac Sim

Usage

Command Line Interface

Isaac Sim Extension

Python API

Headless USD Operations

Configuration

Environment Variables

MCP Tools

Headless USD (no runtime required)

Isaac Sim — Scene Inspection

Isaac Sim — Prim Manipulation

Isaac Sim — Viewport & Camera

Isaac Sim — Physics

Isaac Sim — Simulation Control

Isaac Sim — Materials

Isaac Sim — Rendering & AOVs

Isaac Sim — USD Schema Queries

Isaac Sim — Extensions & Assets

Isaac Sim — Advanced

Observability

Blender (when runtime connected)

Unreal Engine (when runtime connected)

Examples

Basic USD Analysis

HTTP Client Example

MCP Tool Usage

Development

Project Structure

Running Tests

SimulationApp Smoke Test

Code Formatting

Development Tasks

Architecture

Core Components

Runtime Environments

Key Design Principles

Contributing

Development Guidelines

Troubleshooting

Common Issues

Debug Mode

License

Support

Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages