sofa-mcp

MCP server for the SOFA physics simulation framework. Exposes 24 tools for controlling SOFA simulations over stdio transport.

Install

Run inside the Python environment SOFA is linked to:

pip install -e .

For development tools (pytest, mypy, ruff):

pip install -e ".[dev]"

Connect

Claude Desktop

Add to the config file for your OS:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sofa-mcp": {
      "command": "sofa-mcp"
    }
  }
}

Claude Code (CLI)

claude mcp add sofa-mcp sofa-mcp

Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "sofa-mcp": {
      "command": "sofa-mcp"
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "sofa-mcp": {
      "type": "stdio",
      "command": "sofa-mcp"
    }
  }
}

Tools

Category	Tools
Scene	create_scene, load_scene_file, add_child_node, add_component, get_scene_graph, save_scene, unload_scene
Simulation	init_simulation, step_simulation, step_simulation_n, step_and_render, reset_simulation, get_state, get_node_energy
Data	get_field_value, set_field_value, list_components, list_component_fields, get_mechanical_state, set_mechanical_state
Visualizer	init_visualizer, render_frame
Utility	query_available_components, load_plugins

Demos

python demos/falling_sofa_demo.py

Set SOFA_ROOT if your SOFA install differs from the default (/opt/sofa/install):

SOFA_ROOT=/path/to/sofa python demos/falling_sofa_demo.py

Test

pytest sofa_mcp/tests/test_mcp_tools.py      # no SOFA needed
pytest sofa_mcp/tests/test_sofa_bridge.py    # SOFA-dependent tests auto-skip