mcp_pykingenie

This repository contains a local MCP server for the analysis of surface-based binding kinetics data from Octet and Gator experiments. It is based on the Python package pykingenie.

Demo videos

• Example with Visual Studio Code
• Example with Claude

Installation

We recommend running mcp_pykingenie with uv.

Run from the command line

uvx mcp_pykingenie

By default, generated plots and relative-path input data are stored in ~/user_data_mcp_pykingenie/<YYYY-MM-DD>/. To choose a different results folder, set RESULTS_DIR before starting the server. Use the print_data_dir MCP tool to inspect the active output folder for a running server.

RESULTS_DIR=~/Documents/user_data_mcp_pykingenie uvx mcp_pykingenie

Configure an MCP client

Add the server to any MCP-compatible client that supports the mcpServers configuration format:

{
  "mcpServers": {
    "mcp_pykingenie": {
      "command": "uvx",
      "args": ["mcp_pykingenie"],
      "env": {
        "RESULTS_DIR": "/absolute/path/to/results-folder"
      }
    }
  }
}

After updating the configuration, restart the MCP client so it can launch the server.

If you want to run directly from the Git repository:

{
  "mcpServers": {
    "mcp_pykingenie": {
      "command": "uvx",
      "args": ["git+https://github.com/osvalB/mcp_pykingenie.git@main"]
    }
  }
}

Claude Desktop

In Claude Desktop, open Settings, go to Developer, and click Edit Config. Add mcp_pykingenie to claude_desktop_config.json:

{
  "mcpServers": {
    "mcp_pykingenie": {
      "command": "uvx",
      "args": ["mcp_pykingenie"],
      "env": {
        "RESULTS_DIR": "/Users/your-name/Documents/user_data_mcp_pykingenie"
      }
    }
  }
}

Claude Desktop stores this file at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Save the file, then fully quit and reopen Claude Desktop.

Local development

To run the server from a local checkout, use an absolute path to the repository:

{
  "mcpServers": {
    "mcp_pykingenie": {
      "command": "uvx",
      "args": [
        "--refresh",
        "--from",
        "/absolute/path/to/mcp_pykingenie",
        "mcp_pykingenie"
      ]
    }
  }
}

If you want to reuse the checkout's existing environment, run it through uv:

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

For HTTP transport during development:

uv run mcp_pykingenie -t http -p 8000

Install with pip

pip install --user mcp_pykingenie

Then run the server with:

mcp_pykingenie

If your shell cannot find the command, make sure your user-level Python scripts directory is on PATH.

Install from source

git clone https://github.com/osvalB/mcp_pykingenie.git
cd mcp_pykingenie
uv sync --extra dev --extra doc --extra test

Run tests with:

uv run pytest

Build the documentation with:

uv run --extra doc make -C docs html

Example workflow

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

Importing data

Use print_data_dir to see the active MCP data directory. Import tools accept absolute paths, or paths relative to that directory.

• Download the bundled Octet BLI example data: octet_bli_example_data.zip.
• import_octet_experiment: pass a folder containing Octet .frd files and sample plate metadata.
• import_gator_experiment: pass a Gator folder or .zip archive containing channel CSV files plus Setting.ini and ExperimentStep.ini.
• import_kingenie_surface_csv: pass a surface-simulation CSV with trace columns such as Time, Signal, Smax, and Analyte_concentration_micromolar_constant.
• load_octet_example: load the packaged example to test the workflow.

Contact

If you found a bug, please use the issue tracker.

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}
}