Content
# sofa-mcp
MCP server for the [SOFA](https://www.sofa-framework.org/) physics simulation framework. Exposes 24 tools for controlling SOFA simulations over stdio transport.
## Install
Run inside the Python environment SOFA is linked to:
```bash
pip install -e .
```
For development tools (pytest, mypy, ruff):
```bash
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`
```json
{
"mcpServers": {
"sofa-mcp": {
"command": "sofa-mcp"
}
}
}
```
### Claude Code (CLI)
```bash
claude mcp add sofa-mcp sofa-mcp
```
### Cursor
Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
```json
{
"mcpServers": {
"sofa-mcp": {
"command": "sofa-mcp"
}
}
}
```
### VS Code (GitHub Copilot)
Add to `.vscode/mcp.json` in your workspace:
```json
{
"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
```bash
python demos/falling_sofa_demo.py
```
Set `SOFA_ROOT` if your SOFA install differs from the default (`/opt/sofa/install`):
```bash
SOFA_ROOT=/path/to/sofa python demos/falling_sofa_demo.py
```
## Test
```bash
pytest sofa_mcp/tests/test_mcp_tools.py # no SOFA needed
pytest sofa_mcp/tests/test_sofa_bridge.py # SOFA-dependent tests auto-skip
```
