Napari MCP Server
Allows OpenAI LLMs (e.g., GPT-4) to remotely control napari viewers for microscopy image analysis.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Napari MCP Server Load image from data/sample.tif and apply viridis colormap"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Napari MCP Server
MCP server for remote control of napari viewers via Model Context Protocol (MCP). Perfect for AI-assisted microscopy analysis with Claude Desktop and other LLM applications.
https://github.com/user-attachments/assets/d261674c-9875-4671-8c60-a7f49d6f1b84
๐ Quick Start (3 Steps)
1. Install the Package
pip install napari-mcp2. Auto-Configure Your AI Application
# For Claude Desktop
napari-mcp-install install claude-desktop
# Include a napari GUI backend in the uv environment
napari-mcp-install install claude-desktop --backend pyqt6
# For other applications (Claude Code, Cursor, Cline, etc.)
napari-mcp-install install --help # See all options3. Restart Your Application & Start Using
Restart your AI app and you're ready! Try asking:
"Can you call session_information() to show my napari session details?"โ See Full Documentation for detailed guides
Related MCP server: Gemini MCP Server
๐ Using as a napari Plugin
napari-mcp can also be used as a napari plugin for direct integration with a running napari session:
Start napari normally:
napariOpen the widget: Plugins โ napari-mcp: MCP Server Control
Click "Start Server" to expose your current session to AI assistants
Connect your AI app using the standard installer:
napari-mcp-install install <app>
This mode enables AI assistants to control your current napari session rather than starting a new viewer. Perfect for integrating with existing workflows!
โ See Plugin Guide for detailed instructions
๐ฏ What Can You Do?
Basic Image Analysis
"Load the image from ./data/sample.tif and apply a viridis colormap"
"Create point annotations at coordinates [[100,100], [200,200]]"
"Take a screenshot and save it"Advanced Workflows
"Execute this code to create a filtered version:
from scipy import ndimage
filtered = ndimage.gaussian_filter(viewer.layers[0].data, sigma=2)
viewer.add_image(filtered, name='filtered')"
"Install scikit-image and segment the cells in this microscopy image"3D/4D Navigation
"Switch to 3D display mode"
"Navigate to time point 5, Z-slice 10"
"Create a rotating animation of this volume"Automated Workflows
Want to automate image processing with Python scripts? Use any LLM (OpenAI, Anthropic, etc.) with napari MCP:
โ See Python Integration Examples for batch processing and workflow automation
๐ค Supported AI Applications
Application | Command | Status |
Claude Desktop |
| โ Full Support |
Claude Code |
| โ Full Support |
Cursor IDE |
| โ Full Support |
Cline (VS Code) |
| โ Full Support |
Cline (Cursor) |
| โ Full Support |
Gemini CLI |
| โ Full Support |
Codex CLI |
| โ Full Support |
โ See Integration Guides for application-specific instructions
๐ Available MCP Tools
The server exposes 16 tools for complete napari control:
Core Functions
Session Management:
init_viewer,close_viewer,session_informationLayer Operations:
add_layer,list_layers,get_layer,remove_layer,set_layer_properties,reorder_layer,apply_to_layers,save_layer_dataViewer Controls:
configure_viewerUtilities:
screenshot,execute_code,install_packages,read_output
โ ๏ธ Security Notice
!!! warning "Code Execution Capabilities" This server includes powerful tools that allow arbitrary code execution:
- **`execute_code()`** - Runs Python code in the server environment
- **`install_packages()`** - Installs packages via pip
The bridge server binds to `127.0.0.1` (localhost only) with no authentication.
Any local process can invoke these tools.
**Use only with trusted AI assistants on local networks.**
Never expose to public internet without proper sandboxing.๐ Documentation
Quick Start Guide - Get running in 3 minutes
Installation Options - Advanced installation methods
Integration Guides - Setup for specific AI applications
Python Examples - Automate workflows with custom scripts
Troubleshooting - Common issues and solutions
API Reference - Complete tool documentation
๐งช Development Setup
# Clone repository
git clone https://github.com/royerlab/napari-mcp.git
cd napari-mcp
# Install with development dependencies
pip install -e ".[dev]"
# Run tests
pytest -m "not realgui" # Skip GUI tests
pytest --cov=src --cov-report=html # With coverage๐ค Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature)Make your changes with tests
Run pre-commit hooks:
pre-commit run --all-filesCommit changes (
git commit -m 'Add amazing feature')Push to branch (
git push origin feature/amazing-feature)Open a Pull Request
๐ Architecture
state.pyโServerStateholding all mutable state (viewer, locks, execution namespace)server.pyโcreate_server(state)factory; tools defined as closures over stateqt_helpers.pyโ Qt application and viewer lifecycle managementoutput.pyโ Output truncation utilitybridge_server.pyโ Plugin bridge server (overrides 3 tools for Qt thread safety)viewer_protocol.pyโViewerProtocolfor typed viewer backendscli/โnapari-mcp-installCLI for configuring AI applications
Key features:
Thread-safe: All napari operations are serialized
Non-blocking: Qt event loop runs asynchronously
Stateful: Maintains viewer state across tool calls
Extensible: Easy to add new tools
๐ Resources
napari - Multi-dimensional image viewer
Model Context Protocol - MCP specification
FastMCP - Python MCP framework
Claude Desktop - AI assistant with MCP support
๐ License
BSD-3-Clause License - see LICENSE file for details.
๐ Acknowledgments
napari team for the excellent imaging platform
FastMCP for the MCP framework
Anthropic for Claude and MCP development
astral-sh for uv dependency management
Built with โค๏ธ for the microscopy and AI communities
Available Tools
16 toolsadd_layerA
Add a layer to the viewer.
Parameters
layer_type : str
One of: "image", "labels", "points", "shapes",
"vectors", "tracks", "surface".
path : str, optional
File path (for image/labels).
data : list, optional
Inline data (coordinates, shape vertices, etc.).
data_var : str, optional
Name of a variable in the execute_code namespace.
name : str, optional
Layer name. Defaults to variable name or filename.
colormap : str, optional
Colormap name (image only).
blending : str, optional
Blending mode (image only).
channel_axis : int, optional
Channel axis (image only).
size : float, optional
Point size in pixels (points only, default 10).
shape_type : str, optional
Shape type: "rectangle", "ellipse", "line", "path", "polygon"
(shapes only, default "rectangle").
edge_color : str, optional
Edge color (shapes/vectors only).
face_color : str, optional
Face color (shapes only).
edge_width : float, optional
Edge width in pixels (shapes/vectors only).
Inputs: layer_type (required), path, data, data_var, +9 more. Returns: object
apply_to_layersA
Apply property changes to multiple layers matching a filter.
Parameters
filter_type : str, optional
Layer type name to match (e.g., "Image", "Labels", "Points").
filter_pattern : str, optional
Glob pattern matched against layer names (e.g., "seg_*").
properties : dict, optional
Properties to set on matched layers. Supported keys: visible,
opacity, colormap, blending, contrast_limits,
gamma, new_name (renames by appending a suffix is NOT
supported โ use set_layer_properties individually).
Inputs: filter_type, filter_pattern, properties. Returns: object
close_viewerA
Close the viewer window and clear all layers.
Inputs: no named parameters. Returns: object
configure_viewerA
Configure viewer display: camera, dimensions, and grid.
All parameters are optional โ set any combination in one call.
Parameters
reset_view : bool, default False
If True, reset the camera to fit all data.
center : list[float], optional
Camera center position.
zoom : float, optional
Camera zoom factor (must be > 0).
angles : list[float], optional
Camera angles as [azimuth, elevation, roll] in degrees.
ndisplay : int, optional
Number of displayed dimensions (2 or 3).
dims_axis : int, optional
Axis index for slider position (use with dims_value).
dims_value : int, optional
Step value for the given axis.
grid : bool, optional
Enable or disable grid view.
Inputs: reset_view, center, zoom, angles, +4 more. Returns: object
execute_codeA
Execute arbitrary Python code in the server's interpreter.
Similar to napari's console. The execution namespace persists across calls and includes 'viewer', 'napari', and 'np'.
Parameters
code : str Python code string. The value of the last expression (if any) is returned as 'result_repr'. line_limit : int, default=30 Maximum number of output lines to return. Use -1 for unlimited output. Warning: Using -1 may consume a large number of tokens.
Note
In standalone mode, code execution runs synchronously on the main thread (required for Qt/napari operations) and has no timeout. In bridge mode, a 600-second timeout is enforced.
Inputs: code (required), line_limit. Returns: object
get_layerA
Get detailed info about a layer, optionally including data.
Always returns metadata (shape, dtype, scale, translate, type-specific
properties). When include_data=True or slicing is provided,
also returns statistics and/or raw data values.
Parameters
name : str
Layer name (exact match).
include_data : bool, default False
If True, include data statistics (min/max/mean/std) and, for
small layers, inline data values.
slicing : str, optional
Numpy-style index string, e.g. "0, :5, :5". Implies
include_data=True.
max_elements : int, default 1000
Maximum number of data elements to return inline. Larger data
is stored and an output_id returned for read_output.
Inputs: name (required), include_data, slicing, max_elements. Returns: object
init_viewerA
Create or return the napari viewer, with viewer detection.
When detect_only=True, reports available viewers (local and
external) without creating or modifying anything.
Parameters
title : str, optional Optional window title (only for local viewer). width : int, optional Optional initial canvas width (only for local viewer). height : int, optional Optional initial canvas height (only for local viewer). port : int, optional If provided, attempt to connect to an external napari-mcp bridge on this port (default is taken from NAPARI_MCP_BRIDGE_PORT or 9999). detect_only : bool, default=False If True, only detect available viewers without initialising.
Inputs: title, width, height, port, +1 more. Returns: object
install_packagesA
Install Python packages using pip.
Parameters
packages : list of str List of package specifiers (e.g., "scikit-image", "torch==2.3.1"). upgrade : bool, optional If True, pass --upgrade flag. no_deps : bool, optional If True, pass --no-deps flag. index_url : str, optional Custom index URL. extra_index_url : str, optional Extra index URL. pre : bool, optional Allow pre-releases (--pre flag). line_limit : int, default=30 Maximum number of output lines to return. Use -1 for unlimited output. timeout : int, default=240 Timeout for pip install in seconds.
Inputs: packages (required), upgrade, no_deps, index_url, +4 more. Returns: object
list_layersC
Return a list of layers with key properties.
Inputs: no named parameters. Returns: result
read_outputA
Read stored tool output with optional line range.
Parameters
output_id : str Unique ID of the stored output. start : int, default=0 Starting line number (0-indexed). end : int, default=-1 Ending line number (exclusive). If -1, read to end.
Inputs: output_id (required), start, end. Returns: object
remove_layerC
Remove a layer by name.
Inputs: name (required). Returns: object
reorder_layerA
Reorder a layer by name.
Provide exactly one of:
index: absolute target index
before: move before this layer name
after: move after this layer name
Inputs: name (required), index, before, after. Returns: object
save_layer_dataA
Save a layer's data to a file.
Parameters
name : str
Layer name.
path : str
Output file path. Format is inferred from extension unless
format is specified. Supported: .tiff, .png,
.npy, .csv (points/tabular only).
format : str, optional
Explicit format override (e.g., "npy", "tiff").
Inputs: name (required), path (required), format. Returns: object
screenshotA
Take a screenshot, or a timelapse series by sweeping a dims axis.
For a single screenshot, call with no axis/slice_range.
For a timelapse, provide both axis and slice_range.
Parameters
canvas_only : bool, default True
If True, only capture the canvas area.
save_path : str, optional
Save single screenshot to this file path (returns metadata).
axis : int, optional
Dims axis to sweep for timelapse (e.g., temporal axis).
slice_range : str, optional
Python-like slice string, e.g. "1:5", ":6", "::2".
Required when axis is provided.
interpolate_to_fit : bool, default False
If True, downsample timelapse frames to fit ~1.3 MB total.
save_dir : str, optional
Save timelapse frames as frame_NNNN.png in this directory.
Inputs: canvas_only, save_path, axis, slice_range, +2 more. Returns: result
session_informationA
Get comprehensive information about the current napari session.
Inputs: no named parameters. Returns: object
set_layer_propertiesA
Set properties on a layer by name.
Parameters
name : str Layer name (exact match). visible, opacity, colormap, blending, contrast_limits, gamma Standard layer rendering properties. new_name : str, optional Rename the layer. active : bool, optional If True, make this the selected/active layer. Setting to False has no effect (use viewer selection directly).
Inputs: name (required), visible, opacity, colormap, +5 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 16 tools
Each tool targets a distinct operation or query. Add/remove/reorder layers are clearly separate; set_layer_properties and apply_to_layers differ in scope; execute_code and read_output serve different purposes. No overlapping tools.
All tools use consistent snake_case with a verb_noun pattern (e.g., add_layer, list_layers, close_viewer). No mixed conventions or irregular naming.
16 tools is well-scoped for the napari viewer domain. Each tool serves a clear purpose without redundancy or unnecessary sprawl.
Core workflows (viewer lifecycle, layer manipulation, data I/O, code execution) are covered. Minor gaps exist, such as no dedicated file import for non-image layers, but these can be addressed via execute_code.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yoโฆ
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that integrates InvokeAI with Claude Code, enabling AI-powered image generation, transformation, and upscaling directly from your AI assistant.30 PyPI5MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that connects Claude Desktop to Google Gemini, enabling multimodal analysis with file attachments (video, image, audio, PDF).509 npmMIT
- AlicenseNot gradedqualityDmaintenanceA powerful MCP server that brings AI vision capabilities to Claude Desktop. Analyze images and videos using OpenAI GPT-4o, Claude, or any compatible vision API.27 npmMIT
- FlicenseNot gradedqualityBmaintenanceMCP server that enables LLMs to create and control interactive MapLibre maps by placing markers, drawing paths, and rendering polygons directly in Claude Desktop.1-