Thermo Orbitrap (Instrument API)

Thermo Orbitrap (Instrument API): MCP Server

Let an AI agent watch and steer a Thermo Fisher Orbitrap mass spectrometer in real time: check the instrument mode and vacuum, read the scans streaming off the instrument (filtered by MS order, with the most intense centroids), place validated custom scans and pick up their results, set a repeating scan, and start, pause or stop acquisitions to a raw file. It does this through Thermo's own Instrument API (IAPI).

[!IMPORTANT]

This is an adapter. It contains no Thermo software. The IAPI is a Windows .NET API. To use it you need a signed IAPI software licence agreement with Thermo Fisher Scientific, with the licence applied to your instrument (legal requirements, licence FAQ, how to obtain a licence). This package never bundles or downloads the IAPI assemblies: you point it at the ones you obtained. It has never been tested on real hardware. Everything below was developed against the official IAPI interface definitions and examples and a simulator.

Try it without hardware

uvx labmcp-thermo-iapi --simulate --check

The simulator is an Orbitrap Exploris 480 by default (--option sim_model=eclipse or qexactive-hf for the others). It runs a synthetic tryptic digest: MS1 survey scans in On mode, a data-dependent top-10 method during an acquisition, custom and repeating scans that come back with their access id, realistic transient and injection times, and a status log with vacuum readings every ~5 s.

Connect your instrument

On the Windows instrument PC, with Tune installed and your IAPI licence applied:

1. Get the IAPI assemblies that come with your licence (for a Tribrid: API-2.0.dll, Spectrum-1.0.dll, Thermo.TNG.Factory.dll and Fusion.API-2.0.dll for Tune 4.3 or Fusion.API-1.0.dll for Tune 4.2 and earlier). Put them in a folder, e.g. C:\IAPI.
2. Install Python 3.10+ and the server with pythonnet:

   pip install "labmcp-thermo-iapi[windows]"

1. Test the connection (the instrument family picks the connection recipe from the IAPI examples):

   labmcp-thermo-iapi --option instrument=tribrid  --option assembly_dir=C:\IAPI --check   # Fusion/Lumos/Eclipse/Ascend

labmcp-thermo-iapi --option instrument=exploris --option assembly_dir=C:\IAPI --check # Exploris 240/480 labmcp-thermo-iapi --option instrument=exactive --option assembly_dir=C:\IAPI --check # Q Exactive family

The server gives a specific message if it is not running on Windows, pythonnet is missing, the folder or an assembly is missing, the IAPI service does not connect (Tune not running), or IAPI refuses a command for lack of a licence.

Other options: readbacks=Name1;Name2 (instrument values to show in get_instrument_status; the tool lists the names your instrument exposes), exclusive_scans=true (exclusive rather than cooperative IScans access), runtime=coreclr, connect_timeout_s, buffer_size (scans kept in memory, default 500).

Add to your MCP client

claude mcp add orbitrap -- labmcp-thermo-iapi --option instrument=tribrid --option assembly_dir=C:\IAPI

{

"mcpServers": { "orbitrap": { "command": "labmcp-thermo-iapi", "args": ["--option", "instrument=exploris", "--option", "assembly_dir=C:\\IAPI"] } } }

Add --read-only to let the agent watch scans and status but not place scans or start acquisitions. The stop and cancel tools stay available. To reach the server from another computer, run it with --transport http --host 0.0.0.0 --port 8000 on the instrument PC and protect that port.

Tools

get_connection_info, get_command_log and reconnect are built into every LabMCP server. Every IAPI control call (with the exact scan values sent) is recorded in the command log.

Safety limits

Override at launch: --limit max_custom_scans_per_minute=600.

On top of these limits, every custom and repeating scan value is checked against the instrument's own IScans.PossibleParameters before anything is sent: the parameter name must exist, numbers must lie inside the instrument's range (for example the m/z range for FirstMass/LastMass), and choice parameters such as OrbitrapResolution must be one of the allowed values. IAPI itself silently ignores illegal values, which is why the server checks first, and why accepted values are sent in the instrument's own spelling (hcd goes out as HCD, 2.0 for an integer parameter as 2).

stop_acquisition attempts every step (cancel the acquisition, the custom scans, the repeating scan, Standby) even if one fails, and reports what failed.

Example prompts

• "Is the Orbitrap in On mode and what are the vacuum readings? How many scans came in during the last minute?"
• "Show me the last 5 MS2 scans with their precursor m/z, injection times and top 10 fragments."
• "Place a 120k SIM scan on m/z 524.26 with a 10 m/z window and tell me the most intense peaks you see."
• "Start a 30-minute acquisition to D:\Data\HeLa_test.raw with sample name HeLa 200 ng, then check every few minutes that MS2 scans are still arriving."

Notes

• Instrument mode: scans only arrive in On mode, and custom scans and acquisitions need it too. stop_acquisition(standby=true) switches to Standby. This server has no tool to switch back to On (do that in Tune).
• Custom scans: values you leave out come from the instrument's defaults, as Thermo documents for IScanDefinition.Values. running_number comes back as the scan's `access_id