Prior art & related projects — several other projects bridge bioimage tools with LLMs via MCP.
This project was developed independently but shares the same problem space:
MCP server that gives LLM agents a scripting interface into a running Fiji (ImageJ2) instance
Étoiles
9
Outils
—
Disponibilité
—
fiji/fiji-llm project - Chat with AI assistants directly in Fiji to get help with image analysis, scripting, macros, and general questions.
fiji_mcp (NicoKiaru) — Fiji MCP via PyImageJ (in-process, Groovy)
Run macros and scripts in Fiji from your LLM conversation (run_ij_macro, run_script, run_command)
Inspect images — list open images, get metadata, save to disk
Visual feedback via thumbnails — get_thumbnail returns a display-ready PNG with the current LUT and overlays baked in, so the LLM can see what it's working with
Observe user actions — the plugin captures what the biologist does in Fiji's GUI (commands, image opens/closes, ROI edits) and streams it to the LLM via an event log
Export workflows — convert a recorded action sequence to a runnable ImageJ macro
Search commands — find Fiji menu commands by name
Thumbnails and visual models
This project is designed for use with vision-capable LLMs (Claude, GPT-4o, Gemini, etc.). The get_thumbnail tool is the primary way the agent sees image data — it returns a scaled PNG with the current LUT, brightness/contrast, and overlays already applied, exactly as the image appears in Fiji.
Agents should call get_thumbnail liberally: after opening an image, after each processing step, and before reporting results. This gives the model visual ground truth to catch mistakes (wrong channel, bad threshold, off-target ROI) that text-only metadata would miss. The thumbnail is file-path-based — no base64 in the protocol — so it works efficiently even for large images.
Available tools
Tool
Description
run_ij_macro
Execute ImageJ macro code
run_script
Execute a script in any supported language (Python, Groovy, JS, ...)
run_command
Run a Fiji menu command by name
list_images
List all open images
get_image_info
Get image metadata (dimensions, type, path)
get_thumbnail
Get a display-ready PNG snapshot (LUT + overlays baked in)
git clone https://github.com/SteffenPL/fiji-mcp.git
cd fiji-mcp
uv sync
2. Install the bridge plugin into Fiji
# Auto-discovers Fiji in standard locations:
uv run fiji-mcp install
# Or specify your Fiji path explicitly:
uv run fiji-mcp install --fiji-home /path/to/Fiji.app
This copies the bridge plugin JAR into your Fiji's plugins/ directory, checks the bundled Java version, and saves the Fiji path so the MCP server can find it at runtime.
3. Configure your MCP client
Add fiji-mcp to your MCP client.
Claude Code
Project scope (run from your project root):
claude mcp add --scope project fiji-mcp -- \
uv run --directory /absolute/path/to/fiji-mcp fiji-mcp
Global scope:
claude mcp add --scope user fiji-mcp -- \
uv run --directory /absolute/path/to/fiji-mcp fiji-mcp
Codex CLI / Codex app
In the Codex app, use the Show Terminal button and run the same commands below.
Use this JSON either in a project .mcp.json for Claude Code, or in Claude Desktop's config file at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
Use this block in .codex/config.toml for a project-only install, or in ~/.codex/config.toml for a global install.
To override the saved Fiji path at runtime, pass --fiji-home:
uv run --directory /absolute/path/to/fiji-mcp fiji-mcp --fiji-home /other/Fiji.app
Usage
The first tool call auto-launches Fiji if it's not already running. You can also start Fiji manually and go to Plugins > fiji-mcp > Start Bridge.
Example conversation:
You: Open the sample image "blobs.gif" and apply a Gaussian blur with sigma 2
Claude:(uses run_ij_macro with code open("http://imagej.net/images/blobs.gif"); run("Gaussian Blur...", "sigma=2");)
Configuration
Setting
Default
Description
.fiji-path file
(written by install)
Saved Fiji path — set automatically by fiji-mcp install
--fiji-home flag
—
Override saved path at runtime: fiji-mcp --fiji-home /path
FIJI_HOME env
(auto-discover)
Fallback if .fiji-path is not set
FIJI_MCP_PORT env
8765
WebSocket port (set on both Fiji and MCP server side)
Architecture
Two processes connected by WebSocket:
fiji-mcp (Python) — MCP server using fastmcp 3.x with stdio transport. Connects to Fiji as a WebSocket client. Buffers events in a 10,000-entry ring buffer.
fiji-mcp-bridge (Java) — Fiji plugin. Runs a WebSocket server inside Fiji. Executes macros/scripts, captures user actions via ImageJ listeners, and pushes events to the MCP server.
Image data is file-based only (Fiji saves to temp directory, MCP server returns file paths). No base64 encoding in the protocol.
Event capture
The plugin captures user and MCP-triggered actions across 7 categories:
Every event is tagged with "source": "user" or "source": "mcp" so the LLM can distinguish what the biologist did from what it triggered itself.
Development
# Install dev dependencies
uv sync --dev
# Run Python tests (no Fiji required)
uv run pytest -v
# Run smoke test (requires Fiji with bridge started)
uv run python tests/smoke_test.py
# Build the Java plugin from source (requires Maven + JDK 8+)
cd fiji-plugin && mvn package -q
# Copy to package data:
cp target/fiji-mcp-bridge-0.1.0.jar ../src/fiji_mcp/data/
Pas encore de liste d'outils. Les serveurs distants en obtiennent une après le premier contrôle d'état.
FAQ
Questions
Comment installer Fiji ?
Copiez sur cette page la configuration stdio pour Cursor, Claude Desktop, Claude Code ou VS Code. Elle utilise l'installation de l'éditeur, pas un proxy PlugMCP.
Fiji nécessite-t-il une clé API ?
Aucune variable d'environnement requise n'est indiquée sur cette fiche.
Quel transport Fiji utilise-t-il ?
Fiji s'exécute en local via stdio.
Quand Fiji a-t-il été vérifié pour la dernière fois ?
Dernière vérification : 2026-10-28. MCP server that gives LLM agents a scripting interface into a running Fiji (ImageJ2) instance