Openreadout MCP Server

OpenReadout

OpenReadout is an open-source reader for lab-instrument files, designed for AI agents.

Give AI agents full access to raw data from microscopes, mass spectrometers, cytometers, electrophysiology rigs, and 90+ other instrument file formats — in one command.

Open-source. Single binary. No vendor software. No dependencies. No network access. Works everywhere.

OpenReadout makes data stored in proprietary instrument file formats readable: it pulls out the metadata, images, traces, spectra, and tables as structured JSON and renders previews so your agent can see and understand the data. Every format is validated against real data and independent libraries.

For AI Agents — Get Started in One Line

Paste this into your AI agent's chat — it will read the skill file and install everything:

curl -fsSL https://raw.githubusercontent.com/openreadout/openreadout/main/skills/openreadout/SKILL.md

That's it. The skill file tells the agent how to install the binary and how to use every command.

For Humans

Option A — Browser: Open the browser demo and drop a file on it. It runs OpenReadout compiled to WebAssembly inside the page; nothing is uploaded.

Option B — CLI: Install the binary (see Installation), then connect it to your agent:

openreadout self skill --install all      # skill for Claude Code, Codex, Cursor, Copilot, Gemini CLI
openreadout mcp --install claude-desktop  # MCP server for Claude Desktop (or cursor, codex, vscode, ...)

Your agent can now open, check, plot, and convert instrument files on your behalf.

For Developers — See It Live in 30 Seconds

# 1. Install (macOS / Linux; other ways below)
curl -fsSL https://raw.githubusercontent.com/openreadout/openreadout/main/scripts/install.sh | sh

# 2. See what is in a file — reads headers only, fast on any size
openreadout info cells.lif

# 3. Look at it — writes cells.preview.png
openreadout preview cells.lif --composite

# 4. Convert it — read back and verified before it is saved
openreadout export cells.lif -o cells.ome.tiff

That's it. The same commands work on a CZI, an ND2, a Thermo RAW, an ABF, or any of the other formats.

Quick Start

# What is in the file?
openreadout info cells.lif
# → format: Leica LIF (lif) v2  size: 16.0 MiB  images: 1  planes: 2
# →   [0] PEI_laminin_35k  2048x2048 z=1 c=2 t=1  uint16  px=0.3250 µm
# →       objective: HC PL FLUOTAR L 20x/0.40 DRY

# Is it complete?
openreadout check partial-copy.lif
# → error  truncated       block chain runs past end of file
# → error  missing_planes  geometry needs 16777216 bytes but only 8969789 are stored

# Integrate the peaks of a chromatogram
openreadout analyze peaks gc-run.ch --min-height 1
# → 4 peaks, area in pA·min
# → 1   4.852 min  area 0.2779  25.08 %
# → ...

# Structured JSON for scripts and agents
openreadout info cells.lif --json

{
  "ok": true,
  "schema_version": "1",
  "data": {
    "format": { "id": "lif", "name": "Leica LIF", "vendor": "Leica Microsystems" },
    "images": [
      {
        "size_x": 2048, "size_y": 2048, "size_c": 2,
        "pixel_type": "uint16",
        "physical_size": { "x": 0.325, "y": 0.325, "unit": "µm" }
      }
    ]
  }
}

Why OpenReadout?

What used to take vendor software or a different library for every format:

import czifile, nd2, liffile, pyabf, flowio
# ... a different API, metadata layout, and set of quirks for each one ...

Now takes one command, for all of them:

openreadout info any-file --json

What OpenReadout can do:

• Inspect images, channels, traces, spectra, tables, and metadata -- in plain text or structured JSON
• Check files for truncation, missing planes, and damaged structure -- exit code 4 when a file is corrupt
• Export to OME-TIFF, OME-Zarr, mzML, NWB, CSV, Parquet, Arrow, JCAMP-DX, Allotrope ASM, and RDML -- every export read back and verified
• Preview image planes, traces, spectra, and plate heat maps as PNG
• Analyze chromatographic peaks, plate assays (IC50, standard curves), qPCR (Cq, ΔΔCq), NMR peaks, patch-clamp features, spikes, and flow-cytometry gates -- with documented methods
• Batch over whole directories, index lab shares, and watch running acquisitions

The format list has all 96 formats and their known gaps.

Use Cases

For Researchers:

• Open instrument files on any computer, without the acquisition software
• Convert a folder of raw files to OME-Zarr, mzML, or NWB for analysis and sharing
• Verify that files copied off an instrument PC are complete

For AI Agents:

• Answer questions about a file: channels, pixel size, objective, acquisition time, scan count
• Extract metadata, traces, spectra, and tables as JSON
• Run documented analyses (peak areas, IC50s, Cq values) and report the method used

For Core Facilities and Pipelines:

• Index a lab share into searchable Parquet tables with index and search
• Watch instrument directories and flag stalled or damaged acquisitions with watch
• Run in Nextflow, Snakemake, and Galaxy pipelines (integrations/)

Installation

Ships as a single self-contained binary. No Java, no Python, no vendor DLLs -- nothing else to install.

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/openreadout/openreadout/main/scripts/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/openreadout/openreadout/main/scripts/install.ps1 | iex

# Homebrew (macOS / Linux)
brew install openreadout/tap/openreadout

# npm (all platforms — fetches the native binary for your platform)
npm install -g openreadout

# Rust toolchain
cargo install openreadout --locked

Docker, Nix, cargo-binstall, and the other channels are on the install page.

Verify installation: openreadout --version

AI Integration

MCP Server

Built-in MCP server — register with one command:

openreadout mcp --install claude          # Claude Code
openreadout mcp --install claude-desktop  # Claude Desktop
openreadout mcp --install codex           # OpenAI Codex
openreadout mcp --install cursor          # Cursor
openreadout mcp --install vscode          # VS Code / Copilot
openreadout mcp --install gemini          # Gemini CLI

Windsurf, Zed, Continue, and Cline are supported too. The server exposes 15 tools (openreadout_info, openreadout_check, openreadout_preview, openreadout_export, openreadout_analyze, ...) over JSON-RPC — no shell access needed.

Claude Code Plugin

Installs the MCP server and the skill together:

/plugin marketplace add openreadout/agent-plugins
/plugin install openreadout@openreadout

Gemini CLI Extension

gemini extensions install https://github.com/openreadout/agent-plugins

Codex Plugin

codex plugin marketplace add openreadout/agent-plugins
codex plugin add openreadout@openreadout

The Claude Code plugin, the Gemini CLI extension and the Codex plugin each add the skill and the MCP server. They come from the small openreadout/agent-plugins repository, which each release updates. The server runs the openreadout binary from your PATH, so install it first.

Agent Skill

openreadout self skill --install claude   # ~/.claude/skills/openreadout
openreadout self skill --install agents   # ~/.agents/skills/openreadout (Codex, Cursor, Copilot, Gemini CLI)

The skill source is in skills/openreadout.

Why your agent will thrive on OpenReadout

• Deterministic JSON output — every command supports --json with published schemas. No regex parsing, no scraping stdout.
• Fixed exit codes — 0 ok, 1 error, 2 usage, 3 unknown format, 4 corrupt file, 5 I/O, 6 unsupported feature. Agents branch on the code, not on the message.
• Self-healing errors — every error carries a hint that says what to do next. Agents self-correct without human intervention.
• Assurance on every answer — each result says whether files like it were validated against an independent reader. Agents know when to double-check.
• Built-in preview renderer — preview writes a PNG the agent can look at. Agents can see the image, trace, or plate they are reasoning about.
• Cheap metadata — info reads headers only, so a 100 GB file costs the same as a small one. --only returns just the fields asked for, saving tokens.
• Safe by default — inputs are opened read-only and nothing connects to the network.

Error Recovery

# Agent asks for an image that does not exist
openreadout preview cells.lif --image 3 --json

{
  "ok": false,
  "error": {
    "code": "usage",
    "message": "usage error: image 3 not found (file has 1 images)",
    "hint": "Indices are zero-based; `openreadout info FILE --json` lists the images, traces (sweep_count, sample_count), tables (row_count) and spectra the file holds.",
    "exit_code": 2
  }
}

The agent follows the hint, lists the images, and picks the right index.

Python and R

Python — pip install openreadout returns metadata as dicts and pixels as NumPy, dask, or xarray arrays, with plugins for bioio and napari. See the Python guide.

import openreadout

with openreadout.File("cells.lif") as f:
    f.images[0]["channels"]     # same keys as `info --json`
    stack = f.to_xarray(0)      # labelled with channel names and µm

R — the R package returns arrays and data frames. See the R guide.

Comparison

Validation

Readers are tested against about 1,500 public instrument files. Each file's geometry, metadata, and plane hashes are compared with independent libraries (czifile, nd2, liffile, Bio-Formats, FlowIO, pyABF, and others), and pixel data must match exactly. See Validation.

Every reader was written from public files and permissively licensed documentation — no vendor SDKs, headers, DLLs, or GPL source code. See the clean-room policy.

Documentation

The documentation has guides for every command and format:

• Getting started: Install | Your first file | Reading the JSON output
• Reference: Commands | MCP tools | Formats
• Guides: AI agents | Python | R | Recipes | Batch tables
• A file that does not work: run openreadout check --report FILE and attach the bundle to a new-variant issue. It contains no data values, sample names, or paths.

Privacy

OpenReadout runs on your computer, makes no network connections and sends no telemetry. See PRIVACY.md.

License

Licensed under either the Apache License 2.0 or the MIT license, at your option. OpenReadout is not affiliated with any instrument vendor; see TRADEMARKS.md.

Bug reports and contributions are welcome on GitHub Issues. See CONTRIBUTING.md, and read the clean-room policy before working on a reader.

Images and demo files come from the public test corpus (corpus/manifest.toml), used under their licences: mouse section, Zeiss sample images for Bio-Formats (Zenodo 10577621, CC-BY-4.0); Convallaria lambda scan, Maria Manuela Azevedo (Zenodo 14976703, CC-BY-4.0); BaTiO3 STEM, Rama Vasudevan and Gerd Duscher (Zenodo 8190744, CC-BY-4.0); H&E QPTIFF, PerkinElmer via the OME sample images (CC-BY-4.0); qPCR, the RDML R package (MIT); MS2, ProteoWizard test data (Apache-2.0); HPLC, cheminfo (MIT); EPR, EasySpin (MIT); patch clamp, pyABF (MIT); GC-FID, entab (MIT); terminal demo, Allen Institute for Cell Science (BSD-3-Clause). demo.tape regenerates the demo.

---

If you find OpenReadout useful, please give it a star on GitHub — it helps others discover the project.