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).

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]"
   

3. 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 (trailer item Access Id:). The server numbers scans automatically if you don't. A custom scan usually finishes before the agent's next tool call, so wait_for_scan(access_id=...) also returns a result that arrived after the scan was placed but before the wait started. IAPI leaves the result undefined when several custom scans are placed before the instrument has processed the earlier ones; the rate limit keeps this under control.
• Parameter names differ by model and Tune version (e.g. Analyzer on Tribrids). Use get_possible_scan_parameters and pass anything that has no named argument through extra_parameters.
• Scan headers: scan_number, ms_order, scan_mode and precursor_mz come from header keys used in Thermo's examples (Scan, MSOrder, ScanMode, PrecursorMass[0]). master_scan_number, agc_target and injection_time_ms are read from the trailer names Thermo raw files use (Master Scan Number:, AGC Target:, Ion Injection Time (ms):). The IAPI repository doesn't document these, so they may be null on your instrument. Use include_header_trailer=true to see exactly what it sends.
• Readbacks: IAPI has no fixed list of readback names (vacuum gauges, voltages). get_instrument_status shows the names from IInstrumentValues.ValueNames and the latest scan StatusLog, where the vacuum readings usually appear.
• Licence check: on Exploris instruments the server reports whether an API licence is present (IExplorisInstrumentAccess.Licenses). Tribrid and Exactive instruments enforce the licence in the instrument service, and a refused command reports it.
• Verified API surface: every IAPI member the pythonnet backend touches is listed with its source file in iapi_members.py (checked against thermofisherlsms/iapi@c246dcc). A test fails if the backend uses a name that isn't in that list.
• Scan data: each scan's .NET object is copied and disposed at once, as Thermo's examples require (otherwise the instrument's shared memory stays blocked). Up to 5 000 centroids per scan are kept. max_centroids limits what a tool returns, and get_recent_scans(save_path=...) writes all kept centroids to a new CSV file (the path must end in .csv and must not exist yet: existing files are never overwritten).

Hardware verification