Overview

mcp_pykingenie exposes pykingenie surface-based binding kinetics workflows through the Model Context Protocol. This MCP server is only for surface-based binding data, such as Octet and Gator BLI experiments. It provides tools for importing experiments, aligning association and dissociation phases, subtracting reference sensors, preparing fitting datasets, running kinetic fits, plotting traces, and inspecting fitted parameters.

Basic Workflow

The typical workflow for surface-based binding kinetics analysis is:

  1. Import an Octet or Gator experiment.

  2. Align the association phase.

  3. Align the dissociation phase.

  4. Subtract a reference sensor.

  5. Inspect the sample information table.

  6. Select traces and generate fitting datasets.

  7. Run either a steady-state fitting model or a kinetic fitting model.

  8. Plot fitted curves and retrieve fitting results, when running kinetic fitting.

Importing Data

Data can be imported from absolute paths or from paths relative to the active MCP data directory. Use print_data_dir to see that directory. Relative-path imports are useful when you first place or copy input files into the server’s date-stamped data folder.

Supported import paths are:

  • load_octet_example loads the packaged Octet BLI example and is the quickest way to test the full workflow. Users can also download the same raw example data as octet_bli_example_data.zip.

  • import_octet_experiment imports an Octet folder containing .frd files and the sample plate metadata files produced by the Octet software.

  • import_gator_experiment imports a Gator folder or .zip archive. The folder/archive should contain the channel CSV files plus Setting.ini and ExperimentStep.ini. Zip archives are extracted into the active MCP data directory before loading.

  • import_kingenie_surface_csv imports a KinGenie surface-simulation CSV. The CSV should contain surface trace columns such as Time, Signal, Smax, and Analyte_concentration_micromolar_constant.

Each import tool stores the loaded experiment in the in-memory pykingenie.KineticsAnalyzer under the supplied experiment name. Use list_experiment_names after importing to confirm what is available for alignment, subtraction, plotting, and fitting.

MCP Tools

The server keeps a pykingenie.KineticsAnalyzer instance in memory for the current MCP session. Generated plots are written to the active data directory, which defaults to ~/user_data_mcp_pykingenie/<YYYY-MM-DD>/. Set RESULTS_DIR before starting the server to choose a different root folder. Use the print_data_dir tool to display the exact folder used by the running server.

Example Chat Flow

Once connected through your MCP client, ask your AI assistant to run a flow like:

1. load the Octet example experiment
2. align the association phase
3. align the dissociation phase
4. subtract the sensor H1
5. plot all the steps
6. show me the sample information
7. create a fitting dataset using sample wt - imd
8. run kinetic fitting with a one-to-one model
9. plot the fitted curves

Local Development

For local MCP clients that support the mcp.json convention, point the server command at the repository:

{
  "mcpServers": {
    "mcp_pykingenie": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/mcp_pykingenie", "mcp_pykingenie"]
    }
  }
}

Citation

If you use mcp_pykingenie, please cite it as:

Burastero, O. (2026). mcp_pykingenie (Version 1.0) [Computer software]. GitHub. https://github.com/osvalB/mcp_pykingenie

@software{burastero_2026_mcp_pykingenie,
  author = {Burastero, Osvaldo},
  title = {mcp_pykingenie},
  version = {1.0},
  year = {2026},
  url = {https://github.com/osvalB/mcp_pykingenie}
}