bioimage-mcp-server

An MCP server that gives LLM agents access to microscopy image data. Reads 150+ file formats (CZI, ND2, LIF, OME-TIFF, and many more) via Bio-Formats and exposes five tools for inspecting metadata, generating visual previews, computing intensity statistics, and converting to open formats.

Hand your agent a .czi and ask "what channels were acquired?" or "is this image saturated?" — no desktop application or one-off script required.

Caution!

This is a very new proof-of-concept implementation. It has been architected to be robust, extensible, and safe. However, it does not have extensive use to find in-practice problems!

Use with caution, but also enthusiasm, because it's nice to have your LLMs have better access to your data. If you see something wrong, or would like a feature tweaked, please submit an issue!

Quick start

Prerequisites

• JBang (installs and manages the JVM for you)

Installation should be one line on the command-line, listed on the download page!

To use with Claude Code

claude mcp add bioimage-mcp \
  -- jbang https://github.com/ichoran/bioimage-mcp-server/blob/main/runner/bioimage_mcp.java

Then future invocations of claude will have access.

Or from a local clone or copy of the bioimage_mcp.java file (generally you should use the absolute path on your system, not just runner/bioimage_mcp.java):

claude mcp add bioimage-mcp \
  -- jbang runner/bioimage_mcp.java

To remove,

claude mcp remove bioimage-mcp

and future invocations will no longer have access.

To use with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json), with the same caveats about paths:

{
  "mcpServers": {
    "bioimage-mcp": {
      "command": "jbang",
      "args": ["runner/bioimage_mcp.java"]
    }
  }
}

Other clients

Instruct the client to run using jbang via URL or local target, using the Claude examples as a guide.

File access

By default the server only accesses files under directories declared by the MCP client (client roots). To grant access to additional paths, or to deny access to sensitive directories, copy the runner file and edit the allow/deny lists:

BioImageMcpServer.builder()
    .allow("/data/microscopy")
    .allow("/shared/lab-images")
    .deny("/data/microscopy/private")
    .build()
    .run(args);

This keeps your access rules inspectable and version-controllable in a single file. Then point your MCP client at your edited copy instead of the original.

For quick one-off use, you can also pass --allow and --deny flags on the command line:

jbang runner/bioimage_mcp.java --allow /data/microscopy --deny /tmp/secret

CLI flags are merged with any paths hardcoded in the runner file. Deny rules always win. See DESIGN.md §5 for details.

Tools

All tools accept an absolute file path and handle large files safely (adaptive subsampling, time budgets). Errors are returned as structured messages, never silently swallowed — see DESIGN.md for the rationale.

Typical workflow

1. inspect_image — learn what's in the file (start with summary detail)
2. get_thumbnail — quick visual overview
3. get_plane / get_intensity_stats — detailed investigation
4. export_to_tiff — convert for downstream tools (FIJI, napari, etc.)

Example session (in part)

... [View full README on GitHub](https://github.com/Ichoran/bioimage-mcp-server#readme)