Lets an AI client perform stochastic Boolean network simulations, attractor analysis, and biological model configuration.
Also known as marcorusc/mcp-biomodelling-servers, maboss, 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 MaBoSS MCP?
MaBoSS lets an AI client perform stochastic Boolean network simulations, attractor analysis, and biological model configuration. It exposes 36 tools, such as export_configuration_bundle, configure_simulation_inputs, create_session.
Summary generated from the project's README
About MaBoSS MCP server
Performing stochastic Boolean network simulations and biological model analysis is what researchers achieve using this server. It provides a specialized interface for constructing, configuring, and simulating Boolean models through the Model Context Protocol. The server uses pyMaBoSS as its simulation engine and runs the compiled cmaboss engine in child processes to ensure that long-running simulations do not block the main server connection.
Users interact with the server via stdio after installing the mcp-biomodelling-servers Python package. The system manages work through isolated in-memory sessions, allowing for multiple active models. Developers can manage these sessions using tools like create_session and list_sessions to keep different biological experiments separate. The server also supports a verified modeling pipeline, enabling data handoffs between NeKo and PhysiCell.
Beyond basic simulation, the server allows for deep model inspection and modification. You can adjust initial-state probabilities, update logical rules, or simulate specific mutations without altering the base model. Results are provided as structured JSON, Markdown tables, or visual PNG trajectory plots, with all generated files stored in session-specific artifact directories.
What you can do with it
- 1Simulate biological mutationsRun a specific mutant copy of a model to observe changes without altering the original session state.
- 2Integrate modeling pipelinesImport models directly from NeKo to maintain provenance and prepare data for PhysiCell.
Written from the project's README. Every use case is checked against a quote from it.
How to install MaBoSS MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall MaBoSS MCP in Claude Code
$ claude mcp add maboss -- uvx --from mcp-biomodelling-servers mcp-physicell-serverInstall MaBoSS MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"maboss": {
"command": "uvx",
"args": [
"--from",
"mcp-biomodelling-servers",
"mcp-physicell-server"
]
}
}
}Install MaBoSS MCP in VS Code
.vscode/mcp.json
{
"servers": {
"maboss": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"mcp-biomodelling-servers",
"mcp-physicell-server"
]
}
}
}Install MaBoSS MCP in VS Code CLI
$ code --add-mcp '{"name":"maboss","type":"stdio","command":"uvx","args":["--from","mcp-biomodelling-servers","mcp-physicell-server"]}'Install MaBoSS MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"maboss": {
"command": "uvx",
"args": [
"--from",
"mcp-biomodelling-servers",
"mcp-physicell-server"
]
}
}
}Install MaBoSS MCP in Codex
$ codex mcp add maboss -- uvx --from mcp-biomodelling-servers mcp-physicell-serverInstall MaBoSS MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.maboss] command = "uvx" args = ["--from", "mcp-biomodelling-servers", "mcp-physicell-server"]
Install MaBoSS MCP in Gemini CLI
$ gemini mcp add -s user maboss uvx -- --from mcp-biomodelling-servers mcp-physicell-serverInstall MaBoSS MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"maboss": {
"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.
MaBoSS 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 GitHubMaBoSS MCP Server
The Wave 2 integration guide covers summary readouts, named rate editing, persistent run IDs, bounded results and handoff 2.1.
The MaBoSS server exposes stochastic Boolean-model construction, configuration, simulation, analysis, and export through the Model Context Protocol (MCP). It uses pyMaBoSS as its simulation engine and can participate in a verified modelling pipeline from NeKo to MaBoSS to PhysiCell.
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 MaBoSS server:
mcp-maboss-server
Alternatively, run it in an isolated environment:
uvx --from mcp-biomodelling-servers mcp-maboss-server
The server does not need the separate MaBoSS executable. It validates and
simulates models with cmaboss, the compiled engine installed with pyMaBoSS,
in a child Python process so a long simulation never blocks the server. Loading
a model that the engine rejects fails with the engine's message.
See the repository README for the supported Python versions, complete MCP client configuration, source-checkout instructions, and shared runtime behavior.
Sessions and model state
Every model belongs to a MaBoSS session. Start by calling
create_session(), retain the returned session_id, and pass it explicitly
when more than one model is active. When session_id is omitted, tools use the
active default session.
create_sessioncreates an isolated in-memory session and may attach a human-readable label.list_sessionsreports active sessions and whether each has a model or simulation result.list_artifact_sessionsdiscovers session artifacts left by earlier server processes.set_default_sessionselects the session used by calls that omitsession_id.delete_sessionremoves in-memory state and, by default, its artifact files.
Generated BND, CFG, CSV, PNG, and handoff files are stored under the server's
session-scoped artifacts/<session_id>/ directory. Use
list_generated_files() to obtain their resolved paths instead of guessing
them.
Recommended standalone workflow
For a standalone BNET model, use the following order:
- Call
create_session(). - Convert the BNET with
bnet_to_bnd_and_cfg(bnet_path). - Load the generated files with
build_simulation(). - Call
get_maboss_nodes()and use only the returned node names. - Inspect the current configuration with
update_maboss_parameters(),get_maboss_initial_state(), andget_maboss_logical_rules(). - Select a small, biologically meaningful set of outputs with
set_maboss_output_nodes(...). - Optionally update parameters, initial-state probabilities, or logical rules.
- Call
run_simulation(). - Read numerical results with
get_simulation_result(). - Render the trajectory with
visualize_network_trajectories(). - Export updated BND/CFG files or a typed PhysiCell handoff when needed.
bnet_to_bnd_and_cfg() writes output.bnd and output.cfg into the session
artifact directory. With no paths supplied, build_simulation() automatically
loads those files. If the server cannot read your BNET file (a host that
sandboxes each server), pass its complete content as bnet_text instead of
bnet_path; it is stored verbatim in the session artifact directory.
A Boolean network with N visible outputs can produce up to 2^N states. Always call
set_maboss_output_nodes()beforerun_simulation(). Selecting only the outputs needed for the scientific question reduces both runtime and result size.
Inspecting and configuring a model
Simulation parameters
Call update_maboss_parameters() without a parameters value to inspect all
parameters supported by the loaded model. Supply only the values that should
change:
{
"parameters": {
"sample_count": 10000,
"max_time": 100,
"time_tick": 0.5,
"thread_count": 4
},
"session_id": "SESSION_ID"
}
Common parameters include:
| Parameter | Meaning |
|---|---|
sample_count |
Number of stochastic trajectories |
max_time |
Simulation time horizon |
time_tick |
Interval between reported time points |
discrete_time |
Discrete-time toggle, 0 or 1 |
thread_count |
Number of simulation threads |
The server also accepts backend parameters exposed by the loaded MaBoSS version. Unknown parameter names produce a recoverable tool error.
Output nodes
First call get_maboss_nodes(), then provide a non-empty subset:
{
"output_nodes": ["Apoptosis", "Proliferation"],
"session_id": "SESSION_ID"
}
Initial-state probabilities
Inspect the existing distribution with get_maboss_initial_state() before
changing it.
For one node, provide [P(OFF), P(ON)]:
{
"nodes": "DNA_damage",
"probDict": [0.2, 0.8],
"session_id": "SESSION_ID"
}
For multiple nodes, use JSON-native state/probability records. State-vector
order must match the order in nodes, each state must contain only 0 or 1,
and the probabilities must sum to 1:
{
"nodes": ["DNA_damage", "Growth_signal"],
"probDict": [
{"state": [0, 0], "probability": 0.4},
{"state": [1, 0], "probability": 0.6}
],
"session_id": "SESSION_ID"
}
The listed states do not have to cover every possible combination, but states
must be unique and each vector must have the same length as nodes.
Logical rules and mutations
get_maboss_logical_rulesreturns the current Boolean rules, up to 100 nodes unlessselected_nodesis given (truncatedreports when more exist). Arule_limitationmarks nodes whose custom rate expressions mean the rule alone does not describe their switching; inspect those withget_maboss_nodes.change_maboss_rulereplaces one node's rule and restores the previous rule if model validation rejects the change.get_maboss_mutationsreports mutations currently stored in the model.simulate_mutationruns a mutant copy without changing the session's base simulation.
For example:
{
"nodes": ["TP53", "AKT"],
"state": ["ON", "OFF"],
"session_id": "SESSION_ID"
}
Mutation states are ON, OFF, or WT. A single state may be applied to all
requested nodes, or a state list may be supplied in node order.
Running and reading a simulation
run_simulation() executes the loaded model in a worker thread, stores the
pyMaBoSS result in the session, reports MCP progress, and writes a non-empty
state-probability table to result.csv.
get_simulation_result() returns both:
- a Markdown state-probability table for the model to read; and
- JSON-native structured content containing the numerical trajectory table.
The same Markdown result is available through
maboss://session/{session_id}/result.
Native trajectory images
After run_simulation(), call:
{
"session_id": "SESSION_ID",
"until": 50
}
on visualize_network_trajectories.
The optional until parameter is the maximum simulation time displayed. It
must be a finite number greater than zero. Omit it to plot the full available
trajectory.
The tool:
- delegates trajectory drawing to pyMaBoSS
plot_trajectory(until=...); - uses a tight bounding box and padding so legends outside the axes are not cropped;
- returns the PNG as an MCP
ImageContentblock with MIME typeimage/png; - returns text plus structured metadata for the session, time window, and artifact; and
- saves the exact same PNG bytes as
network_trajectory.pngin the session artifact directory.
An MCP client must support rendering image content blocks to display the plot inline. The saved artifact remains available when a client presents only the textual or structured part of the result.
Cross-server handoffs
NeKo to MaBoSS
Prefer import_neko_handoff(manifest_path) when the Boolean model comes from
the NeKo MCP server. The tool:
- validates the
neko-to-mabossmanifest and artifact hashes; - converts the referenced BNET into MaBoSS BND and CFG files;
- verifies the converted node set;
- applies output nodes declared by NeKo when present;
- loads the model only after the complete import succeeds; and
- retains the NeKo provenance for a later PhysiCell handoff.
If the manifest declares no output nodes, call set_maboss_output_nodes()
before running or exporting the model.
If this server cannot read NeKo's files (a host that sandboxes each server),
pass handoff_bundle, the object returned by NeKo export_handoff_bundle,
instead of manifest_path. See
Hosts that sandbox each server.
MaBoSS to PhysiCell
Call export_maboss_handoff(target_cell_type=...) to produce an
integrity-protected maboss-to-physicell handoff. It snapshots:
- the current BND and CFG model;
- MaBoSS parameters and selected output nodes;
- an optional non-empty simulation-result CSV;
- the intended PhysiCell cell type and biological context; and
- the complete upstream NeKo lineage, when one was imported.
A standalone MaBoSS model must provide biological_context. A model imported
from NeKo may inherit that context. The export refuses to overwrite existing
handoff artifacts, so choose a new artifact_prefix for every retained
handoff.
For a PhysiCell server that cannot read MaBoSS's files, call
export_handoff_bundle(manifest_path=...) here and pass the result to
import_maboss_handoff(handoff_bundle=...). The bundle also carries the NeKo
parent manifest and its files.
Use export_maboss_bnd_cfg() when only standalone MaBoSS files are needed.
Use export_maboss_handoff() when PhysiCell needs typed scientific context,
integrity metadata, and provenance.
Tool reference
| Category | Tools |
|---|---|
| Sessions | create_session, list_sessions, list_artifact_sessions, set_default_session, delete_session |
| Import and loading | import_neko_handoff, bnet_to_bnd_and_cfg, build_simulation |
| Inspection | get_maboss_nodes, get_maboss_initial_state, get_maboss_logical_rules, get_maboss_mutations |
| Configuration | change_maboss_rule, edit_maboss_readouts, update_maboss_parameters, set_maboss_output_nodes, set_maboss_initial_state |
| Simulation and analysis | run_simulation, simulate_mutation, get_simulation_result, visualize_network_trajectories |
| Export | export_maboss_bnd_cfg, export_maboss_handoff, export_handoff_bundle |
| Artifacts | list_generated_files, clean_generated_files |
Resources and prompt
The server exposes read-only resources for clients that support MCP resource templates:
| URI | Content |
|---|---|
docs://maboss/agent_manual |
Complete agent operating manual |
maboss://session/{session_id}/nodes |
Network node names |
maboss://session/{session_id}/parameters |
Current parameters |
maboss://session/{session_id}/initial_state |
Initial-state distribution |
maboss://session/{session_id}/logical_rules |
Boolean rules |
maboss://session/{session_id}/mutations |
Current mutations |
maboss://session/{session_id}/result |
Latest in-memory state-probability result (use get_simulation_result(run_id=...) for saved runs) |
maboss://session/{session_id}/files |
Generated artifact files |
maboss_workflow_prompt exposes the same recommended operating rules as an
MCP prompt.
Preserved simulation runs
Each successful file-backed run_simulation and simulate_mutation call
preserves a unique run_<uuid> artifact set before pyMaBoSS releases its
temporary directory:
- Exact BND/CFG inputs sent to the engine (for mutant runs, the mutated copy) and the engine's actual output files.
- Full state-probability and node-marginal CSV tables, including their original
time index labelled
Time. - A JSON inventory with session/run identity, run kind, source model revision, requested mutations, effective configuration (parameters, rates, initial state, outputs, readouts), reported timepoints, file sizes and SHA-256 hashes. The inventory is published after its files.
Both tools return the run ID. get_simulation_result(run_id=...) and
visualize_network_trajectories(run_id=...) read a saved run from disk after
verifying its integrity, including after a server restart, without rerunning the
engine. Omitting run_id selects the latest ordinary run of the session and
reports the resolved ID; mutant runs never replace that selection, and the base
model is not modified. An unknown run ID, or one from another session, is an
error rather than a fallback. Each plot is saved under a new
<run_id>.plot_<uuid>.png name, so earlier plots are never overwritten.
The legacy result.csv and result resource keep their latest final-snapshot
behavior and are not the historical record. Saving results does not fill missing
timepoints or validate numerical/biological behavior.
An engine failure or a copy, parsing or publication error fails the operation
without rerunning the engine and is recorded as a separate failed_<uuid>.json
incomplete record with any available diagnostic files. Partial publication rolls
back only that attempt's new links. Previously saved runs remain intact.
Errors and artifact cleanup
Invalid parameters, unknown nodes, missing model state, missing simulation results, and failed scientific operations are returned as MCP tool errors with actionable messages. A caller can correct the arguments or perform the named prerequisite and retry without restarting the server.
clean_generated_files(session_id=...) removes artifacts for one session but
keeps its in-memory model. delete_session(clean_files=true) removes both.
These operations are destructive; retain any BND, CFG, CSV, PNG, or handoff
files needed for reproducibility before calling them.
Further reading
- MaBoSS website and documentation
- pyMaBoSS source
- MCP Python SDK v2 media results
- MCP Python SDK v2 structured output
Artifact storage uses the shared cache root or MCP_BIOMODELLING_ARTIFACT_ROOT,
with the MaBoSS/<session_id> namespace. Legacy artifacts remain discoverable.
bnet_to_bnd_and_cfg accepts optional parent_manifest (a verified BNET source
sidecar or NeKo handoff) and derived_from (the intact parent artifact path for
edited copies). Conversion and model exports retain hashes in .lineage.json
sidecars. Ordinary provenance does not replace import_neko_handoff or confer
approval. See the root README for exact path and provenance semantics.
MaBoSS MCP questions
How do I add MaBoSS MCP to Claude Code?
Run claude mcp add maboss -- 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 MaBoSS 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 MaBoSS MCP provide?
It exposes 36 tools, including export_configuration_bundle, configure_simulation_inputs, create_session, list_sessions, list_artifact_sessions.
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.