Mass Spectrometry Data (mzML, Bruker TDF, vendor conversion) — MCP Server

Let an AI agent find, read and analyse LC-MS data files from any vendor through open interfaces: list the runs in a folder, report the instrument and acquisition details, plot TIC/BPC chromatograms, extract ion chromatograms with apex and area, read spectra, find MS2 scans by precursor m/z, and run a quick QC. Vendor files are converted to mzML with a converter you have installed. This is a data server: it controls no hardware.

Try it without data

uvx labmcp-ms-data --simulate --check

--simulate serves one synthetic 12-minute DDA LC-MS/MS run (simulated_lcms_run.mzML): eight known analytes (caffeine, sulfamethoxazole, leucine enkephalin, angiotensin II 2+, verapamil, glu-fibrinopeptide B 2+, reserpine, terfenadine) eluting as Gaussian LC peaks with isotope envelopes, a polysiloxane background ion, chemical noise, a top-5 DDA method with dynamic exclusion and fragment spectra, AGC-like injection times, and one electrospray dropout at ~10.6 min for the QC tool to find.

Point it at your data

1. Install (pick the extras you need):

   uvx labmcp-ms-data --help                        # mzML / mzML.gz
   uvx --from 'labmcp-ms-data[bruker]' labmcp-ms-data --help   # + Bruker timsTOF spectra/XICs
   uvx --from 'labmcp-ms-data[mzmlb]' labmcp-ms-data --help    # + mzMLb
   

2. Choose the data folder with --address (default: the current directory; the server refuses to start in the filesystem root, where many MCP clients launch servers, without an --address). Subfolders are searched. The agent can only read and write inside this folder: paths with .., absolute paths elsewhere and symlinks pointing outside are refused.

   uvx labmcp-ms-data --address ~/data/lcms --check
   

3. Vendor files (optional): install a converter yourself; this package never bundles or downloads vendor libraries.

   • Thermo .raw, any OS: ThermoRawFileParser (--option converter=thermorawfileparser, plus --option converter_path=/opt/trfp/ThermoRawFileParser.dll if it isn't on PATH; .dll is started with dotnet, .exe with mono on Linux/macOS). With converter=auto, a converter_path is recognised from its file name.
   • All vendors, Windows: ProteoWizard msconvert (--option converter=msconvert).
   • All vendors, Linux/macOS: Docker and docker pull proteowizard/pwiz-skyline-i-agree-to-the-vendor-licenses (--option converter=docker). Pulling the image means you accept the vendor licences. Only the input's folder (read-only) and the output folder are mounted into the container. On Apple Silicon it runs under x86-64 emulation (slow). On Linux the output files are owned by root.
   • converter=auto (default) tries ThermoRawFileParser for Thermo files, then msconvert, then Docker.

   The commands used are: ThermoRawFileParser -i=<file> -o=<dir> -f=2 [-p] [-g] and msconvert <file> -o <dir> --mzML --zlib [--gzip] [--filter "peakPicking vendor msLevel=1-"] (inside Docker via wine msconvert). They are run without a shell, with a timeout; on timeout the converter's whole process tree (and the Docker container) is killed and the incomplete output is deleted.

Add to your MCP client

Claude Code

claude mcp add ms-data -- uvx --from 'labmcp-ms-data[bruker]' labmcp-ms-data --address /path/to/data

Claude Desktop / Cursor / Windsurf (claude_desktop_config.json, .cursor/mcp.json, …)

{
  "mcpServers": {
    "ms-data": {
      "command": "uvx",
      "args": ["--from", "labmcp-ms-data[bruker]", "labmcp-ms-data", "--address", "/path/to/data",
               "--option", "converter=docker"]
    }
  }
}

Add --read-only to hide convert_to_mzml (the only tool that writes a data file; save_path CSV exports inside the data folder remain available). A save_path must end in .csv (a name without an extension gets one), and an existing file is never replaced unless the call passes overwrite=true. For other clients, generate the snippet with uvx labmcp config ms-data --address /path/to/data --client vscode (also cursor, codex, claude-code).

Tools

get_connection_info, get_command_log and reconnect are built into every LabMCP server (reconnect here closes the cached runs). There are no HAZARD tools, because nothing physical is controlled, so no SAFETY stop tool is needed.

Safety limits

Override at launch: --limit max_conversion_time_s=7200.

Example prompts

• "Which runs are in this folder, and which ones need converting?"
• "Give me the instrument, acquisition date and scan counts for QC_2024_03_01.mzML."
• "Extract XICs for caffeine (195.0877) and verapamil (455.2904) at 5 ppm and report apex RT and area."
• "Find every MS2 scan of m/z 523.7745 between 5 and 7 min and show me the fragments of the most intense one."
• "Run a QC on the last three runs: any spray dropouts, and how many MS2 per cycle?"
• "Convert sample_07.raw to mzML, then plot its base peak chromatogram."

Notes

• Format support: mzML (indexed or not, optionally .gz) through pyteomics (Apache-2.0), using the PSI-MS vocabulary bundled with psims (no download). mzMLb needs the [mzmlb] extra (h5py, hdf5plugin). Gzipped mzML is decompressed to a temporary file for random access.
• Bruker timsTOF (TDF): run metadata (instrument, serial, date, m/z and 1/K0 ranges), the TIC (Frames.SummedIntensities), BPC intensity (Frames.MaxIntensity, the most intense single peak in any mobility scan; its m/z is not stored) and the DDA precursor list are read straight from the analysis.tdf SQLite tables (GlobalMetadata, Frames, Precursors, PasefFrameMsMsInfo), so they work without extras. Spectra and XICs need the [bruker] extra (timsrust-pyo3, Apache-2.0, wheels for Linux/macOS/Windows). MS1 and diaPASEF frames are summed over ion mobility (diaPASEF MS2 frames mix all isolation windows); each ddaPASEF precursor is one MS2 spectrum. Ion mobility is not resolved in the outputs. Bruker BAF .d folders need conversion.
• Vendor formats: Thermo, Waters, Agilent, SCIEX, Shimadzu and Bruker BAF files can only be decoded with the vendors' own libraries, whose licences don't allow redistribution. The server detects them and converts them with a tool you installed (see above). It never downloads vendor code.
• Numbers: retention times are in minutes (mzML scan start times in seconds are converted, going by the unit accession); XIC intensity is the sum of all peaks inside ± tolerance; areas are trapezoidal integrals over RT in minutes, with no baseline subtraction, between the points where the trace falls to 1 % of the apex or reaches a valley. The FWHM is measured within those bounds (it is null when a co-eluting peak keeps the trace above half height). Use them for relative comparisons.
• Big files: the first access to a run makes one pass over all spectra to index it (TIC, precursors, RTs). Up to 4 runs stay cached (--option cache_size=N). A run is reopened automatically when the file changes (modification time or size). XICs read every spectrum in the RT window, so narrow the window on long runs.
• Profile data: chromatograms and XICs work as-is. get_spectrum reports local maxima as "peaks". Convert with peak picking for proper centroids.

Hardware verification