Creates, inspects, modifies, and exports PhysiCell and PhysiBoSS configuration files for biological simulations.
Also known as marcorusc/mcp-biomodelling-servers, physicell, mcp-biomodelling-servers
- Stars
- 20
- Tools
- 36
- Downloads, 30 days
- 1,330
- Latest version
- 2.5.2
- Last commit
- Oct 28, 2026
- License
- GPL-3.0
What is PhysiCell Configuration Builder MCP?
PhysiCell Configuration Builder is an MCP server. Creates, inspects, modifies, and exports PhysiCell and PhysiBoSS configuration files for biological simulations. It exposes 36 tools, such as export_configuration_bundle, configure_simulation_inputs, create_session.
Summary generated from the project's README
About PhysiCell Configuration Builder MCP server
Researchers and computational biologists can use this server to build, inspect, and modify configuration files for biological simulations. It acts as a configuration builder for PhysiCell and PhysiBoSS rather than a simulation runtime, meaning it prepares the necessary XML and CSV files that must then be executed within a separate PhysiCell project. The server operates over stdio and is part of the mcp-biomodelling-servers Python package.
Users manage complex modeling tasks through sessions, allowing for multiple independent configurations to be active at once. The workflow involves defining a simulation domain, adding substrates like oxygen or nutrients, and defining cell populations. It provides specialized tools to patch cell parameters, set substrate interactions, and establish signal-behavior rules using Hill functions. For advanced modeling, it integrates with PhysiBoSS to attach intracellular MaBoSS models, enabling the mapping of signals to Boolean nodes and behaviors through specific input and output links.
What you can do with it
- 1Define simulation environment parametersSet the spatial dimensions, mesh resolution, and total simulation time for a new model.
- 2Integrate intracellular modelsImport and map MaBoSS models to PhysiCell cell types to simulate complex intracellular logic.
Written from the project's README. Every use case is checked against a quote from it.
How to install PhysiCell Configuration Builder MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall PhysiCell Configuration Builder MCP in Claude Code
$ claude mcp add physicell -- uvx --from mcp-biomodelling-servers mcp-physicell-serverInstall PhysiCell Configuration Builder MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"physicell": {
"command": "uvx",
"args": [
"--from",
"mcp-biomodelling-servers",
"mcp-physicell-server"
]
}
}
}Install PhysiCell Configuration Builder MCP in VS Code
.vscode/mcp.json
{
"servers": {
"physicell": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"mcp-biomodelling-servers",
"mcp-physicell-server"
]
}
}
}Install PhysiCell Configuration Builder MCP in VS Code CLI
$ code --add-mcp '{"name":"physicell","type":"stdio","command":"uvx","args":["--from","mcp-biomodelling-servers","mcp-physicell-server"]}'Install PhysiCell Configuration Builder MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"physicell": {
"command": "uvx",
"args": [
"--from",
"mcp-biomodelling-servers",
"mcp-physicell-server"
]
}
}
}Install PhysiCell Configuration Builder MCP in Codex
$ codex mcp add physicell -- uvx --from mcp-biomodelling-servers mcp-physicell-serverInstall PhysiCell Configuration Builder MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.physicell] command = "uvx" args = ["--from", "mcp-biomodelling-servers", "mcp-physicell-server"]
Install PhysiCell Configuration Builder MCP in Gemini CLI
$ gemini mcp add -s user physicell uvx -- --from mcp-biomodelling-servers mcp-physicell-serverInstall PhysiCell Configuration Builder MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"physicell": {
"command": "uvx",
"args": [
"--from",
"mcp-biomodelling-servers",
"mcp-physicell-server"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for mcp-biomodelling-servers 2.5.2 in an isolated container with no network and no keys. It answered and listed 36 tools.
PhysiCell Configuration Builder MCP tools 36
Read from the server with tools/listexport_configuration_bundleActionSave 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_inputsActionStore 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_sessionActionCreate 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_sessionsRead-onlyList all active simulation sessions with their status and progress. Returns: CallToolResult: Formatted text plus validated session metadata.
list_artifact_sessionsRead-onlyList 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')
set_default_sessionActionSwitch the default session used by subsequent tool calls. Returns: str: Confirmation of the session switch.
get_workflow_statusRead-onlyReturn 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.
delete_sessionActionDelete a simulation session and all its state permanently. Returns: str: Confirmation of deletion.
import_maboss_handoffActionVerify and atomically attach a typed MaBoSS handoff through PhysiBoSS.
set_maboss_contextActionStore 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_contextRead-onlyReturn 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.
load_xml_configurationActionLoad 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.
| 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. | Action |
| 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. | Action |
| 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. | Action |
| 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. | Action |
| 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. | Action |
| import_maboss_handoff | Verify and atomically attach a typed MaBoSS handoff through PhysiBoSS. | Action |
| 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. | Action |
| 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. | Action |
Show all 36 toolsShow fewer tools
validate_xml_fileRead-onlyValidate a PhysiCell XML configuration file without loading it. Returns: str: Validation result — valid confirmation or error description.
analyze_loaded_configurationActionShow an overview of the loaded XML configuration with modification instructions. Returns: str: Configuration summary (domain, substrates, cell types) with tool hints.
list_loaded_componentsRead-onlyInspect stored components in created or imported configurations, including substrate origins. Returns: str: Detailed component information with parameter values and tool hints.
analyze_biological_scenarioActionStore 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_domainActionCreate 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_substrateActionAdd 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_typeActionAdd 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_parametersActionInspect 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_interactionActionPatch 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_modelsRead-onlyList 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()`.
list_all_available_signalsRead-onlyList 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.
list_all_available_behaviorsRead-onlyList 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.
add_single_cell_ruleActionAdd 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_modelActionIntegrate 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_settingsActionPatch timing, fractional stochasticity and inheritance on an attached model. Omitted settings are preserved. Returns actual stored values and model identity.
add_physiboss_input_linkActionCreate 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_linkActionMap 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_mutationActionFix 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_summaryRead-onlyReturn 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.
export_xml_configurationActionExport 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_csvActionExport 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_filesRead-onlyList PhysiCell artifact files (XML/CSV) for the active session. Returns: CallToolResult: Grouped text plus validated artifact file metadata.
clean_generated_filesActionRemove all artifact files (XML, CSV, etc.) for the active session. Returns: CallToolResult: Cleanup confirmation plus the validated removal count.
get_helpRead-onlyReturn the same workflow guide exposed as a prompt and resource. Returns: str: Markdown-formatted help guide.
| 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. | Action |
| 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. | Action |
| 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. | Action |
| 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. | Action |
| 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. | Action |
| 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. | Action |
| 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. | Action |
| 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. | Action |
| 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. | Action |
| configure_physiboss_settings | Patch timing, fractional stochasticity and inheritance on an attached model. Omitted settings are preserved. Returns actual stored values and model identity. | Action |
| 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. | Action |
| 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. | Action |
| 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. | Action |
| 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. | Action |
| 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. | Action |
| 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. | Action |
| get_help | Return the same workflow guide exposed as a prompt and resource. Returns: str: Markdown-formatted help guide. | Read-only |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubPhysiCell MCP Server
The Wave 2 integration guide covers stored configuration readback, typed inputs, required-substrate visibility and portable bundles.
The PhysiCell server creates, loads, inspects, modifies, validates, and exports
PhysiCell configuration files through the Model Context Protocol (MCP). It uses
the physicell-settings
package to build PhysiCell_settings.xml, Cell Rules CSV files, and
PhysiBoSS intracellular-model settings.
This server is a configuration builder, not a PhysiCell simulation runtime. It does not launch a PhysiCell executable or analyze tissue-simulation output. Exported files must be placed in an appropriate PhysiCell project and executed with that project's compiled application.
The server is distributed in the
mcp-biomodelling-servers
Python package and communicates over stdio.
Installation and startup
Install all three bio-modelling servers:
python -m pip install mcp-biomodelling-servers
Start the installed PhysiCell server:
mcp-physicell-server
Alternatively, run it in an isolated environment:
uvx --from mcp-biomodelling-servers mcp-physicell-server
See the repository README for supported Python versions, complete MCP client configuration, and source-checkout instructions.
Sessions and configuration state
Use one PhysiCell session per independent model. create_session() selects the
new session as the default unless set_as_default=false is supplied:
{
"set_as_default": true,
"session_name": "hypoxic_tumor_v1"
}
Pass the full returned session_id explicitly whenever multiple configurations
are active. set_default_session() also accepts an unambiguous eight-character
session prefix.
list_sessionsreports active sessions, configuration presence, component counts, loaded-XML provenance, PhysiBoSS counts, and workflow progress.list_artifact_sessionsdiscovers files retained from current or previous server processes.get_workflow_statusandget_simulation_summaryreturn the same workflow state and recommended next steps.delete_sessionpermanently removes the in-memory session state.
Workflow progress records which configuration-building steps have been performed. It does not prove that parameter values are biologically justified, that all required custom code exists, or that the exported model will execute successfully in a particular PhysiCell project.
Build a new configuration
Use the following order:
- Call
create_session(). - Store the modelling objective with
analyze_biological_scenario(). - Define space, mesh, dimensionality, and duration with
create_simulation_domain(). - Call
add_single_substrate()once for every diffusible substrate. - Call
add_single_cell_type()once for every cell population. - Configure cell parameters and every required cell/substrate interaction.
- Discover exact signal and behavior names.
- Add as many signal-behavior rules as the model requires.
- Optionally attach and configure intracellular MaBoSS models through PhysiBoSS.
- Inspect the summary and read-only resources.
- When cell rules exist, export their CSV first and the XML second.
analyze_biological_scenario() stores the supplied text as session context. It
does not infer cell types, substrates, parameter values, or rules
automatically.
Recreating the domain resets the model
create_simulation_domain() creates a fresh PhysiCellConfig and replaces the
configuration currently stored in the session. Calling it after substrates,
cell types, rules, or PhysiBoSS models have been added discards those
components. Use the parameter patch tools—not a second domain call—to revise an
existing configuration.
Define the simulation domain
For a planar model:
{
"domain_x": 2000,
"domain_y": 2000,
"use_2d": true,
"dx": 20,
"max_time": 7200,
"session_id": "SESSION_ID"
}
In 2D mode, the z extent is one mesh voxel (dx) and PhysiCell's planar mode
is enabled. For a full 3D model, set use_2d=false and provide a positive
domain_z.
The domain is centered on the origin. max_time is expressed in minutes and
dx in micrometers. Smaller mesh spacing increases spatial resolution and
typically increases the cost of the eventual PhysiCell simulation.
Add substrates and cell types
Substrates
Call add_single_substrate() separately for oxygen, nutrients, drugs, or
other diffusing fields:
{
"substrate_name": "oxygen",
"diffusion_coefficient": 100000,
"decay_rate": 0.01,
"initial_condition": 38,
"units": "mmHg",
"dirichlet_enabled": true,
"dirichlet_value": 38,
"session_id": "SESSION_ID"
}
When Dirichlet boundaries are enabled, the tool applies the value to the x and
y boundaries and also to z boundaries in 3D. When dirichlet_value is
omitted, the initial condition is used.
Cell types
Use get_available_cycle_models() to inspect valid cycle names, then call
add_single_cell_type() once per population:
{
"cell_type_name": "cancer_cell",
"cycle_model": "Ki67_basic",
"session_id": "SESSION_ID"
}
Substrates and cell types must exist before tools can configure a specific cell/substrate pair or attach an intracellular model.
Flat partial-update semantics
The public configuration tools currently use flat optional arguments. Supply only the values that should change. The deferred nested-parameter-object redesign is not part of this release.
Each patch is prepared on a separate configuration copy and published only after it succeeds. A failed patch leaves the active configuration unchanged.
Patch cell parameters
configure_cell_parameters() supports:
volume_total;volume_nuclear;fluid_fraction;motility_speed;persistence_time;motility_enabled;apoptosis_rate;necrosis_rate.
At least one value is required. Every omitted value is preserved.
{
"cell_type": "cancer_cell",
"motility_speed": 0.8,
"motility_enabled": true,
"session_id": "SESSION_ID"
}
The same cell type can be revised later without repeating its motility values:
{
"cell_type": "cancer_cell",
"apoptosis_rate": 0.001,
"session_id": "SESSION_ID"
}
That second call preserves the earlier motility speed and enabled state. Repeat the tool independently for every cell type that needs configuration.
Patch one cell/substrate interaction
set_substrate_interaction() targets one existing cell-type/substrate pair:
{
"cell_type": "cancer_cell",
"substrate": "oxygen",
"uptake_rate": 10,
"session_id": "SESSION_ID"
}
At least one of secretion_rate or uptake_rate is required. An omitted rate
is preserved, as are the existing secretion target and net export rate. Repeat
the tool for every required pair or call it again later to revise one rate.
The result contains the interaction values actually stored for the pair, the
configuration revision and changed, which is false when the requested values
already matched.
Signals, behaviors, and Cell Rules
Use:
list_all_available_signals()for environment, contact, intracellular, and other signals available in the current configuration;list_all_available_behaviors()for configurable cell behaviors;get_available_cycle_models()for cell-cycle identifiers.
The signal and behavior discovery tools return descriptions and requirements as structured data. Use their exact names when adding a rule.
add_single_cell_rule() adds one Hill-function relationship:
{
"cell_type": "cancer_cell",
"signal": "oxygen",
"direction": "decreases",
"behavior": "apoptosis",
"saturation_value": 0,
"half_max": 5,
"hill_power": 4,
"session_id": "SESSION_ID"
}
direction is increases or decreases. half_max and hill_power must be
positive. Call the tool repeatedly for every signal-behavior relationship.
Modify an existing XML configuration
Use this workflow:
- Call
validate_xml_file(filepath). - If the structured result reports
valid=true, callload_xml_configuration(filepath). - Inspect it with
analyze_loaded_configuration(). - Use
list_loaded_components()for substrate, cell-type, or PhysiBoSS details. - Apply targeted patches and additions.
- Inspect
get_simulation_summary(). - Export to a session-scoped filename.
validate_xml_file() is read-only. A well-formed validation request for an
invalid XML file returns a successful tool result with valid=false and an
error description. The validation operation succeeded; the file did not pass
validation.
load_xml_configuration() validates and parses a candidate configuration
before replacing the session state. A missing, invalid, or unloadable file
does not replace the current configuration.
analyze_loaded_configuration() returns source provenance, domain information,
component names, existing rules, PhysiBoSS models, and modification guidance.
list_loaded_components(component_type=...) accepts substrates,
cell_types, physiboss, or all.
PhysiBoSS integration
PhysiBoSS support must be available in the installed physicell-settings
package. A target PhysiCell cell type must exist before an intracellular MaBoSS
model can be attached.
Preferred verified handoff
Export a maboss-to-physicell handoff from the MaBoSS MCP server, then call:
{
"manifest_path": "/path/to/maboss_to_physicell.handoff.json",
"artifact_prefix": "cancer_cell_maboss_v1",
"replace_existing": false,
"session_id": "SESSION_ID"
}
on import_maboss_handoff.
If this server cannot read MaBoSS's files (a host that sandboxes each server),
replace manifest_path with handoff_bundle, the object returned by MaBoSS
export_handoff_bundle. See
Hosts that sandbox each server.
The tool:
- verifies the manifest, BND, CFG, optional result table, and artifact hashes;
- verifies the complete upstream NeKo lineage when present;
- checks the exact Boolean node and output-node contracts;
- checks that the declared target cell type exists;
- copies the verified artifacts into the PhysiCell session;
- attaches the candidate model only after the complete import succeeds; and
- stores a separate MaBoSS context for the target cell type.
Use a new artifact_prefix for every retained import. Existing import
artifacts are not overwritten.
Importing models for different target cell types preserves independent
contexts. If the target already has an intracellular model, import fails unless
replace_existing=true is supplied. Explicit replacement resets that target's
previous PhysiBoSS settings, input links, output links, and mutations.
Configure settings and biological mappings
After import, patch the target's timing and inheritance:
{
"cell_type": "cancer_cell",
"intracellular_dt": 6,
"time_stochasticity": 0,
"inheritance_global": true,
"session_id": "SESSION_ID"
}
configure_physiboss_settings() also supports scaling and start_time. At
least one value is required and every omitted setting is preserved. The tool
can be called repeatedly for the same target or separately for several target
cell types.
Then call repeatedly as needed:
add_physiboss_input_linkto map a PhysiCell signal to a Boolean node and return the stored input mapping;add_physiboss_output_linkto map a Boolean node to a PhysiCell behavior;apply_physiboss_mutationto fix a Boolean node to0or1.
Input and output link actions are activation or inhibition. Discover exact
PhysiCell signal and behavior names with the discovery tools, and use exact
Boolean node names from the MaBoSS context.
MaBoSS output nodes, parameters, and simulation summaries are preserved as context. They are not automatically translated into PhysiBoSS timing or signal/node/behavior mappings; those require explicit biological decisions.
Inspect all stored contexts with get_maboss_context(), or supply cell_type
to select one target.
Standalone BND and CFG fallback
When no typed handoff manifest exists:
- call
set_maboss_context()with the standalone file paths and known model metadata; - call
add_physiboss_model()for the intended cell type; - configure settings, links, and mutations as above.
This route does not verify a cross-server provenance chain or copy an
integrity-protected artifact set. Prefer import_maboss_handoff() whenever a
MaBoSS manifest is available.
Inspect with read-only resources
The server exposes one static manual and seven session resource templates:
| URI | Content |
|---|---|
docs://physicell/agent_manual |
Complete agent operations manual |
physicell://session/{session_id}/workflow |
Progress and recommended next actions |
physicell://session/{session_id}/domain |
Space, mesh, dimensionality, duration, and time steps |
physicell://session/{session_id}/substrates |
Substrate diffusion and initial-condition summary |
physicell://session/{session_id}/cell_types |
Principal phenotype values for each cell type |
physicell://session/{session_id}/cell_rules |
Signal-behavior rules and ruleset references |
physicell://session/{session_id}/physiboss |
Intracellular models, context, settings, links, and mutations |
physicell://session/{session_id}/files |
All generated session artifacts |
The workflow and files resources work for a valid session before a simulation domain exists. Domain, substrates, cell types, cell rules, and PhysiBoSS resources require a configuration. These resources are read-only and do not create missing sessions or modify workflow progress.
physicell_workflow_prompt and get_help() expose the same operating manual.
Export XML and Cell Rules
Export order when rules exist
When at least one Cell Rule exists:
- call
export_cell_rules_csv()first; - that tool writes the CSV and registers its enabled ruleset reference in the in-memory configuration;
- call
export_xml_configuration()afterward so the generated XML contains that ruleset reference.
{
"filename": "tumor_rules.csv",
"session_id": "SESSION_ID"
}
followed by:
{
"filename": "tumor_settings.xml",
"session_id": "SESSION_ID"
}
Without cell rules, only the XML export is required.
XML and CSV filenames must be plain basenames without directory components and
must use the matching .xml or .csv suffix. Outputs are confined to:
<configured-or-user-cache-root>/PhysiCell/{session_id}/
Reusing an export filename updates that session artifact. Choose distinct filenames when several configuration versions must be retained.
list_generated_files() reports XML and CSV artifacts for the active session;
pass session_id="all" to aggregate those file types across sessions.
list_artifact_sessions() and the files resource also expose other retained
handoff artifacts.
The XML can be supplied to the appropriate compiled PhysiCell project. The server cannot verify project-specific C++ extensions or execute the exported model.
Tool reference
| Category | Tools |
|---|---|
| Sessions and workflow | create_session, list_sessions, list_artifact_sessions, set_default_session, get_workflow_status, get_simulation_summary, delete_session |
| MaBoSS context and handoff | import_maboss_handoff, set_maboss_context, get_maboss_context |
| Existing XML | validate_xml_file, load_xml_configuration, analyze_loaded_configuration, list_loaded_components |
| Domain and scenario | analyze_biological_scenario, create_simulation_domain |
| Substrates and cells | add_single_substrate, add_single_cell_type, configure_cell_parameters, set_substrate_interaction, configure_simulation_inputs |
| Discovery and rules | get_available_cycle_models, list_all_available_signals, list_all_available_behaviors, add_single_cell_rule |
| PhysiBoSS | add_physiboss_model, configure_physiboss_settings, add_physiboss_input_link, add_physiboss_output_link, apply_physiboss_mutation |
| Export and artifacts | export_xml_configuration, export_cell_rules_csv, export_configuration_bundle, list_generated_files, clean_generated_files |
| Help | get_help |
Structured output and validation results
Session discovery, workflow status, XML validation and analysis, component inspection, signal/behavior discovery, context inspection, verified handoff import, exports, and artifact tools return JSON-native structured results in addition to concise model-readable text.
Invalid arguments, missing prerequisites, unsafe filenames, failed
configuration changes, and integrity failures are returned as MCP tool errors
with recovery guidance. A valid call to validate_xml_file() may instead
return valid=false, because file validity is the scientific result being
requested.
Cleanup
clean_generated_files(session_id=...) removes all artifacts for the selected
session while preserving its in-memory configuration. Retain any XML, CSV,
BND, CFG, result, or handoff files required for reproducibility before calling
it.
If both configuration state and artifacts should be discarded, clean the
generated files before calling delete_session().
Further reading
- physicell-settings on PyPI
- PhysiCell project
- PhysiCell Studio documentation
- PhysiBoSS
- MCP Python SDK v2 structured output
- MCP Python SDK v2 resources
The artifact tree above now lives at
$MCP_BIOMODELLING_ARTIFACT_ROOT/PhysiCell/<session_id> or the shared user-cache
default documented in the root README, rather than the installed package.
Legacy package-local artifacts remain discoverable with full paths and a
legacy marker. Existing PhysiBoSS handoff and approval requirements are unchanged.
PhysiCell Configuration Builder MCP questions
How do I add PhysiCell Configuration Builder MCP to Claude Code?
Run claude mcp add physicell -- uvx --from mcp-biomodelling-servers mcp-physicell-server in your terminal. Add --scope user to make it available in every project.
How do I add PhysiCell Configuration Builder MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does PhysiCell Configuration Builder MCP provide?
It exposes 36 tools, including export_configuration_bundle, configure_simulation_inputs, create_session, list_sessions, list_artifact_sessions.
Does this server run PhysiCell simulations?
No, this is a configuration builder and not a simulation runtime. It does not launch the executable or analyze simulation output.
How do I install the PhysiCell MCP server?
You can install it via pip using the command python -m pip install mcp-biomodelling-servers.
What happens if I call create_simulation_domain on an existing configuration?
Calling this tool will create a fresh configuration and replace the one currently stored in the session, discarding any previously added substrates, cell types, or rules.
Can I use this to modify existing XML files?
Yes, you can validate an XML file, load it into a session, inspect it, apply targeted patches, and then export it.