plr-mcp

A Model Context Protocol server for PyLabRobot. It exposes a liquid handler, a plate reader, a thermocycler, and a heater-shaker as MCP tools, so any MCP client (Claude Desktop, Claude Code, or your own agent) can run lab-automation steps by calling tools instead of writing PyLabRobot code.

It ships in simulation mode by default. Every tool runs end to end against PyLabRobot's chatterbox backends with no instruments attached, so you can try the whole thing on a laptop. Point it at real hardware by setting one environment variable (see below).

Verified against PyLabRobot 0.2.1.

Why an MCP server (and not just tool-use)

Driving PyLabRobot from a Claude skill or direct tool-calls is tool-use inside one agent. An MCP server is a standalone process that speaks the Model Context Protocol over stdio, so any MCP client can discover and call these tools without knowing anything about PyLabRobot. This repo is the server.

Related MCP server: my-mcp-server

Install

git clone https://github.com/di-omics/plr-mcp.git
cd plr-mcp
pip install -e .

This pulls in mcp and pylabrobot.

Prove it works (no hardware)

python examples/smoke_test.py

It drives every tool through the chatterbox backends and prints ALL OK when the run succeeds.

Run the server

plr-mcp                          # stdio transport, chatterbox simulation
PLR_MCP_BACKEND=star plr-mcp     # target a real Hamilton STAR instead

Tools

Well ranges use PyLabRobot syntax: a single well A1, a column A1:H1, or a partial column A1:D1.

Connect a client

Claude Code

claude mcp add plr -- plr-mcp

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "plr": {
      "command": "plr-mcp"
    }
  }
}

If plr-mcp is not on the client's PATH, use the absolute path to the console script (which plr-mcp) or run it as python -m plr_mcp.server.

Backends

Pick the liquid-handling backend with PLR_MCP_BACKEND, or override it per session in a setup_deck call (backend="star", etc.).

Only chatterbox runs with no instrument. The other three construct the real PyLabRobot backend (correct API for 0.2.1) and attempt to connect; if no instrument is reachable, or a vendor extra such as pylabrobot[opentrons] is not installed, setup_deck reports that in notes instead of crashing. The Hamilton tip and plate auto-load only for chatterbox and star; ot2 and evo use vendor-specific labware, so load your own.

For ot2, pass the robot IP:

PLR_MCP_BACKEND=ot2 PLR_MCP_OT2_HOST=169.254.1.1 plr-mcp

The non-liquid-handling instruments (plate reader, thermocycler, heater-shaker) run on chatterbox simulation and expose real hardware backends as clearly marked extension points in plr_mcp/lab.py (the _ensure_* methods). Wire in your own (for example an Inheco ODTC thermocycler or a BioTek reader) and validate on your deck before trusting a run.

Layout

plr_mcp/
  lab.py       stateful PyLabRobot wrapper (all the real calls live here)
  server.py    FastMCP server, one thin tool per Lab method
tests/
  test_lab.py  pytest suite, runs on chatterbox (no hardware)
examples/
  smoke_test.py end-to-end run with no hardware

Development

pip install -e '.[dev]'
ruff check plr_mcp tests        # lint
ruff format --check plr_mcp tests
mypy plr_mcp --check-untyped-defs
pytest -q

CI runs all four on Python 3.10 through 3.13 for every push and pull request.

License

MIT