Builds, curates, and analyzes biological signaling networks using curated interaction databases and SIF files.
Also known as marcorusc/mcp-biomodelling-servers, neko, 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 NeKo Biological Network Builder MCP?
NeKo Biological Network Builder is an MCP server. Builds, curates, and analyzes biological signaling networks using curated interaction databases and SIF files. It exposes 36 tools, such as export_configuration_bundle, configure_simulation_inputs, create_session.
Summary generated from the project's README
About NeKo Biological Network Builder MCP server
Researchers and computational biologists can build, curate, and analyze biological signaling networks directly through an AI client. The server uses the NeKo engine to construct networks from curated databases like omnipath or signor, or by importing existing SIF files. It operates over stdio and is distributed via the mcp-biomodelling-servers Python package.
Users manage their work through distinct sessions, allowing for multiple modeling hypotheses to exist simultaneously. The server provides specialized tools for editing topology, such as adding nodes, removing interactions, and resolving bimodal edges to ensure scientific accuracy. It also includes advanced connectivity auditing to identify isolated nodes and simulate repair strategies like relaxing path lengths or targeting high-degree hubs.
A standout feature is the native branching history, which automatically records snapshots of every topology change. This allows developers to navigate between states using undo, redo, or checkout actions, and compare different network versions without losing work. Once a network is finalized, it can be exported via an integrity-protected handoff to the MaBoSS MCP server.
What you can do with it
- 1Audit and repair network connectivityIdentify isolated nodes in a network and simulate how different connection strategies might fix them.
- 2Compare different topological versionsAnalyze the differences in nodes and interactions between two specific historical states of a network.
Written from the project's README. Every use case is checked against a quote from it.
How to install NeKo Biological Network Builder MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall NeKo Biological Network Builder MCP in Claude Code
$ claude mcp add neko -- uvx --from mcp-biomodelling-servers mcp-physicell-serverInstall NeKo Biological Network Builder MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"neko": {
"command": "uvx",
"args": [
"--from",
"mcp-biomodelling-servers",
"mcp-physicell-server"
]
}
}
}Install NeKo Biological Network Builder MCP in VS Code
.vscode/mcp.json
{
"servers": {
"neko": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"mcp-biomodelling-servers",
"mcp-physicell-server"
]
}
}
}Install NeKo Biological Network Builder MCP in VS Code CLI
$ code --add-mcp '{"name":"neko","type":"stdio","command":"uvx","args":["--from","mcp-biomodelling-servers","mcp-physicell-server"]}'Install NeKo Biological Network Builder MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"neko": {
"command": "uvx",
"args": [
"--from",
"mcp-biomodelling-servers",
"mcp-physicell-server"
]
}
}
}Install NeKo Biological Network Builder MCP in Codex
$ codex mcp add neko -- uvx --from mcp-biomodelling-servers mcp-physicell-serverInstall NeKo Biological Network Builder MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.neko] command = "uvx" args = ["--from", "mcp-biomodelling-servers", "mcp-physicell-server"]
Install NeKo Biological Network Builder MCP in Gemini CLI
$ gemini mcp add -s user neko uvx -- --from mcp-biomodelling-servers mcp-physicell-serverInstall NeKo Biological Network Builder MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"neko": {
"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.
NeKo Biological Network 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 GitHubNeKo MCP Server
The Wave 2 integration guide covers bounded diagnostics and the coordinated lightweight-history API.
The NeKo server builds, curates, analyzes, and exports signalling networks through the Model Context Protocol (MCP). It uses NeKo to construct networks from curated interaction databases or existing SIF files, and it preserves topology changes in NeKo's native branching history.
The server is distributed in the
mcp-biomodelling-servers
Python package and communicates over stdio. A typed, integrity-protected
handoff connects a finished NeKo network to the MaBoSS MCP server.
Installation and startup
Install all three bio-modelling servers:
python -m pip install mcp-biomodelling-servers
Start the installed NeKo server:
mcp-neko-server
Alternatively, run it in an isolated environment:
uvx --from mcp-biomodelling-servers mcp-neko-server
The branching history resource renders with the bundled PyGraphviz; no system Graphviz is needed. See the repository README for supported Python versions, complete MCP client configuration, and source-checkout instructions.
Sessions and network state
Every modelling hypothesis should have its own NeKo session. Begin with
create_session(), retain the returned session_id, and pass it explicitly to
subsequent calls. A newly created session is not automatically selected as the
default; call set_default_session() if later calls should be allowed to omit
the ID.
{
"label": "TP53-MYC resistance network"
}
list_sessionsreports active in-memory sessions, network dimensions, the current default, and history-retention settings.list_artifact_sessionsdiscovers exported files from current or previous server processes.statusreturns the node and interaction counts for one session.reset_networkdiscards the current network while keeping the session and its settings.delete_sessionpermanently removes the in-memory session.
set_default_params() stores completion defaults per session. Previews and
global completion reuse all defaults; add_nodes(autoconnect=true) reuses the
sign and consensus filters.
Recommended workflow
Use this order for a database-backed network:
- Call
create_session()and retain its ID. - Optionally configure reusable connection settings with
set_default_params(). - Build the network with
create_network(...). - Resolve bimodal edges, which BNET export requires:
edit_interactions(operation='set_effect') with evidence where the sign matters, orremove_bimodal_interactions()to delete all remaining ones (this can disconnect the network). When appropriate, also callremove_undefined_interactions(). - Check connectivity with
analyze_connectivity()(isolated nodes and the full component partition). - If repair is needed, call
preview_connection_impact()before selecting a mutating connection strategy. - Inspect the resulting topology and evidence.
- Use the history tools to compare the new state with earlier alternatives.
- Export an integrity-protected MaBoSS handoff with
export_neko_handoff(...).
During iterative construction, prefer verbosity="summary". Use preview or
full only when the actual nodes, interactions, paths, or evidence are needed.
Building a network
create_network() supports two curated database backends:
omnipath, the default;signor.
Create a network from seed genes:
{
"list_of_initial_genes": ["EGFR", "KRAS", "TP53", "AKT1"],
"database": "omnipath",
"max_len": 2,
"path_policy": "one_shortest",
"reuse_policy": "discovered_paths",
"only_signed": true,
"consensus": true,
"session_id": "SESSION_ID",
"verbosity": "summary"
}
The construction parameters are:
| Parameter | Contract |
|---|---|
max_len |
Maximum path length, from 1 to 4 |
path_policy |
one_shortest, all_shortest, or all_bounded |
reuse_policy |
none, discovered_paths, or induced_subgraph |
only_signed |
Keep only signed interactions when true |
consensus |
Use the resource's own consensus sign flags when true; this does not universally imply multiple databases or higher confidence |
verbosity |
summary, preview, or full |
Construction may query an external biological database and can take several minutes. The tool reports MCP progress while database resources and the network are being prepared.
An existing SIF can be used instead:
{
"list_of_initial_genes": [],
"sif_file": "/absolute/path/input.sif",
"database": "omnipath",
"session_id": "SESSION_ID",
"verbosity": "summary"
}
If the server cannot read your file (a host that sandboxes each server), pass
the file's complete content as sif_text instead of sif_file. NeKo stores it
verbatim in the session artifact directory and records it as the import source.
Additional seed genes may be supplied together with sif_file. A call that
cannot complete successfully does not replace a valid network already stored
in the session.
Editing and curating the topology
Add or remove nodes and interactions
add_nodesadds one or more genes in a single call and, by default, autoconnects each new gene to any direct neighbour already in the network (cheap; does not search multi-step paths). Setautoconnect=falseto skip.remove_generemoves a node and all incident edges.remove_interactionremoves only the requested directed edge.
Inspect the current network before destructive edits:
{
"session_id": "SESSION_ID",
"verbosity": "preview",
"max_rows": 50
}
on list_genes_and_interactions.
Gene symbols should match the identifiers returned by the inspection tools.
remove_interaction(node_A, node_B) removes node_A → node_B; it does not
remove the reverse edge.
Curate interaction signs
remove_bimodal_interactionsremoves edges reported as both activating and inhibiting, with their references, and can disconnect the network. Preferedit_interactionswith evidence when an edge's sign matters.remove_undefined_interactionsremoves edges whose effect cannot be mapped to a Boolean activation or inhibition.
These operations simplify later BNET export but change the scientific topology. Inspect the affected network and its history after applying them.
Inspecting topology and evidence
The server offers both concise text and JSON-native structured results:
list_genes_and_interactionsreturns node and directed-interaction records.filter_interactionsfilters by effect, source, or target without modifying the network.find_pathsreports directed paths between two genes up to a bounded length.get_referencesreturns literature evidence for interactions involving one or two genes.statusreports the current dimensions.
For example, inspect inhibitory edges targeting apoptosis:
{
"effect": ["inhibition"],
"target": "Apoptosis",
"session_id": "SESSION_ID",
"verbosity": "preview",
"format": "markdown",
"max_rows": 50
}
filter_interactions(format="json") changes the model-readable text format;
the tool's structured result remains available independently.
Auditing and repairing connectivity
analyze_connectivity() reports isolated nodes—nodes with no incident
edges—together with the complete connected-component partition of the
network. Use it before a BNET or handoff export.
Scout candidate changes
preview_connection_impact() evaluates possible repair directions without
changing the active network:
| Method | Result |
|---|---|
hubs |
Ranks high-degree genes that may help orient a repair |
relax_max_len |
Simulates increasing the stored maximum path length |
unsigned |
Simulates allowing unsigned interactions |
Example:
{
"method": "relax_max_len",
"session_id": "SESSION_ID",
"verbosity": "preview",
"format": "markdown"
}
The simulation methods operate on a copy. Their predicted changes are not committed to the session.
Apply a selected strategy
See NeKo's concise connection-strategy guide to choose the topology and path/reuse policies that match the research question.
bridge_components() connects two explicit groups:
{
"comp_a": ["EGFR", "KRAS"],
"comp_b": ["TP53", "BAX"],
"max_len": 2,
"mode": "OUT",
"only_signed": true,
"consensus": true,
"session_id": "SESSION_ID"
}
comp_a/comp_b must be Gene Symbols (e.g. from a component's nodes list
in analyze_connectivity()'s output), never the numeric component_id that
analyze_connectivity() reports for each component - that ID is a report
label, not a valid gene name.
mode is OUT, IN, or ALL.
connect_targeted_nodes() supports:
connect_to_upstream_nodes;connect_subgroup.
apply_global_connection() supports:
complete_connection, with explicitpath_policyandreuse_policy;connect_network_radially, withdirection="OUT"or"IN";connect_as_atopo, withstrategy_mode="radial"or"complete"and an optionaloutputslist of gene symbols to anchor the topology. This strategy loops until the network is connected to every declared output, so its cost is open-ended on large networks.
The database-backed connection tools can be expensive — complete_connection
is O(N^2) over every node pair, and connect_as_atopo cost is open-ended.
Reinspect components and compare history states after every selected
strategy.
Branching network history
NeKo automatically records snapshots for its supported topology-changing operations. The MCP server exposes that native history directly, so undo, redo, checkout, and comparison preserve the exact NeKo network states.
List states
list_network_history() returns:
- the exact current state ID;
- retained state IDs;
- parent and child relationships;
- node and edge counts for every state;
- the configured retention limit.
State IDs are identifiers, not list positions. Always obtain them from
list_network_history() before navigation or comparison.
Navigate
Use the single navigate_network_history() tool:
{
"action": "checkout",
"state_id": 3,
"session_id": "SESSION_ID"
}
The supported actions are:
| Action | state_id behavior |
|---|---|
undo |
Moves to the parent; state_id must be omitted |
redo |
Moves to a child; the ID may be omitted when there is one unambiguous child |
checkout |
Moves to the exact saved state; state_id is required |
Navigation does not delete other saved states. If an older state is checked out and then modified, NeKo retains the previous future and records the new topology on a separate branch.
Compare without navigating
compare_network_states(state_a, state_b) reports added and removed nodes and
interactions without changing the currently checked-out state:
{
"state_a": 2,
"state_b": 5,
"session_id": "SESSION_ID"
}
Configure retention
set_network_history_limit(max_states) sets the per-session policy:
nullkeeps an unbounded history;- an integer must be at least 2;
- a policy set before construction applies when a network is created;
- lowering the limit may immediately and irreversibly prune older snapshots.
Call list_network_history() before reducing the limit.
Render the history
Read:
neko://session/{session_id}/history
to obtain read-only HTML containing NeKo's inline SVG history diagram. This
resource does not change the checked-out state. The server renders NeKo's
history digraph with the bundled PyGraphviz rather than an external dot
executable; a rendering failure is returned as a resource error.
Export and the MaBoSS handoff
Standalone exports
export_network(format="sif") writes a standalone tab-separated interaction
network. export_network(format="bnet") writes a Boolean model for MaBoSS.
BNET export requires one connected network. It sanitizes names that are invalid
in Boolean rules and reports renamed nodes and duplicate rules removed after
identifier normalization. Use list_bnet_files() to inspect BNET artifacts in
the session.
Verified NeKo-to-MaBoSS transfer
Prefer export_neko_handoff() when the next step is simulation in the MaBoSS
MCP server:
{
"biological_context": "EGFR-driven survival and apoptosis decision",
"output_nodes": ["Apoptosis", "Proliferation"],
"artifact_prefix": "egfr_decision_v1",
"session_id": "SESSION_ID"
}
The handoff:
- requires a connected network and non-empty
biological_context; - writes a sanitized BNET and versioned JSON manifest;
- records exact Boolean nodes, declared outputs, node renames, removed duplicates, package versions, session provenance, and the current NeKo history state;
- protects both files with artifact integrity metadata;
- translates requested original NeKo output names to their exact sanitized BNET names; and
- refuses to overwrite an existing artifact pair.
Choose a new artifact_prefix for every retained handoff. output_nodes may
be omitted, but MaBoSS must then select a small output set before running a
simulation.
Pass the returned manifest path to MaBoSS import_neko_handoff(). A standalone
BNET path can instead be passed to MaBoSS bnet_to_bnd_and_cfg(), but that
route does not preserve the typed scientific context and provenance manifest.
If MaBoSS cannot read NeKo's files (a host that sandboxes each server), call
export_handoff_bundle(manifest_path=...) and pass the returned object to
import_neko_handoff(handoff_bundle=...) instead. See
Hosts that sandbox each server.
Tool reference
| Category | Tools |
|---|---|
| Sessions | create_session, list_sessions, list_artifact_sessions, set_default_session, status, reset_network, delete_session |
| Construction and editing | create_network, set_default_params, add_nodes, remove_gene, remove_interaction |
| Curation | edit_interactions, remove_bimodal_interactions, remove_undefined_interactions |
| Inspection and evidence | list_genes_and_interactions, filter_interactions, find_paths, get_references, analyze_connectivity, analyze_gene_set |
| Connection strategies | preview_connection_impact, bridge_components, connect_targeted_nodes, apply_global_connection |
| Branching history | list_network_history, navigate_network_history, compare_network_states, set_network_history_limit |
| Export and artifacts | export_network, export_neko_handoff, export_biomass_handoff, export_handoff_bundle, list_bnet_files, clean_generated_files |
Resources and prompt
| Name or URI | Content |
|---|---|
docs://neko/agent_manual |
Recommended agent workflow and operating rules |
neko://session/{session_id}/history |
Branching history as inline SVG HTML |
neko_workflow_prompt |
The operating manual as an MCP prompt |
Structured output and errors
Inspection, session, history, export, and handoff tools return structured JSON-native results in addition to concise model-readable text. This allows an MCP host to consume exact nodes, interactions, state IDs, dimensions, paths, provenance, and artifact metadata without parsing Markdown.
Invalid identifiers, missing prerequisites, unsupported strategies, failed database operations, disconnected exports, and other modelling failures are returned as MCP tool errors with recovery guidance. Correct the arguments or perform the named prerequisite and retry in the same session.
Artifact cleanup
clean_generated_files(session_id=...) deletes exported artifacts for the
selected session without resetting its in-memory network. It is destructive.
Retain any SIF, BNET, or handoff files needed for reproducibility before
calling it.
If both network state and artifacts should be discarded, clean the generated
files before calling delete_session().
Further reading
- NeKo documentation
- Exploring Network History in NeKo
- NeKo source
- MCP Python SDK v2 structured output
- MCP Python SDK v2 resources
Export an ODE-construction handoff
export_biomass_handoff(biological_context, artifact_prefix="neko_to_biomass", session_id=...) writes a network JSON and integrity-protected
neko-to-biomass manifest. It preserves original node identifiers, stable edge
IDs, all references, and available mechanism/database/context columns. Duplicate
identical interactions merge their reference lists. Disconnected and unsigned
interactions remain available for evidence curation.
Import the manifest with BioMASS's import_neko_handoff. The calling agent then
reads literature and proposes reactions with evidence or explicit assumptions.
This export does not assign rate laws or kinetic parameters. The existing
export_neko_handoff continues to export Boolean models for MaBoSS.
Artifact storage uses the shared cache root or MCP_BIOMODELLING_ARTIFACT_ROOT,
with the NeKo/<session_id> namespace. Legacy package-local artifacts remain
listed with their location. See the root README's artifact storage section.
create_network accepts optional parent_manifest and derived_from for SIF
imports. A parent is a verified .lineage.json from a SIF export; an edited copy
requires derived_from to identify the intact parent SIF. SIF/BNET exports retain
source hashes in sibling .lineage.json files, independently of handoff approval.
Evidence-backed interaction editing (Wave 2)
With the updated NeKo curation API, edit_interactions accepts up to 20 explicit
add or set_effect operations between existing nodes. Each operation requires
an effect, rationale, and publication evidence. PMIDs are optional when another
citation is supplied; missing references are never invented. Obtain the exact
network/state IDs from status and pass them with the session ID. A stale request,
ambiguous endpoint or conflicting addition fails without partial batch mutation.
The capability does not grant scientific authorization.
Inspection preserves manual origin and separates original evidence from edit
justification. Existing history tools expose bounded summaries and exact-state
detail resources. Use export_network(format='history') to save retained branches,
snapshots and explanations, then Network.from_history(path) to restore them.
Database identity reports the name used for construction only.
SIF/BNET exports and handoffs include verified history/provenance companions. Keep the referenced files together and use the coordinated MCP package to read new manifests. See Wave 2 integration for the agreed API, compatibility table, source requirements and measured interface costs.
NeKo Biological Network Builder MCP questions
How do I add NeKo Biological Network Builder MCP to Claude Code?
Run claude mcp add neko -- 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 NeKo Biological Network 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 NeKo Biological Network Builder MCP provide?
It exposes 36 tools, including export_configuration_bundle, configure_simulation_inputs, create_session, list_sessions, list_artifact_sessions.
Does the server require a system installation of Graphviz?
No, the server uses a bundled PyGraphviz to render the branching history resource, so no system Graphviz is required.
How do I manage multiple modeling hypotheses?
Every modeling hypothesis should have its own NeKo session. You should begin with create_session() and retain the returned session_id to pass to subsequent calls.