An MCP (Model Context Protocol) server for running Kappa simulations using the Kappybara package. This allows LLMs to run rule-based simulations of molecular interaction systems directly.
Python packages used:
- Kappybara
- FastMCP -- deployed on https://kappybara.fastmcp.app/mcp
- Run Kappa Simulations: Execute Kappa models with customizable parameters using kappybara
- CSV Output: Get simulation results as CSV data for easy analysis
- Example Models: Built-in example models (reversible binding, linear polymerization)
- Pure Python: Uses the kappybara Python library for all simulations
- Clone or download this repository
- Install dependencies:
pip install -r requirements.txtfastmcp run main.pyfastmcp install claude-desktop main.py
Run a Kappa simulation and return results with stdout, stderr, and CSV output.
Parameters:
kappa_code(string, required): The Kappa model code to simulatetime_limit(float, default: 100.0): Maximum simulation timepoints(int, default: 200): Number of data points to collectseed(int, optional): Random seed for reproducibility
Returns: JSON string with three fields:
stdout: Standard output from the simulationstderr: Standard error output (warnings, errors)output: CSV data with simulation results
Example:
kappa_code = """
%init: 100 A(x[.])
%init: 100 B(x[.])
%obs: 'AB' |A(x[1]), B(x[1])|
A(x[.]), B(x[.]) <-> A(x[1]), B(x[1]) @ 1, 1
"""
result = run_kappa_simulation(kappa_code, time_limit=50, points=100)
# Result is a JSON string like:
# {
# "stdout": "",
# "stderr": "",
# "output": "time,AB\n0.0,0\n0.01,1\n..."
# }A simple reversible binding model (kappybara syntax).
A linear polymerization model (kappybara syntax).
Kappybara uses a specific syntax for Kappa models. Here's a quick reference:
%init: 100 AgentName(site1[.], site2[state]) # Initialize agents
%obs: 'Observable' |pattern| # Define observable
pattern -> pattern @ rate # Define rule (irreversible)
pattern <-> pattern @ rate1, rate2 # Define rule (reversible)
[.]- unbound site[1],[2], etc. - bound sites (bond labels)[_]- wildcard for any binding state
%init: 100 A(x[.])
%init: 100 B(x[.])
%obs: 'A_free' |A(x[.])|
%obs: 'B_free' |B(x[.])|
%obs: 'AB_complex' |A(x[1]), B(x[1])|
// Reversible binding with forward rate 0.001 and reverse rate 0.1
A(x[.]), B(x[.]) <-> A(x[1]), B(x[1]) @ 0.001, 0.1
kappybara-mcp/
├── main.py # MCP server implementation
├── requirements.txt # Python dependencies
├── README.md # This file
└── test_example.py # Example test/demo script
Run the test example:
python test_example.py- The MCP server exposes Kappa simulation capabilities through the Model Context Protocol
- LLMs can call the
run_kappa_simulationtool with Kappa code (using kappybara syntax) and parameters - The server uses the Kappybara Python library to parse the model and run the simulation
- Results are returned as JSON with stdout, stderr, and CSV output that can be analyzed or visualized
MIT