control_lights
Turn robot lights on or off
LABSCO SUMMARY
The robot and its API reference answer in the same session, which is where protocol work usually stalls.
Starting work is deliberately split: upload_protocol puts the file on the robot, create_run starts a run against a protocol_id, and run_time_parameters can be supplied at either end. control_run is the single door for play, pause, stop and resume, so the run state machine stays in one place. poll_error_endpoint_and_fix changes your protocol rather than reporting on it, and it needs both the JSON error report and the original protocol path.
What it is
A server for Opentrons lab robots with a double role: a searchable index of the Opentrons HTTP API, and direct control of a robot addressed by robot_ip.
What you get
- API lookup: search_endpoints by functionality, method, path or keyword with an include_deprecated switch, get_endpoint_details for one method and path, list_by_category for a functional group, and get_api_overview for the structure as a whole.
- Protocols onto the robot: upload_protocol takes the file path, a protocol_kind and run_time_parameters, and get_protocols lists what the robot already holds.
- Run control: create_run against a protocol_id, control_run for play, pause, stop and resume, get_runs for the history and get_run_status for one run in detail.
- Robot state: robot_health for connectivity, control_lights, and home_robot for the axes or a specific pipette by mount.
- Error triage: poll_error_endpoint_and_fix fetches a named JSON error report and fixes the protocol it came from.
Requirements
An Opentrons robot reachable over the network — the control tools take robot_ip — and the protocol file on disk, given as file_path to upload_protocol and as original_protocol_path to poll_error_endpoint_and_fix.
Setup effort
One command — npx -y opentrons-mcp
USE CASES
01
Getting a new protocol onto the bench robot
Check the robot is reachable, upload the protocol file with its run-time parameters, create the run and watch it from the client.
02
Stopping a run that has started going wrong
Find the run that is active, read where it got to, and pause, stop or resume it without walking to the robot.
03
Fixing the protocol the robot just rejected
Read the failure, hand the error report and the original file to the repair tool, and put the corrected protocol back on the robot.
04
Finding the API call behind a behaviour you need
Search the endpoint index by what you are trying to do, then read the one endpoint in detail rather than paging through the whole reference.
05
Returning the deck to a known state between runs
Home the axes or the pipette that was left mid-move, confirm the robot is answering, and put the lights back the way you found them.
14 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
control_run
Control run execution (play, pause, stop, resume)
create_run
Create a new protocol run on the robot
get_api_overview
Get high-level overview of the Opentrons HTTP API structure and capabilities
get_endpoint_details
Get comprehensive details about a specific API endpoint
get_protocols
List all protocols stored on the robot
get_run_status
Get detailed status of a specific run
get_runs
List all runs on the robot
home_robot
Home robot axes or specific pipette
list_by_category
List all endpoints in a specific functional category
poll_error_endpoint_and_fix
Fetch specific JSON error report and automatically fix protocols
robot_health
Check robot health and connectivity
search_endpoints
Search Opentrons HTTP API endpoints by functionality, method, path, or any keyword
upload_protocol
Upload a protocol file to an Opentrons robot
BEFORE YOU INSTALL
What to know first
Tools you get
14 tools when we connected.
Requires
- npx on PATH
- Node.js 18+
CONTEXT COST
Light Standing cost
Rated by the size of the 14 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Add the block to your client, or run the command directly.
Server setup
Configuration file
JSON
{
"mcpServers": {
"opentrons-mcp": {
"command": "npx",
"args": [
"-y",
"opentrons-mcp"
]
}
}
}npx
TERMINAL
npx -y opentrons-mcp
