使用说明

生物图像mcp服务器

MCP服务器，允许LLM代理访问显微镜图像数据。通过以下方式读取150多种文件格式（CZI、ND2、LIF、OME-TIFF等）生物格式并暴露五种工具用于检查元数据、生成视觉预览，计算强度统计并转换为开放格式。

交给你的经纪人 .czi 并询问“收购了哪些渠道？”或 “这个图像饱和了吗？”--没有桌面应用程序或一次性脚本必修的。

注意安全

这是一个非常新的概念验证实施。已经其架构具有健壮性、可扩展性和安全性。然而，它没有广泛使用，在实践中发现问题！

谨慎使用，但也要热情，因为有法学硕士学位很好更好地访问您的数据。如果你发现有什么问题，或者想功能已调整，请提交问题！

快速开始

先决条件

Jbang （为您安装和管理JVM）

安装应下载中列出的命令行上的一行页!

示例用法

与Claude Code一起使用

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

然后，未来对claude的调用将可以访问。

或者从bioimage_mcp.java文件的本地克隆或副本（通常是应该使用系统上的绝对路径，而不仅仅是 runner/bioimage_mcp.java）：

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

为了移除，

claude mcp remove bioimage-mcp

并且未来的调用将不再具有访问权限。

用作gRPC服务器（从GitHub启动）

跑

jbang https://github.com/ichoran/bioimage-mcp-server/blob/main/runner/bioimage_grpc.java \
  --allow /network/core/confocal/JaneDoe

在终端窗口中；按Ctrl-C终止。

通过127.0.0.1:8723连接；模式见src/proto/bioimage.proto。

（请注意，像素是通过文件系统端点传输的，这可能如果您的系统支持内存映射虚拟文件系统，则可以使用该系统；客户负责请求目标。)

与Claude Desktop一起使用

添加到您的Claude Desktop配置(claude_desktop_config.json), 对路径也有同样的警告：

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

其他客户

指示客户端通过URL或本地目标使用jbang运行，使用克劳德的例子作为指导。

其他传输（微服务）

同一图像核心也由三个非MCP传输曝光，每个传输都有它自己的JBang跑步者和同样的 --allow/--deny 规则：

超文本传输协议 — runner/bioimage_http.javaJSON输入，JSON/PNG输出。看 API-网址.
UNIX套接字 — runner/bioimage_socket.java；持久的，支持会话的连接加上零拷贝 共享内存存储 生的像素体积。看 API套接字.md.
gRPC（本地） — runner/bioimage_grpc.java；双向环回流，也支持会话，将共享内存存储重新用于批量数据。看 API-个人.md默认端口为8723。

套接字和gRPC传输支持会话：打开图像一次，获取一个句柄，并重用保持打开的阅读器进行多次读取；读者是当连接关闭时释放。看服务端点.md 对于共享操作目录和设计.md §9-§11的基本原理。

文件访问

默认情况下，服务器仅访问由声明的目录下的文件 MCP客户端（客户端根）。授予对其他路径的访问权限，或要拒绝访问敏感目录，请复制runner文件并编辑允许/拒绝列表：

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

这使您的访问规则在单个文件。然后将您的MCP客户端指向您编辑过的副本，而不是原件。

对于快速一次性使用，您也可以通过 --allow 和 --deny 旗帜在命令行上：

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

CLI标志与runner文件中硬编码的任何路径合并。否认规则总是赢。详见DESIGN.md§5。

平行性

export_to_ngff （OME Zarr导出）压缩worker上的分片块游泳池。通过以下方式控制其大小 --parallelism:

jbang runner/bioimage_mcp.java --parallelism 8      # 8 writer threads
jbang runner/bioimage_mcp.java --parallelism 0.5    # half the available cores

整数是线程数；小数是机器的小数岩芯（四舍五入）。默认值为 0.334 （大约三分之一的核心），这样共享机器的服务器就不会假设所有CPU都是自己的。游泳池是 服务器范围 --无论如何限制总压缩许多客户端连接。

碎片尺寸

默认情况下 export_to_ngff 自动调整每个分片文件的大小（约1 MB 像素），这提供了良好的并行（去）压缩，但可以产生很大的用于存储大量体积/时间序列数据的许多文件——在一个网络文件系统，其中每个文件操作都是一次往返。通过 suggested_planes_per_shard 要将更多平面捆绑到每个文件中：

它是一个建议，不是一个确切的数字。服务器选取一个分片形状它符合数据，接近你的提示，超调量低：
- 通常它捆绑在一起 Z平面 （每个分片一个通道/时间点）；
- 如果您的提示接近（在日志空间中）每个时间点的完整卷 (channels × Z)，它捆绑在一起 所有渠道 也一样——每个碎片一个时间点；
- 对于一个纯粹的 时间序列 （1个通道，1个Z）没有Z可以捆绑，所以它四分五裂时间相反。
这种灵活性很重要，因为显微镜文件的格式非常不同形状，以及在网络挂载上摊销每个文件延迟的正确单位这取决于形状。
明确的建议覆盖服务器的内部文件计数上限：即使它产生了很多文件（你要求的），它也很荣幸。当超过上限时，结果中会包含警告，因此文件计数成本从不隐藏。（相比之下，自动尺寸调整处理盖子作为坚硬的后挡板，并使碎片变粗以留在下面。）
实际选择的值始终报告为 shard_planes_per_series （每个导出系列一个条目），无论大小是自动的或暗示的，所以你可以确切地看到数据是如何到达的磁盘和调整。

内部读取粒度始终是一个平面，因此较大的分片永远不会产生单平面读取更昂贵——它们只会改变平面的分组方式成文件。

工具

工具	退货	目的
`inspect_image`	JSON	尺寸、像素类型、物理尺寸、通道、仪器信息
`get_ome_metadata`	JSON	完整的OME-XML元数据文档(`{format, content}`)，便携式形式
`get_thumbnail`	PNG	带Z投影和通道合成的RGB合成预览
`get_plane`	PNG	全分辨率单通道灰度平面
`get_intensity_stats`	JSON	最小值/最大值/平均值/标准偏差/中值、直方图、饱和度警告
`export_to_tiff`	JSON	使用可选子集转换为OME-TIFF
`export_to_ngff`	JSON	对于大型/云原生数据，转换为OME-Zarr（OME-NGFF 0.5，Zarr v3）

所有工具都接受绝对文件路径，并安全处理大文件（自适应子采样、时间预算）。错误返回为结构化消息，永远不会被默默吞噬——请参阅DESIGN.md了解理论基础。

典型工作流程

inspect_image --了解文件中的内容（从 summary 细节）
get_thumbnail --快速视觉概览
get_plane / get_intensity_stats --详细调查
export_to_tiff --转换为下游工具（FIJI、napari等）

示例会话（部分）

> Can you find a tiff file in (elided) and get image info about it?                                

● Searched for 1 pattern (ctrl+o to expand)

● Found several TIFF files. Let me inspect the first one.

● bioimage-mcp - inspect_image (MCP) [...]

● Here's the info on the first TIFF file:

  ┌─────────────────┬──────────────────────────┐
  │    Property     │          Value           │
  ├─────────────────┼──────────────────────────┤
  │ Format          │ Tagged Image File Format │
  ├─────────────────┼──────────────────────────┤
  │ Dimensions      │ 2000 x 480 pixels        │
  ├─────────────────┼──────────────────────────┤
  │ Z slices        │ 1                        │
  ├─────────────────┼──────────────────────────┤
  │ Channels        │ 1                        │
  ├─────────────────┼──────────────────────────┤
  │ Timepoints      │ 20,004                   │
  ├─────────────────┼──────────────────────────┤
  │ Pixel type      │ uint16                   │
  ├─────────────────┼──────────────────────────┤
  │ Pixel size      │ 1.0 x 1.0 µm             │
  ├─────────────────┼──────────────────────────┤
  │ Dimension order │ XYCZT                    │
  └─────────────────┴──────────────────────────┘

  This is a time-series with 20,004 frames — a single-channel, single-Z-plane
  recording at 2000x480 pixels. Looks like it could be a calcium imaging or
  similar time-lapse acquisition.

❯ Let's get the image stats from the first 120 timepoints and the last 120      
timepoints.                                                                     

● bioimage-mcp - get_intensity_stats (MCP) [...]
● bioimage-mcp - get_intensity_stats (MCP) [...]
                                                                                
● Here's a comparison of the first and last 120 timepoints:
                                                                                
  ┌────────────────┬─────────────────────┬──────────────────────────┐         
  │   Statistic    │ First 120 (t 0–119) │ Last 120 (t 19884–20003) │           
  ├────────────────┼─────────────────────┼──────────────────────────┤
  │ Min            │ 59                  │ 60                       │           
  ├────────────────┼─────────────────────┼──────────────────────────┤         
  │ Max            │ 489                 │ 281                      │
  ├────────────────┼─────────────────────┼──────────────────────────┤
  │ Mean           │ 98.53               │ 98.43                    │
  ├────────────────┼─────────────────────┼──────────────────────────┤
  │ Std Dev        │ 5.69                │ 5.07                     │
  ├────────────────┼─────────────────────┼──────────────────────────┤
  │ Median         │ 98                  │ 98                       │
  ├────────────────┼─────────────────────┼──────────────────────────┤
  │ Saturation     │ 0%                  │ 0%                       │
  ├────────────────┼─────────────────────┼──────────────────────────┤
  │ Bit depth used │ 0.66%               │ 0.34%                    │
  └────────────────┴─────────────────────┴──────────────────────────┘

  Key observations:
  - Very stable baseline — mean and median are essentially identical between the
   start and end of the recording (~98).
  - Reduced dynamic range over time — the max dropped from 489 to 281, and
  stddev decreased from 5.69 to 5.07. This could indicate photobleaching,
  reduced activity, or fewer bright transient events later in the recording.

从源头构建

先决条件

磨坊 1.1+

安装命令上应该有一两行线.

命令

mill test                # run all tests (429 unit + integration)
mill assembly            # build fat jar
mill run                 # run the server directly via Mill
mill publishLocal        # publish to ~/.ivy2/local for local testing

与JBang共同开发

根据本地构建测试运行器（不发布到Maven 中央）：

mill assembly
jbang --cp out/assembly.dest/out.jar runner/bioimage_mcp.java

(mill assembly 将脂肪罐写入 out/assembly.dest/out.jar不要使用 mill show assembly 对于类路径——在Mill 1.1中，它打印一个 ref:v0:<hash>:<path> PathRef字符串，不是裸路径。)

集成测试

将服务器作为子进程生成，并在其上执行MCP协议标准：

mill assembly && jbang integration-test/SmokeTest.java

看 integration-test/README.md 了解详情。

项目结构

src/server/          Main sources (Java 21, package lab.kerrr.mcpbio.bioimageserver)
test/src/server/     Unit tests (JUnit 5)
test/fixtures/       Test data (downloaded on demand, gitignored)
runner/              JBang entry point for end users
integration-test/    End-to-end MCP protocol tests

Bio-Formats API的使用仅限于 BioFormatsReader.java 和 BioFormatsWriter.java其他一切都取决于 ImageReader / ImageWriter 接口和模型记录。

许可证

GPL-3.0——见许可证.

生物格式(ome:formats-gpl)是GPL-2.0，与 GPLv3。

使用说明

生物图像mcp服务器

注意安全

快速开始

先决条件

示例用法

与Claude Code一起使用

用作gRPC服务器（从GitHub启动）

与Claude Desktop一起使用

其他客户

其他传输（微服务）

文件访问

平行性

碎片尺寸

工具

典型工作流程

示例会话（部分）

从源头构建

先决条件

命令

与JBang共同开发

集成测试

项目结构

许可证

相关 MCP

SVG转图像服务

文档转换服务

电子表格自动化MCP服务器

SAMtools MCP模型控制协议

网页内容抓取服务器

知识图谱记忆服务器