Skip to main content
Glama

Cellpose MCP Server

Python 3.10+ License: BSD-3-Clause PyPI

Cellpose-mcp is a Model Context Protocol (MCP) server that enables AI assistants like Claude, Cursor IDE, etc. to perform cell segmentation through natural language commands. This tool exposes comprehensive Cellpose functionality through 13+ MCP tools, including 2D/3D segmentation, batch processing, image restoration (denoising, deblurring, upsampling), and custom model training. The system integrates seamlessly with Napari, enabling complete workflows from segmentation to interactive visualization.

Cellpose-MCP Research Poster

πŸ“Œ Note: This project started as a fun project inspired by napari-mcp and adapted for Cellpose segmentation workflows. If you would like to contribute then please get in touch with me at ssahu2@ucmerced.edu.

πŸš€ Quick Start

Requirements: Python 3.10, 3.11, or 3.12 and Cellpose 3.1.1.2.

Cellpose 4 does not include the restoration API used by this server. The package pins the final Cellpose 3 release until restoration has a tested replacement.

Install from PyPI:

pip install cellpose-mcp

Install and configure for Cursor in one go:

pip install cellpose-mcp && cellpose-mcp-install cursor

The installer uses the Python that runs the command (or a conda env named Cellpose_mcp if present). Restart Cursor after configuring.

Development install (from source):

git clone https://github.com/surajinacademia/cellpose_mcp.git
cd cellpose_mcp
pip install -e .

Auto-Configure Your AI Application

After pip install cellpose-mcp, run the installer for your app. It writes to the correct MCP config file using your current Python.

Application

Command

Notes

Cursor IDE

cellpose-mcp-install cursor

Writes to ~/.cursor/mcp.json

Claude Desktop

cellpose-mcp-install claude-desktop

Adds to Claude Desktop config

Antigravity

cellpose-mcp-install antigravity

Configures Antigravity MCP

VS Code (Cline/Roo Cline)

cellpose-mcp-install vscode

Configures Cline/Roo Cline extension

Claude Code

Manual only

See Manual Configuration below

Options: --python-path /path/to/python to use a specific Python; --env-name NAME to use a conda env (default: Cellpose_mcp).

If you prefer manual setup (or use Claude Code), create a .mcp.json file in your project root. Use the full path to your Python executable if python is not the one that has cellpose-mcp installed (e.g. a venv or conda):

{
  "mcpServers": {
    "cellpose": {
      "command": "python",
      "args": ["-m", "cellpose_mcp"],
      "env": {
        "KMP_DUPLICATE_LIB_OK": "TRUE",
        "OMP_NUM_THREADS": "1"
      }
    }
  }
}

For Cursor, use the same structure in ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project.

After installation, restart your AI app and try asking:

"Can you list available Cellpose models?"
"Segment the cells in ./data/sample.tif using the cyto2 model"

🎯 What Can You Do?

Example: Cell Segmentation in Action

Basic Cell Segmentation

"Segment the cells in ./data/sample.tif using the cyto2 model"
"List available Cellpose models"
"Estimate cell diameter from ./data/image.tif"

Advanced Workflows

"Segment all TIFF files in ./data/images/ and save masks to ./output/"
"Train a custom segmentation model using images in ./train/images/ and masks in ./train/masks/"
"Restore and segment the noisy image in ./data/noisy.tif using oneclick_cyto3"

Batch Processing

"Process all images in ./data/ with the cyto2 model and save results to ./output/"

Related MCP server: cloudcompare-mcp

πŸ›  Available MCP Tools

The server exposes 13+ tools for complete Cellpose functionality:

Segmentation Tools

  • segment_cells_2d - Segment cells in 2D images

  • segment_cells_3d - Segment cells in 3D volumes

  • segment_cells_batch - Batch process multiple images

Image Restoration Tools

  • denoise_image - Denoise microscopy images

  • deblur_image - Deblur microscopy images

  • upsample_image - Upsample low-resolution images

  • restore_and_segment - Combined restoration + segmentation

Training Tools

  • train_segmentation_model - Train custom segmentation model

  • train_restoration_model - Train custom restoration model

Utility Tools

  • list_available_models - List all pretrained models

  • estimate_cell_diameter - Estimate cell diameter from image

  • save_masks - Save masks in various formats

  • load_image_info - Get image metadata

πŸ“– Documentation

πŸ“‹ Architecture

  • FastMCP Server: Handles MCP protocol communication

  • Cellpose Integration: Manages model loading and segmentation operations

  • Tool Layer: Exposes Cellpose functionality as MCP tools

  • File I/O: Handles image reading, writing, and mask generation

Key features:

  • Thread-safe: All operations are properly serialized

  • Non-blocking: Async operations for better performance

  • Napari Integration: Integration with Napari for visualization and analysis

Author: Suraj Sahu
Affiliation: Department of Physics, University of California Merced, CA, USA
Email: ssahu2@ucmerced.edu

πŸ“„ License

BSD-3-Clause License - see LICENSE file for details.

πŸ™ Acknowledgments


Available Tools

12 tools
deblur_imageB

Deblur a microscopy image using Cellpose restoration models.

Args: image_path: Path to input image model_type: Restoration model type (deblur_cyto2, deblur_cyto3, etc.) channels: Channel specification diameter: Expected object diameter for scaling gpu: Whether to use GPU acceleration output_path: Optional path to save deblurred image

Returns

Dictionary with deblurring results

Inputs: image_path (required), gpu, channels, diameter, +2 more. Returns: object

denoise_imageA

Denoise a microscopy image using Cellpose restoration models.

Args: image_path: Path to input image model_type: Restoration model type (denoise_cyto2, denoise_cyto3, etc.) channels: Channel specification diameter: Expected object diameter for scaling gpu: Whether to use GPU acceleration output_path: Optional path to save denoised image

Returns

Dictionary with denoising results

Inputs: image_path (required), gpu, channels, diameter, +2 more. Returns: object

estimate_cell_diameterC

Estimate cell diameter from an image using Cellpose size model.

Args: image_path: Path to input image model_type: Model type to use for estimation channels: Channel specification gpu: Whether to use GPU acceleration

Returns

Dictionary with estimated diameter and confidence

Inputs: image_path (required), gpu, channels, model_type. Returns: object

list_available_modelsA

List all available pretrained Cellpose models.

Returns

Dictionary with lists of available models by category

Inputs: no named parameters. Returns: object

load_image_infoB

Get information about an image file.

Args: image_path: Path to image file

Returns

Dictionary with image metadata (shape, dtype, channels, dimensions)

Inputs: image_path (required). Returns: object

restore_and_segmentC

Restore (denoise/deblur) and segment an image in one pipeline.

Args: image_path: Path to input image restoration_model: Restoration model type (oneclick_cyto3, etc.) segmentation_model: Segmentation model type (cyto3, etc.) diameter: Expected cell diameter in pixels channels: Channel specification gpu: Whether to use GPU acceleration output_path_mask: Optional path to save masks output_path_restored: Optional path to save restored image

Returns

Dictionary with combined restoration and segmentation results

Inputs: image_path (required), gpu, channels, diameter, +4 more. Returns: object

save_masksA

Save masks plus outlines and overlay visualizations.

Always writes three outputs: (1) masks in the chosen format, (2) outlines as a binary PNG, (3) overlay PNG (colored masks on image or black).

Args: mask_path: Path to existing mask file output_format: Output format for masks (tif, png, npy) output_path: Optional custom output path for the masks file image_path: Optional path to original image; if provided, overlay is drawn on it save_flows: Reserved for future use (flow fields not saved)

Returns

Dictionary with mask_path, outlines_path, overlay_path, and files_created

Inputs: mask_path (required), image_path, save_flows, output_path, +1 more. Returns: object

segment_cells_2dA

Segment cells in a 2D microscopy image using Cellpose.

Args: image_path: Path to input image file (TIFF, PNG, etc.) model_type: Cellpose model type (cyto, cyto2, cyto3, nuclei, etc.) diameter: Expected cell diameter in pixels (0 = model default) channels: Channel specification [cyto, nuclei] or None for grayscale flow_threshold: Flow error threshold (lower = more masks, may be worse quality) cellprob_threshold: Cell probability threshold (higher = fewer masks) min_size: Minimum cell size in pixels gpu: Whether to use GPU acceleration augment: Use test-time augmentation (flip/rotate) normalize: Normalize image intensities invert: Invert image intensities (for bright background) output_path: Optional path to save masks (default: image_path with _masks suffix)

Returns

Dictionary with segmentation results including cells_detected, output_path, diameter, mask_shape

Inputs: image_path (required), gpu, invert, augment, +8 more. Returns: object

segment_cells_3dB

Segment cells in a 3D volume using Cellpose.

Args: image_path: Path to input 3D image stack (TIFF, etc.) model_type: Cellpose model type diameter: Expected cell diameter in pixels do_3d: Use full 3D segmentation (True) or slice + stitch (False) anisotropy: Z-axis anisotropy factor (z_pixel_size / xy_pixel_size) stitch_threshold: Threshold for stitching masks across slices (if do_3d=False) flow3d_smooth: Smoothing factor for 3D flows channels: Channel specification [cyto, nuclei] or None gpu: Whether to use GPU acceleration output_path: Optional path to save masks

Returns

Dictionary with 3D segmentation results

Inputs: image_path (required), gpu, do_3d, channels, +6 more. Returns: object

segment_cells_batchB

Segment cells in multiple images in batch.

Args: image_paths: List of paths to input images model_type: Cellpose model type diameter: Expected cell diameter in pixels output_dir: Directory to save masks (default: same as input images) gpu: Whether to use GPU acceleration batch_size: Number of images to process in parallel

Returns

Dictionary with batch processing results

Inputs: image_paths (required), gpu, diameter, batch_size, +2 more. Returns: object

train_segmentation_modelA

Train a custom Cellpose segmentation model.

Args: train_dir: Directory containing training images train_labels_dir: Directory containing training masks/labels model_name: Name for the trained model model_type: Base model type (cyto, nuclei, etc.) n_epochs: Number of training epochs learning_rate: Learning rate for training batch_size: Batch size for training test_dir: Optional directory with test images test_labels_dir: Optional directory with test labels gpu: Whether to use GPU acceleration output_dir: Directory to save trained model (default: current directory)

Returns

Dictionary with training results

Inputs: train_dir (required), model_name (required), train_labels_dir (required), gpu, +7 more. Returns: object

upsample_imageB

Upsample a microscopy image using Cellpose restoration models.

Args: image_path: Path to input image model_type: Upsampling model type (upsample_cyto2, upsample_cyto3, etc.) scale_factor: Upsampling factor (typically 2 or 4) channels: Channel specification gpu: Whether to use GPU acceleration output_path: Optional path to save upsampled image

Returns

Dictionary with upsampling results

Inputs: image_path (required), gpu, channels, model_type, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct operation: 2D/3D/batch segmentation are clearly separated by dimension and scope, restoration tools (denoise, deblur, upsample) use distinct model types, and utilities like save_masks and load_image_info are independent. There is no overlapping purpose that would cause an agent to misselect.

    Naming Consistency5/5

    All tool names follow consistent snake_case with a verb_noun pattern (segment_cells_2d, denoise_image, train_segmentation_model, etc.). Naming is uniform and predictable, with clear singular verbs and no mixing of conventions.

    Tool Count5/5

    12 tools is a well-scoped set for a cell analysis server, covering segmentation, restoration, training, model listing, estimation, and utility functions. Each tool serves a clear purpose and the count is within the ideal 3-15 range.

    Completeness3/5

    The surface covers core workflows (segment, restore, train, estimate, save, inspect), but there is a notable gap: after training a custom model, there is no tool to apply that model for segmentationβ€”the segmentation tools only accept pretrained model types. This creates a dead-end in the lifecycle and limits practical use.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers