Skip to content

installation.md

Latest commit

 

History

History
418 lines (297 loc) · 9.28 KB

installation.md

File metadata and controls

418 lines (297 loc) · 9.28 KB
Raw

Advanced Installation

Advanced installation options for napari MCP server including manual configuration, development setup, and zero-install approaches.

!!! tip "Quick Setup Available" Most users should use the Quick Start Guide with the automated CLI installer. This guide is for advanced users who need manual configuration or development setups.

CLI Installer (Recommended)

The easiest way is using the automated installer:

pip install napari-mcp
napari-mcp-install install <application>

→ See Quick Start for step-by-step instructions

Manual Configuration

For users who prefer manual setup or need custom configurations.

Configuration File Locations

The CLI installer auto-detects these locations. For manual setup, you need to know where each application stores its MCP config:

Claude Desktop

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Claude Code

  • All platforms: ~/.claude.json

Cursor

  • Global: ~/.cursor/mcp.json
  • Project: .cursor/mcp.json (in project root)

Cline (VS Code)

  • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Windows: %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Note: For VS Code Insiders, replace "Code" with "Code - Insiders"

Cline (Cursor)

  • macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Windows: %APPDATA%/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Gemini CLI

  • Global: ~/.gemini/settings.json
  • Project: .gemini/settings.json (in project root)

Codex CLI

  • All platforms: ~/.codex/config.toml (TOML format)

Standard Configuration (JSON)

Most applications use this JSON format:

{
  "mcpServers": {
    "napari-mcp": {
      "command": "uv",
      "args": ["run", "--with", "napari-mcp", "napari-mcp"]
    }
  }
}

This uses uv for zero-install execution (no permanent installation required).

Using Persistent Python Environment

If you have napari-mcp installed in your Python environment:

{
  "mcpServers": {
    "napari-mcp": {
      "command": "python",
      "args": ["-m", "napari_mcp.server"]
    }
  }
}

Or with a specific Python path:

{
  "mcpServers": {
    "napari-mcp": {
      "command": "/path/to/your/python",
      "args": ["-m", "napari_mcp.server"]
    }
  }
}

Application-Specific Configuration

Gemini CLI (Extended)

{
  "mcpServers": {
    "napari-mcp": {
      "command": "uv",
      "args": ["run", "--with", "napari-mcp", "napari-mcp"],
      "cwd": ".",
      "timeout": 600000,
      "trust": false
    }
  }
}

Cline (Tool Permissions)

{
  "mcpServers": {
    "napari-mcp": {
      "command": "uv",
      "args": ["run", "--with", "napari-mcp", "napari-mcp"],
      "alwaysAllow": ["screenshot", "list_layers"],
      "disabled": false
    }
  }
}

Codex CLI (TOML Format)

[mcp_servers.napari_mcp]
command = "uv"
args = ["run", "--with", "napari-mcp", "napari-mcp"]

Zero Install with uv

Run napari MCP without permanent installation using uv:

# Direct execution (for testing)
uv run --with napari-mcp napari-mcp

# Add a napari GUI backend when needed
uv run --with napari-mcp --with napari[pyqt6] napari-mcp

The configuration files use uv automatically. You can also ask napari-mcp-install to include a backend with --backend all, --backend pyqt5, --backend pyqt6, --backend pyside, --backend none, or a custom value. See Zero Install Guide for details.

Development Installation

For contributors and plugin developers:

Clone and Install

# Clone repository
git clone https://github.com/royerlab/napari-mcp.git
cd napari-mcp

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Or with uv (recommended)
uv pip install -e ".[dev]"

Configure for Development

# Configure to use your development installation
napari-mcp-install install claude-desktop --persistent

# This will use your local Python with the editable installation

Run Tests

# Fast tests (skip GUI)
pytest -m "not realgui"

# With coverage
pytest --cov=src --cov-report=html -m "not realgui"

# Include GUI tests (requires display)
pytest -m realgui

Development Tools

# Install pre-commit hooks
pre-commit install

# Run linting
ruff check src/ tests/

# Format code
ruff format src/ tests/

Virtual Environment Setup

Using venv

# Create environment
python -m venv napari-mcp-env

# Activate (macOS/Linux)
source napari-mcp-env/bin/activate

# Activate (Windows)
napari-mcp-env\Scripts\activate

# Install
pip install napari-mcp

# Configure
napari-mcp-install install <app> --persistent

Using conda

# Create environment
conda create -n napari-mcp python=3.11

# Activate
conda activate napari-mcp

# Install
pip install napari-mcp

# Configure
napari-mcp-install install <app> --persistent

🔌 Plugin Mode: Direct napari Integration

napari-mcp can also be used as a napari plugin for direct integration with a running napari session.

!!! tip "When to Use Plugin Mode" - Working with existing napari workflows and loaded data - Want to switch between manual and AI-assisted analysis - Integrating with other napari plugins

Quick Setup

  1. Start napari (with or without data):

    napari
# Or: napari path/to/image.tif

  2. Open the MCP Server Control widget:

    • In napari: Plugins → napari-mcp: MCP Server Control

  3. Start the bridge server:

    • Click "Start Server" button (default port: 9999)
    • The widget shows connection URL: http://localhost:9999/mcp

  4. Configure your AI app:

    napari-mcp-install install <app>

    The installer auto-configures to detect your bridge server.

  5. Test the connection:

    • Restart your AI app
    • Ask: "Can you list the layers in my current napari session?"

How It Works

  • Standalone Mode (default): MCP server creates its own napari viewer
  • Plugin Mode: MCP bridge server connects to your current napari session

Plugin mode enables AI assistants to control your active napari instance rather than starting a new viewer.

→ See Complete Plugin Guide for detailed instructions, use cases, and troubleshooting

Environment Variables

Advanced configuration via environment variables:

# Qt platform (for headless systems)
export QT_QPA_PLATFORM=offscreen

# MCP bridge port (for external viewer)
export NAPARI_MCP_BRIDGE_PORT=9999

# Output limits
export NAPARI_MCP_MAX_OUTPUT_ITEMS=2000

# Logging
export MCP_LOG_LEVEL=INFO

Add to your config:

{
  "mcpServers": {
    "napari-mcp": {
      "command": "uv",
      "args": ["run", "--with", "napari-mcp", "napari-mcp"],
      "env": {
        "QT_QPA_PLATFORM": "offscreen",
        "NAPARI_MCP_BRIDGE_PORT": "9999"
      }
    }
  }
}

Platform-Specific Notes

macOS

  • Permissions: Grant terminal access in System Preferences
  • Python path: Use which python3 to find interpreter
  • M1/M2: Ensure native ARM Python for best performance

Windows

  • Path format: Use forward slashes in JSON: "C:/Python/python.exe"
  • Environment variables: Access with %VAR% syntax
  • PowerShell: May need execution policy changes

Linux

  • Display: X11 or Wayland required for GUI (or use offscreen mode)
  • Permissions: Ensure config directories are writable
  • Headless: Use QT_QPA_PLATFORM=offscreen for servers

Troubleshooting

Common installation issues and solutions:

Command Not Found

# Verify installation
pip list | grep napari-mcp

# Check PATH
which napari-mcp-install

# Reinstall
pip install --force-reinstall napari-mcp

Configuration Not Applied

# Verify config created
napari-mcp-install list

# Check file syntax
python -m json.tool < config-file.json

# Force reinstall
napari-mcp-install install <app> --force

Python Environment Issues

# Check Python version
python --version  # Should be 3.10+

# Verify napari-mcp is accessible
python -c "import napari_mcp; print('OK')"

# Use specific Python
napari-mcp-install install <app> --python-path $(which python)

→ See Troubleshooting Guide for comprehensive help

Next Steps

For most users, the Quick Start Guide with automated CLI installer is the recommended approach!