Complete API Reference¶
Auto-generated documentation for all 16 napari MCP server tools, extracted from source code.
Session & Viewer Controls¶
init_viewer¶
async def init_viewer(title: str | None = None, width: int | str | None = None, height: int | str | None = None, port: int | str | None = None, detect_only: bool = False) -> dict[str, Any]
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.
close_viewer¶
Close the viewer window and clear all layers.
session_information¶
Get comprehensive information about the current napari session.
Layer Management¶
list_layers¶
Return a list of layers with key properties.
get_layer¶
async def get_layer(name: str, include_data: bool = False, slicing: str | None = None, max_elements: int | str = 1000) -> dict[str, Any]
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.
add_layer¶
async def add_layer(layer_type: str, path: str | None = None, data: list | None = None, data_var: str | None = None, name: str | None = None, colormap: str | None = None, blending: str | None = None, channel_axis: int | str | None = None, size: float | str | None = None, shape_type: str | None = None, edge_color: str | None = None, face_color: str | None = None, edge_width: float | str | None = None) -> dict[str, Any]
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).
remove_layer¶
Remove a layer by name.
set_layer_properties¶
async def set_layer_properties(name: str, visible: bool | None = None, opacity: float | None = None, colormap: str | None = None, blending: str | None = None, contrast_limits: list[float] | None = None, gamma: float | str | None = None, new_name: str | None = None, active: bool | None = None) -> dict[str, Any]
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).
reorder_layer¶
async def reorder_layer(name: str, index: int | str | None = None, before: str | None = None, after: str | None = None) -> dict[str, Any]
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
apply_to_layers¶
async def apply_to_layers(filter_type: str | None = None, filter_pattern: str | None = None, properties: dict[str, Any] | None = None) -> dict[str, Any]
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).
save_layer_data¶
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").
Viewer Controls¶
configure_viewer¶
async def configure_viewer(reset_view: bool = False, center: list[float] | None = None, zoom: float | str | None = None, angles: list[float] | None = None, ndisplay: int | str | None = None, dims_axis: int | str | None = None, dims_value: int | str | None = None, grid: bool | str | None = None) -> dict[str, Any]
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.
Utilities¶
screenshot¶
async def screenshot(canvas_only: bool | str = True, save_path: str | None = None, axis: int | str | None = None, slice_range: str | None = None, interpolate_to_fit: bool = False, save_dir: str | None = None) -> ImageContent | list[ImageContent] | dict[str, Any]
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.
execute_code¶
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.
install_packages¶
async def install_packages(packages: list[str], upgrade: bool | None = False, no_deps: bool | None = False, index_url: str | None = None, extra_index_url: str | None = None, pre: bool | None = False, line_limit: int | str = 30, timeout: int = 240) -> dict[str, Any]
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.
read_output¶
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.