Micro-Manager Microscope

Micro-Manager Microscope — MCP Server

Let an AI agent snap images, acquire z-stacks and time-lapses, move the stage and focus within limits you set, switch channels and objectives, set exposure, operate shutters and run autofocus on any microscope controlled by Micro-Manager, through its open device layer (MMCore) and pymmcore-plus.

Try it without hardware

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

The simulator is a widefield fluorescence microscope with a 512 x 512, 12-bit camera, an XY stage, a focus drive, a shutter, a DAPI / FITC / TRITC / Brightfield filter wheel, a 10x / 20x / 40x turret and a hardware autofocus, looking at a field of cell nuclei. Its images defocus with Z, scale with exposure, bleach with light dose, saturate at 4095 and carry shot and read noise, so focusing, exposure and bleaching behave like on a real microscope.

Connect your microscope

1. Hardware configuration: create and test a .cfg file with Micro-Manager's Hardware Configuration Wizard (in the Micro-Manager app), including config groups for channels (usually Channel) and objectives (Objective) and a pixel-size calibration. Close the Micro-Manager app afterwards: a device can only be opened by one program.
2. Device adapters: pymmcore-plus needs Micro-Manager's device adapter libraries in a version that matches its pymmcore build. Either download them with pymmcore-plus' own installer:
   bash

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

   or point to an existing Micro-Manager installation with --option mm_path=/path/to/Micro-Manager (it must be a build whose device interface matches pymmcore; mmcore info shows the version). Vendor camera SDKs and drivers must be installed separately, as for Micro-Manager itself.
3. Test the connection:
   bash

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

   --check loads the configuration and prints the camera, stages and other device roles.

Add to your MCP client

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"]    }  }}

Add --read-only to let the agent read positions and settings without imaging or moving anything (stop_stage and close_shutter stay available). For other clients, generate the snippet with uvx labmcp config micro-manager --address /path/to/MyScope.cfg --client vscode (also cursor, codex, claude-code).

Tools

get_connection_info, get_command_log and reconnect are built into every LabMCP server. get_command_log lists every state-changing MMCore call (setPosition(1502.0), setConfig('Channel', 'FITC'), snapImage(), ...).

Safety limits

Override at launch, e.g. --limit max_z_step_um=10 --limit max_frames=2000.

Soft limits (recommended): absolute stage bounds in micrometres, set with driver options. Find them by moving to the safe extremes in Micro-Manager (e.g. Z with the objective just below the coverslip) and reading the positions:

Every Z and XY move, every z-stack slice and every autofocus result is checked against the step limits and soft limits before anything moves (autofocus results are checked afterwards and undone if out of range).

Example prompts

• "What's on this microscope? List the channels and objectives, and the current position."
• "Switch to FITC, find an exposure that uses about half the camera's range without saturating, then snap an image and show me."
• "Autofocus, then take a z-stack from −10 to +10 µm in 1 µm steps in DAPI and FITC and tell me which slice is sharpest."
• "Move 500 µm to the right and snap a DAPI image; repeat three more times to make a row of four fields."
• "Record a time-lapse in TRITC every 30 s for 20 minutes and tell me how much the signal bleached."
• "Something is wrong — stop the stage and close the shutter."

Notes

• Objective crashes. Moving the focus drive toward the sample can drive the objective into the coverslip or dish. get_position / get_system_info report focus_direction (whether increasing Z moves the objective toward the sample, as declared by the device adapter; often unknown). Configure z_min_um / z_max_um for every microscope you connect.
• Objective changes (set_objective) rotate the nosepiece and are marked as hazardous; set_config refuses config groups whose names look like objective or turret groups (Objective, Nosepiece, Turret, Magnification, Lens). Other groups are applied as-is: if one of your presets moves hardware near the sample, name the group accordingly or leave it out of the configuration.
• Light exposure. With auto-shutter on (the default), the light path only opens while the camera exposes. set_shutter(open=True) leaves the sample lit until close_shutter is called.
• Images are saved as TIFF files (ImageJ hyperstacks with pixel size, Z spacing and frame interval) in save_path, or in --option data_dir=... (default: the system temp folder, labmcp-micro-manager/). save_path must end in .tif/.tiff and must not be a folder; it is checked before anything moves or is exposed. Existing files are never overwritten (a numeric suffix is added). Tools return statistics (min/max/mean/std, saturated fraction, a sharpness score) and a small contrast-stretched PNG preview, never the full image.
• Acquisitions (acquire_z_stack, acquire_time_lapse) snap image by image with the current camera settings; they do not use hardware-triggered sequencing, so they are slower than Micro-Manager's MDA engine but behave identically on every device. stop_stage or close_shutter aborts them between frames; partial data is saved (an incomplete slice or timepoint is dropped). A z-stack returns the focus to its starting position unless it was aborted. An acquisition must fit in one tool call: one whose exposure time alone exceeds 3600 s is refused, and one that runs long because of stage, filter or camera overheads stops between slices/timepoints and reports why in note. Channels cannot come from an objective/turret group.
• Autofocus uses the configured autofocus device (fullFocus). Software autofocus plugins from the Micro-Manager Java app are not available.
• pymmcore-plus is imported only when a real configuration is loaded, so --simulate works without Micro-Manager's native libraries.

Hardware verification