LC-MS Worklist Builder

LC-MS Worklist Builder (MassLynx, SCIEX OS, MassHunter, Xcalibur): MCP Server

Let an AI agent build LC-MS sample queues (worklists, sequences, batches) and export them as import files for Waters MassLynx, SCIEX OS, Agilent MassHunter Acquisition and Thermo Xcalibur. The agent can lay out samples on a tray, insert blanks and QCs, randomise the run order with a recorded seed, check the list for mistakes, convert an existing file from one vendor to another, and write the file for a person to import. It uses only documented import formats. It never starts an acquisition and doesn't talk to the mass spectrometer.

Try it without an instrument

uvx labmcp-ms-worklist --simulate --check

--simulate uses a temporary output folder that is deleted when the server stops. Everything else is the same code.

Set up

The "instrument address" is the output folder where worklist files are written (default ./worklists, created if missing):

uvx labmcp-ms-worklist --address "D:\Worklists" --check        # Windows acquisition PC or a shared drive

uvx labmcp-ms-worklist --address ~/lcms/worklists --check # macOS / Linux, then copy the files over

• The server only reads and writes inside this folder. It refuses .., absolute paths elsewhere and symlinks that point outside it. It never overwrites an existing file unless the agent passes overwrite=true.
• To edit or convert an existing file, or to use a vendor template, copy it into the folder first.
• Point --address at a folder the acquisition software watches only if the vendor documents that behaviour for your setup. Otherwise import the file by hand (instructions below).

Add to your MCP client

Claude Code

claude mcp add ms-worklist -- uvx labmcp-ms-worklist --address ~/lcms/worklists

Claude Desktop / Cursor / Windsurf

{

"mcpServers": { "ms-worklist": { "command": "uvx", "args": ["labmcp-ms-worklist", "--address", "/path/to/worklists"] } } }

--read-only keeps only the tools that inspect things (list_formats, validate_worklist, import_worklist, get_worklist, list_worklists).

Tools

get_connection_info, get_command_log and reconnect are built into every LabMCP server. There are no HAZARD tools: nothing here moves, heats, injects or acquires. The server only writes files. The CONTROL tools change in-memory drafts or write a file, and --read-only hides them.

Typical flow: create_worklist → add_samples (optional) → insert_qc_blanks → validate_worklist → export_worklist, then import the file in the vendor software.

Formats

The table below separates what the vendor documents say (verified) from what the server assumes. list_formats returns the same information to the agent. To be sure of the header for your software version, export an empty batch, sequence or worklist from your own system, put it in the output folder, and pass it to export_worklist as template_path. The server then writes that header, and that delimiter, exactly.

Waters MassLynx: sample list worksheet (waters_masslynx)

• Import: Sample list > File > Import Worksheet, File of Type "Comma Delimited (*.CSV, *.TXT)".
• Verified:
• Row 1 holds the MassLynx FIELD IDs, which are case sensitive. Columns can be in any order, and an Index column is added. Source: WKB63781.
• The required columns are FILE_NAME, INLET_FILE, MS_FILE, SAMPLE_LOCATION and INJ_VOL. Source: MassLynx 4.2 Getting Started Guide 715009602, Table 5-1. The "Bottle" column's FIELD ID is SAMPLE_LOCATION, not BOTTLE.
• The example files attached to WKB63781 use CRLF line endings and unquoted fields, TYPE values Blank/Standard/QC/Analyte, and method names without an extension.
• Mapping: FILE_NAME = data file, FILE_TEXT = sample name, MS_FILE, MS_TUNE_FILE, INLET_FILE, SAMPLE_LOCATION, TYPE, ID, INJ_VOL, Index. You can add any other FIELD ID (for example CONC_A or QUAN_REF) per sample through extra.
• Assumed:
• solvent and double_blank are written as Blank.
• Extension checks: .exp for MS_FILE and .ipr for the tune file, applied only when an extension is given.
• Files are UTF-8 without a BOM. Non-ASCII text is flagged.
• The waters_plate_well position pattern (1:A,1) is a common convention. Its comma is CSV-quoted.

SCIEX OS: batch import (sciex_os)

• Import: Batch workspace > Open > Import from file, then Save As.
• Verified:
• Batches import from .txt or .csv, and the column layout must come from a batch exported from SCIEX OS. Source: SCIEX KB.
• Column names Sample Name (< 252 characters), MS Method, Sample Type, Data File and Processing Method. Source: SCIEX OS Feature Guide RUO-IDV-05-15796-C, Table 4-1.
• Rack Type, Rack Position, Plate Type, Plate Position and Vial Position columns. Source: SCIEX KB.
• Sample types Unknown, Blank, Standard, QualityControl, Solvent and Double blank.
• Several samples can share one data file.
• Assumed:
• SCIEX doesn't publish the exact header text of an exported batch. The default header (Sample Name,Sample ID,Sample Type,MS Method,LC Method,Rack Type,Rack Position,Plate Type,Plate Position,Vial Position,Injection Volume,Data File,Processing Method,Comment) is a best guess. Use template_path with your own export. validate_worklist and export_worklist warn when no template was used.
• Extensions .msm, .lcm and .qmethod produce warnings only.
• Rack and plate columns are set with vendor_columns or per sample with extra.

Agilent MassHunter Acquisition: worklist CSV import (agilent_masshunter)

• Import: Worklist, right-click > "Add/Append Samples from... (csv, xlsx)". Older versions call it "Import Worklist...". You don't need a map file because the headers match the worklist column names.
• Verified:
• The header Sample Name,Barcode,Rack Code,Sample Position,Method,Data File,Sample Type,Level Name,Inj Vol (µL),Comment, positions like P1-A1, and the types Calibration and Sample come from the example file shipped in D:\MassHunter\Worklist_Import, as quoted on the Agilent Community.
• Save as UTF-8 when the file contains µ. Source: Agilent Community.
• Inj Vol = -1 means "As method". Source: Agilent Known Problem Report.
• Sample Position, Method and Data File must be filled in. Source: Study Manager Quick Start G3335-90140.
• Assumed:
• The file has a UTF-8 BOM and CRLF line endings.
• Data files get a .d suffix.
• Methods should end in .m.
• The sample types Blank, QC and DoubleBlank don't appear in the example; solvent is written as Blank.

Thermo Xcalibur: sequence CSV import (thermo_xcalibur)

• Import: Sequence Setup > File > Import Sequence.
• Verified in the Xcalibur 2.2 Acquisition and Processing User Guide XCALI-97209 Rev. D, Appendix A:
• Only .csv files are accepted.
• The first cell must be Bracket Type=n (1 Overlapped, 2 None, 3 Non-Overlapped, 4 Open).
• The separator