# MaBoSS MCP server

> Lets an AI client perform stochastic Boolean network simulations, attractor analysis, and biological model configuration.

- Repository: https://github.com/marcorusc/mcp-biomodelling-servers
- Page: https://hostedmcp.org/servers/marcorusc/maboss
- Transport: stdio
- Stars: 20
- License: GPL-3.0
- Latest version: 2.5.2

## Install

### Claude Code

```sh
claude mcp add maboss -- uvx mcp-biomodelling-servers
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "maboss": {
      "command": "uvx",
      "args": [
        "mcp-biomodelling-servers"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "maboss": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-biomodelling-servers"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"maboss","type":"stdio","command":"uvx","args":["mcp-biomodelling-servers"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "maboss": {
      "command": "uvx",
      "args": [
        "mcp-biomodelling-servers"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add maboss -- uvx mcp-biomodelling-servers
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.maboss]
command = "uvx"
args = ["mcp-biomodelling-servers"]
```

### Gemini CLI

```sh
gemini mcp add -s user maboss uvx -- mcp-biomodelling-servers
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "maboss": {
      "command": "uvx",
      "args": [
        "mcp-biomodelling-servers"
      ]
    }
  }
}
```

## Tools (36)

- `export_configuration_bundle`: Save a unique ZIP with XML, supported inputs, checksums and working-directory instructions. Relative source inputs require the original executable working_directory. Does not include an executable or grant scientific approval.
- `configure_simulation_inputs`: Store explicitly typed parameters or register an existing x,y,z,type CSV. No edits means inspection. CSV registration requires explicit csv_enabled. Counts and random_seed are stored, not proof the target executable uses them.
- `create_session`: Create a new PhysiCell simulation session. Sessions allow independent work on multiple simulation configurations. Create one before calling any setup tools. Returns: str: Session ID and instructions.
- `list_sessions`: List all active simulation sessions with their status and progress. Returns: CallToolResult: Formatted text plus validated session metadata. (read-only)
- `list_artifact_sessions`: List all PhysiCell sessions that have artifact files on disk (including past server runs). Unlike list_sessions() which only shows in-memory sessions, this scans the artifacts/ directory and reads session_meta.json files, so previously created sessions are visible even after a server restart. Use the returned session_id and file paths to resume earlier work, e.g.: load_xml_configuration(xml_path='/path/to/artifacts/<uuid>/PhysiCell_settings.xml') (read-only)
- `set_default_session`: Switch the default session used by subsequent tool calls. Returns: str: Confirmation of the session switch.
- `get_workflow_status`: Return the current workflow status and recommended next steps. Alias for `get_simulation_summary()` — provides identical information. Prefer `get_simulation_summary()` for new code. Returns: str: Progress summary with completed steps and next recommendations. (read-only)
- `delete_session`: Delete a simulation session and all its state permanently. Returns: str: Confirmation of deletion.
- `import_maboss_handoff`: Verify and atomically attach a typed MaBoSS handoff through PhysiBoSS.
- `set_maboss_context`: Store MaBoSS model context for integration into a PhysiCell simulation. Typically called after analysing a MaBoSS model in the MaBoSS server. The stored context is used by `add_physiboss_model()` and `add_physiboss_input_link()`. Returns: str: Confirmation of context storage.
- `get_maboss_context`: Return all stored MaBoSS contexts or select one target cell type. Shows linked Boolean model paths, nodes, results, and handoff provenance. Returns: CallToolResult: Human-readable context plus a validated context list. (read-only)
- `load_xml_configuration`: Load an existing PhysiCell XML configuration file into the current session. After loading, inspect with `analyze_loaded_configuration()` or modify directly using tools such as `configure_cell_parameters()` and `add_single_cell_rule()`. Returns: str: Summary of loaded components and next steps.
- `validate_xml_file`: Validate a PhysiCell XML configuration file without loading it. Returns: str: Validation result — valid confirmation or error description. (read-only)
- `analyze_loaded_configuration`: Show an overview of the loaded XML configuration with modification instructions. Returns: str: Configuration summary (domain, substrates, cell types) with tool hints.
- `list_loaded_components`: Inspect stored components in created or imported configurations, including substrate origins. Returns: str: Detailed component information with parameter values and tool hints. (read-only)
- `analyze_biological_scenario`: Store a biological scenario description to provide context for subsequent simulation setup. This context is displayed alongside signal/behavior lists and helps inform parameter choices. Call this before `create_simulation_domain()` to anchor the session to a specific biology. Returns: str: Confirmation message.
- `create_simulation_domain`: Create the spatial and temporal framework for a PhysiCell simulation. Sets up the domain bounds, mesh resolution, and simulation duration. Must be called before adding substrates or cell types. The domain is centred at the origin: bounds run from -x/2 to +x/2 in each axis. In 2D mode (`use_2d=True`) the z extent is set to `dx` (one voxel thick) and `set_2D(True)` is applied so PhysiCell treats the simulation as planar. Returns: str: Confirmation with domain specs and next step.
- `add_single_substrate`: Add a chemical substrate (oxygen, glucose, drug, etc.) to the simulation environment. Substrates diffuse through the domain and can be consumed or secreted by cells. Call `create_simulation_domain()` first. Repeat for each substrate. Returns: str: Confirmation with substrate parameters and next step.
- `add_single_cell_type`: Add a cell type (cancer, immune, fibroblast, etc.) to the simulation. Cell types define the agents that populate the simulation domain. Call `create_simulation_domain()` first. Repeat for each cell type. After adding, use `configure_cell_parameters()` to set size and motility, and `add_single_cell_rule()` to define signal-response behaviours. Returns: str: Confirmation with cell type details and next step.
- `configure_cell_parameters`: Inspect or patch stored volume, motility, death and existing cycle transitions. Omit all changes to inspect. Explicit zero/false values are preserved. Patches are atomic; omitted settings and the selected cycle model are retained. Returns stored values and model identity, rather than echoing the request.
- `set_substrate_interaction`: Patch a cell type's secretion and uptake rates for one substrate. Both cell type and substrate must already exist in the current session. Omitted values preserve the current interaction. At least one rate must be supplied. Call repeatedly to configure multiple cell-substrate pairs or revise one pair after inspecting a simulation result. Returns the interaction values actually stored for the pair, and whether the configuration changed.
- `get_available_cycle_models`: List all available PhysiCell cell cycle models with their identifiers. Returns: str: Markdown list of model keys and names to use in `add_single_cell_type()`. (read-only)
- `list_all_available_signals`: List all PhysiCell signals that can be used in cell rules. Automatically expands to include substrate-specific and cell-type-specific signals based on components already added to the current session. Call `list_all_available_behaviors()` to see the corresponding behavior targets. Returns: str: Markdown table of signals grouped by type. (read-only)
- `list_all_available_behaviors`: List all PhysiCell behaviours that can be controlled by cell rules. Automatically expands to include substrate-specific and cell-type-specific behaviours based on components already added to the current session. Use exact behavior names in `add_single_cell_rule()`. Returns: str: Markdown table of behaviours grouped by type. (read-only)
- `add_single_cell_rule`: Add a signal-behaviour rule that makes cells respond to environmental cues. Rules are Hill-function dose-response relationships: when `signal` rises, `behavior` is increased or decreased according to a Hill curve parameterised by `saturation_value`, `half_max`, and `hill_power`. Use `list_all_available_signals()` and `list_all_available_behaviors()` first. Returns: str: Confirmation with rule summary and export readiness indicator.
- `add_physiboss_model`: Integrate a PhysiBoSS boolean network model into a cell type. The cell type must already exist. Requires PhysiBoSS support in the installed `physicell_config` package. After adding, call `configure_physiboss_settings()`, then `add_physiboss_input_link()` and `add_physiboss_output_link()`. Returns: str: Confirmation with model file paths and next step.
- `configure_physiboss_settings`: Patch timing, fractional stochasticity and inheritance on an attached model. Omitted settings are preserved. Returns actual stored values and model identity.
- `add_physiboss_input_link`: Create an input link from a PhysiCell signal to a MaBoSS boolean node. Requires a PhysiBoSS model already attached to the cell type. Returns the stored input mapping. Call `add_physiboss_output_link()` after all input links are defined.
- `add_physiboss_output_link`: Map a Boolean node to a cell behavior and return the stored mapping. The action determines Hill-response orientation. Finite steepness does not guarantee an exact Boolean switch. The supported engine reads integer steepness.
- `apply_physiboss_mutation`: Fix a MaBoSS boolean node to a constant value, simulating a genetic mutation. Requires a PhysiBoSS model already attached to the cell type. Call repeatedly to apply multiple mutations. Returns: str: Confirmation of the applied mutation.
- `get_simulation_summary`: Return a comprehensive summary of the current simulation configuration. Shows session progress, configured components (substrates, cell types, rules, PhysiBoSS models), completed workflow steps, and export readiness. Returns: str: Markdown summary of current simulation state. (read-only)
- `export_xml_configuration`: Export the complete PhysiCell configuration to an XML file in the session artifact directory. The generated file can be passed directly to a PhysiCell executable. A simulation domain must have been created before calling this. Returns: CallToolResult: Export guidance plus validated XML artifact metadata.
- `export_cell_rules_csv`: Export cell signal-behaviour rules to a CSV file in the session artifact directory. The generated file is used alongside `PhysiCell_settings.xml` by the PhysiCell executable. At least one rule must exist (added via `add_single_cell_rule()`). Returns: CallToolResult: Export guidance plus validated CSV artifact metadata.
- `list_generated_files`: List PhysiCell artifact files (XML/CSV) for the active session. Returns: CallToolResult: Grouped text plus validated artifact file metadata. (read-only)
- `clean_generated_files`: Remove all artifact files (XML, CSV, etc.) for the active session. Returns: CallToolResult: Cleanup confirmation plus the validated removal count.
- `get_help`: Return the same workflow guide exposed as a prompt and resource. Returns: str: Markdown-formatted help guide. (read-only)

## FAQ

### How do I start a simulation session?

You should start by calling `create_session()`, which creates an isolated in-memory session and may attach a human-readable label.

### Does the server require a separate MaBoSS executable?

No, the server does not need a separate MaBoSS executable as it uses the compiled engine installed with pyMaBoSS.

### Can I visualize the simulation results?

Yes, you can render trajectories using the `visualize_network_trajectories` tool, which returns a PNG image.

### How can I handle large numbers of outputs to improve performance?

You should select a small, biologically meaningful set of outputs using `set_maboss_output_nodes()` before running the simulation.
