Micro-Manager Microscope

Micro-Manager 显微镜 — MCP 服务

让 AI Agent 通过 Micro-Manager 的开放设备层（MMCore）和 pymmcore-plus，对任何由 Micro-Manager 控制的显微镜拍摄图像、采集 Z 轴堆栈和延时序列，在你设定的限制范围内移动载物台和调整焦点，切换通道和物镜，设置曝光，操作快门并运行自动对焦。

软件包	labmcp-micro-manager
仪器	任何配有 Micro-Manager 设备适配器的硬件（数百种相机、XY/Z 载物台、显微镜支架、滤光轮、快门和光源，来自 Hamamatsu、Photometrics、Andor、PCO、Basler、ASI、Prior、Ludl、Märzhäuser、Nikon、Zeiss、Olympus/Evident、Leica、Lumencor、CoolLED 等），由 Micro-Manager .cfg 硬件配置文件描述
接口	设备适配器所使用的接口：USB、串行、Camera Link / CoaXPress / GigE 帧采集卡
协议	通过 pymmcore-plus CMMCorePlus 使用 Micro-Manager MMCore API（MMCore API 参考、pymmcore-plus API、配置指南）
状态	🧪 模拟：已通过模拟显微镜和 pymmcore-plus 的真实核心（配合 Python 测试设备）进行测试，尚未在硬件上验证。报告硬件测试结果

无需硬件即可试用

uvx labmcp-micro-manager --simulate --check

模拟器是一台宽场荧光显微镜，配有 512 x 512、12 位相机、XY 载物台、调焦驱动、快门、DAPI / FITC / TRITC / Brightfield 滤光轮、10x / 20x / 40x 转盘和硬件自动对焦功能，可观察一片细胞核。图像会随 Z 轴位置变化而失焦，随曝光时间变化而改变亮度，随光照剂量增加而发生漂白，在 4095 处饱和，并带有散粒噪声和读出噪声，因此对焦、曝光和漂白效果都与真实显微镜类似。

连接你的显微镜

1. **硬件配置：**在 Micro-Manager 应用中使用其硬件配置向导创建并测试 .cfg 文件，其中应包含通道（通常为 Channel）和物镜（Objective）的配置组，以及像素尺寸校准。完成后关闭 Micro-Manager 应用：一台设备只能由一个程序打开。
2. **设备适配器：**pymmcore-plus 需要与其 pymmcore 构建版本匹配的 Micro-Manager 设备适配器库。你可以使用 pymmcore-plus 自带的安装程序下载：

   uvx --from labmcp-micro-manager mmcore install     # into pymmcore-plus' data folder
   uvx --from labmcp-micro-manager mmcore list        # show what was found
   

   或者使用 --option mm_path=/path/to/Micro-Manager 指向现有的 Micro-Manager 安装目录（其构建版本的设备接口必须与 pymmcore 匹配；mmcore info 可显示版本）。与 Micro-Manager 本身一样，厂商相机 SDK 和驱动程序必须另行安装。
3. 测试连接：

   uvx labmcp-micro-manager --address ~/scopes/Ti2_Prime95B.cfg --check
   uvx labmcp-micro-manager --address MMConfig_demo.cfg --check      # Micro-Manager demo devices
   

   --check 会加载配置并显示相机、载物台和其他设备角色。

添加到你的 MCP 客户端

Claude Code

claude mcp add microscope -- uvx labmcp-micro-manager --address /path/to/MyScope.cfg --option z_min_um=0 --option z_max_um=4500

Claude Desktop / Cursor / Windsurf（claude_desktop_config.json、.cursor/mcp.json、……）

{
  "mcpServers": {
    "microscope": {
      "command": "uvx",
      "args": ["labmcp-micro-manager", "--address", "/path/to/MyScope.cfg",
               "--option", "z_min_um=0", "--option", "z_max_um=4500",
               "--option", "data_dir=/data/microscope"]
    }
  }
}

添加 --read-only，即可让 Agent 读取位置和设置，但不能成像或移动任何设备（仍可使用 stop_stage 和 close_shutter）。对于其他客户端，使用 uvx labmcp config micro-manager --address /path/to/MyScope.cfg --client vscode 生成配置片段（客户端还支持 cursor、codex、claude-code）。

工具

工具	类型	描述
acquire_time_lapse	⚠️ 危险	在当前位置采集延时序列：每隔 interval_s 拍摄图像（每个时间点可选拍摄多个通道），保存为多页 TIFF，并报告每帧统计信息和强度变化（漂白）。受 max_frames 和 max_acquisition_duration_s 限制；stop_stage 可中止采集。
acquire_z_stack	⚠️ 危险	围绕当前焦点采集 Z 轴堆栈：沿 Z 轴移动拍摄各层（每层可选拍摄多个通道），保存为多页 TIFF，报告每层统计信息和最清晰的切片，并将 Z 轴移回起始位置。每层都必须位于起始位置的 max_z_step_um 范围内，且不得超出 Z 轴软限位。
autofocus	⚠️ 危险	运行已配置的自动对焦设备（例如硬件焦点锁）一次；该操作会移动焦点驱动器。如果结果超出 Z 轴步长或软限位范围，则会将焦点移回原位并报错。
close_shutter	🛑 安全	关闭快门（停止照射样品）并中止正在运行的采集。
get_command_log	👁 读取	返回最近发送给仪器的原始命令和收到的回复（最新记录在末尾）。可用于调试和记录操作内容。
get_connection_info	👁 读取	报告已连接的仪器（标识、地址、模拟或真实）、服务是否为只读，以及当前安全限值。请先调用此工具。
get_exposure	👁 读取	返回相机曝光时间，单位为毫秒。
get_position	👁 读取	读取 XY 载物台和焦点（Z 轴）的位置，单位为微米，并报告 Z 轴增大时物镜的移动方向。
get_system_info	👁 读取	描述显微镜信息：已加载的设备（相机、载物台、快门、滤光轮等）、各设备的用途、相机尺寸／位深／曝光时间、像素尺寸、包含预设值的配置组、当前位置和软限位。请先调用此工具。
list_config_groups	👁 读取	列出 Micro-Manager 配置组（例如 Channel、Objective）、组内预设值以及当前启用的预设值。
move_stage_xy	⚠️ 危险	移动 XY 载物台。超过 max_xy_step_um 或超出 XY 软限位的移动会在设备移动前被拒绝。请确保物镜和聚光镜不会碰到样品托架。
move_z	⚠️ 危险	移动焦点驱动器（Z 轴）。将物镜移向样品可能会撞上载玻片：超过 max_z_step_um 或超出 Z 轴软限位的移动会在设备移动前被拒绝。
reconnect	🛑 安全	关闭并重新打开与仪器的连接（例如仪器断电重启或重新插拔线缆后）。
set_config	🎛 控制	应用配置组预设值（例如切换通道：滤光块、光源、发射滤光片）。此处不允许使用物镜／转盘配置组，请使用 set_objective。
set_exposure	🎛 控制	设置相机曝光时间（毫秒）。曝光时间越长，图像越亮，但也会加剧光漂白。返回相机接受的曝光时间。
set_objective	⚠️ 危险	切换物镜（旋转物镜转盘）。较长或浸液物镜可能会撞上样品托架，或需要使用油／水：请先向用户确认。像素尺寸会随物镜变化。
set_shutter	⚠️ 危险	打开或关闭当前快门，并可选择切换自动快门。快门打开时会照射样品（并使其漂白），直到再次关闭。
snap_image	🎛 控制	使用当前通道、曝光时间和位置采集一张图像。曝光期间会照射样品。将完整图像保存为 TIFF，并返回摘要统计信息（最小值／最大值／平均值、饱和度、清晰度）以及可选的对比度拉伸预览。
stop_stage	🛑 安全	立即停止 XY 和 Z 载物台移动，并中止正在进行的 Z 轴堆栈或延时序列采集。
get_connection_info、get_command_log 和 reconnect 内置于每个 LabMCP 服务中。get_command_log 会列出每次改变状态的 MMCore 调用（setPosition(1502.0)、setConfig('Channel', 'FITC')、snapImage()，……）。

安全限制

限制	默认值	含义
max_z_step_um	50 µm	从当前位置起允许的最大对焦移动距离（也是最大的 z-stack 偏移量，以及允许的最大自动对焦校正量）
max_xy_step_um	20000 µm	单次调用允许的最大 XY 载物台移动距离（直线距离）
max_exposure_ms	10000 ms	相机最长曝光时间
max_frames	500	单次 z-stack 或延时摄影中允许的最多图像数（切片数或时间点数 x 通道数）
max_acquisition_duration_s	3600 s	延时摄影的最长时长（无论该值如何设置，单次工具调用最多可运行 3600 s）

启动时覆盖，例如：--limit max_z_step_um=10 --limit max_frames=2000。

**软限制（推荐）：**以微米为单位的载物台绝对边界，通过驱动选项设置。在 Micro-Manager 中移动到安全极限位置（例如，物镜刚好位于盖玻片下方时的 Z 位置），并读取位置值，即可确定这些边界：

选项	含义
z_min_um、z_max_um	允许的对焦范围。将物镜朝样品移动的一侧设置得更严格。
x_min_um、x_max_um、y_min_um、y_max_um	允许的 XY 范围（例如，载玻片或培养板托架的区域）

每次 Z 和 XY 移动、每个 z-stack 切片以及每个自动对焦结果，都会在设备移动前根据步长限制和软限制进行检查（自动对焦结果会在完成后检查，若超出范围则撤销）。

示例提示词

• “这台显微镜上有什么？列出通道和物镜，以及当前位置。”
• “切换到 FITC，找到一种曝光设置，使相机信号达到量程的一半左右且不饱和，然后拍摄并显示图像。”
• “自动对焦，然后在 DAPI 和 FITC 通道中以 1 µm 的步长，从 −10 到 +10 µm 拍摄 z-stack，并告诉我哪一层最清晰。”
• “向右移动 500 µm 并拍摄 DAPI 图像；再重复三次，拍出一排四个视野。”
• “每隔 30 s 在 TRITC 通道拍摄一次，进行 20 分钟的延时摄影，并告诉我信号漂白了多少。”
• “出问题了——停止载物台并关闭快门。”

注意事项

• 物镜可能发生碰撞。 将调焦驱动器朝样品方向移动，可能导致物镜撞上盖玻片或培养皿。get_position / get_system_info 会报告 focus_direction（根据设备适配器的声明，Z 值增大是否会使物镜朝样品方向移动；通常为 unknown）。请为连接的每台显微镜配置 z_min_um / z_max_um。
• 更换物镜（set_objective）会旋转物镜转盘，因此被标记为危险操作；对于名称看起来像物镜或转盘组的配置组（Objective、Nosepiece、Turret、Magnification、Lens），set_config 会拒绝应用。其他组会照常应用：如果某个预设会使硬件移动到样品附近，请相应命名该组，或将其排除在配置之外。
• 光照曝光。 自动快门开启时（默认设置），光路仅在相机曝光期间打开。set_shutter(open=True) 会使样品持续受光，直到调用 close_shutter。
• 图像保存为 TIFF 文件（包含像素尺寸、Z 轴间距和帧间隔的 ImageJ 超级堆栈），存放在 save_path 中，或存放在 --option data_dir=... 指定的位置（默认：系统临时文件夹 labmcp-micro-manager/）。save_path 必须以 .tif / .tiff 结尾，且不能是文件夹；在任何部件移动或曝光前都会进行检查。绝不会覆盖现有文件（会添加数字后缀）。工具会返回统计信息（最小值/最大值/平均值/标准差、饱和比例、清晰度评分）以及经过小幅对比度拉伸的 PNG 预览，绝不会返回完整图像。
• 采集（acquire_z_stack、acquire_time_lapse）会使用当前相机设置逐张拍摄图像；它们不使用硬件触发的序列采集，因此速度比 Micro-Manager 的 MDA 引擎慢，但在所有设备上的行为一致。stop_stage 或 close_shutter 会在帧间中止采集；部分数据会被保存（不完整的切片或时间点会被丢弃）。Z 轴堆栈采集结束后会将焦点移回起始位置，除非采集被中止。一次采集必须能在一次工具调用中完成：仅曝光时间就超过 3600 s 的采集会被拒绝；因载物台、滤光片或相机开销而运行过久的采集会在切片/时间点之间停止，并在 note 中说明原因。通道不能来自物镜/转盘组。
• 自动对焦使用已配置的自动对焦设备（fullFocus）。Micro-Manager Java 应用中的软件自动对焦插件不可用。
• 只有在加载真实配置时才会导入 pymmcore-plus，因此 --simulate 无需 Micro-Manager 原生库即可运行。

硬件验证

显微镜 / 相机 / 载物台	Micro-Manager 适配器	接口	验证者	日期
暂无：抢先验证