Napari Installation & Setup

To prevent dependency conflicts with other tools (like PyMOL), Napari and the napari-mcp plugin must be installed in a strictly isolated virtual environment.

Install Napari and the MCP Plugin in an Isolated Environment

First, create a dedicated virtual environment. To ensure your local plugin is installed in this isolated setup—and to completely bypass your global system Python—you must use the specific pip executable that belongs to your virtual environment.

# 1. Create the virtual environment
python -m venv C:\Users\<user>\.napari-env

# 2. Install Napari using the environment's specific pip
C:\Users\<user>\.napari-env\Scripts\pip install "napari[all]"

# 3. Navigate to your napari-mcp repository root
cd path\to\napari-mcp

# 4. Install the plugin in editable mode using the environment's pip
C:\Users\<user>\.napari-env\Scripts\pip install -e .

# 1. Create the virtual environment
python3 -m venv ~/.napari-env

# 2. Install Napari using the environment's specific pip
~/.napari-env/bin/pip install "napari[all]"

# 3. Navigate to your napari-mcp repository root
cd path/to/napari-mcp

# 4. Install the plugin in editable mode using the environment's pip
~/.napari-env/bin/pip install -e .

# 1. Create the virtual environment
python3 -m venv ~/.napari-env

# 2. Install Napari using the environment's specific pip
~/.napari-env/bin/pip install "napari[all]"

# 3. Navigate to your napari-mcp repository root
cd path/to/napari-mcp

# 4. Install the plugin in editable mode using the environment's pip
~/.napari-env/bin/pip install -e .

Why This Installation Method Works

• The Absolute Path: By providing the absolute path to the virtual environment's pip (e.g., ~/.napari-env/bin/pip), you force that specific Python environment to execute the installation. It automatically places the plugin registration inside the environment's site-packages, right next to Napari itself.
• The Editable Flag (-e): Instead of copying the source code, this flag creates a symlink straight back to your source directory. Because Napari reads the code directly from your folder in real-time, any changes you make to the plugin's source code are instantly reflected the next time you restart Napari.
• The Dot (.): This tells pip to look for the package configuration files (like pyproject.toml) in your current directory.

Configuring the Napari Command

To run Napari globally without breaking your environments, we will route the command through a local user directory or symbolic link.

mkdir C:\Users\<user>\MyCommands

@echo off
"C:\Users\<user>\.napari-env\Scripts\napari.exe" %*

mkdir -p ~/.local/bin
ln -s ~/.napari-env/bin/napari ~/.local/bin/napari

mkdir -p ~/.local/bin
ln -s ~/.napari-env/bin/napari ~/.local/bin/napari

Verification

Open a new terminal or command prompt session and verify the setup by triggering Napari's info command:

napari --info

(If successful, your terminal will print the Napari environment details and napari-mcp should appear in the Plugins list. This confirms discovery without requiring you to manually activate the virtual environment first.)

Connect to Claude Code

To start the napari-mcp JSON-over-TCP server and connect, you only need to run the following command. This will launch Napari, automatically dock the MCP Server widget, and immediately begin listening for Claude Code commands:

napari -w napari-mcp 'MCP Server'

Note: The plugin will listen on port 9877 by default. This port is configurable directly inside _widget.py, or you can change it on the fly by editing the widget's spinbox in Napari, clicking Stop Listening, and then Start Listening again.