Troubleshooting

Common issues and solutions when using napari MCP server with AI assistants.

🛠️ CLI Installer Issues

The napari-mcp-install CLI tool automates configuration. Here are common issues and solutions.

Installation Problems

napari-mcp-install: command not found

Problem: The CLI installer command isn't available after installation.

Solutions:

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

# Verify installation
pip list | grep napari-mcp

# Check if it's in your PATH
which napari-mcp-install

# Try running with python -m
python -m napari_mcp.cli.main --help

ImportError when running installer

Problem: Missing dependencies (typer, rich).

Solution:

# Reinstall with all dependencies
pip install --upgrade napari-mcp

# Or install dependencies manually
pip install typer rich

Configuration Issues

Configuration file not created

Problem: Installer runs but config file doesn't exist.

Solutions: 1. Check what would be created:

napari-mcp-install <app> --dry-run

1. Verify installer detected correct path:

   napari-mcp-install list
   

2. Check permissions:

   # macOS - Claude Desktop example
   ls -la ~/Library/Application\ Support/Claude/
   
   # Fix if needed
   chmod 755 ~/Library/Application\ Support/Claude/
   

3. Create directory manually:

   # macOS - Claude Desktop
   mkdir -p ~/Library/Application\ Support/Claude
   
   # Linux - Claude Desktop
   mkdir -p ~/.config/Claude
   
   # Then retry
   napari-mcp-install claude-desktop
   

Config exists but server not configured

Problem: Config file exists but napari-mcp entry is missing.

Solution:

# Check current status
napari-mcp-install list

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

# Or manually check/edit config
cat ~/.config/Claude/claude_desktop_config.json

Permission Errors

Permission denied writing config

Problem: Can't write to configuration file.

Solutions:

# Check file permissions
napari-mcp-install list  # Shows config paths

# Fix permissions (macOS/Linux)
chmod 644 <config-file-path>

# Check directory permissions
ls -la <directory-path>
chmod 755 <directory-path>

Python Environment Issues

napari-mcp not found in Python environment

Problem: Using --persistent but napari-mcp isn't installed in that environment.

Solutions:

# Check which Python
which python

# Install in current environment
pip install napari-mcp

# Then configure
napari-mcp-install <app> --persistent

# Or specify exact Python path
napari-mcp-install <app> --python-path /full/path/to/python

Verification Commands

# List all installations and their status
napari-mcp-install list

# Preview what would be installed
napari-mcp-install <app> --dry-run

# Check installer version
napari-mcp-install --version

# Get help
napari-mcp-install --help
napari-mcp-install <command> --help

---

🚨 Common Setup Issues

Server Won't Start

uv: command not found

Problem: The uv command isn't found when trying to run the server.

Solution:

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Restart terminal or reload shell
source ~/.bashrc  # or ~/.zshrc

napari-mcp: command not found

Problem: Traditional installation command not found.

Solutions:

# Reinstall in development mode
pip install -e . --force-reinstall

# Or use Python module directly
python -m napari_mcp_server

# Check if it's in your PATH
which napari-mcp

Permission denied

Problem: File permission errors when running downloaded script.

Solution:

# Make file executable
chmod +x napari_mcp_server.py

# Or run with Python directly
python napari_mcp_server.py

Napari GUI Issues

Qt platform plugin not found

Problem: qt.qpa.plugin: Could not find the Qt platform plugin

Solutions:

# For headless/remote systems
export QT_QPA_PLATFORM=offscreen

# For Linux with X11
export QT_QPA_PLATFORM=xcb

# For debugging
export QT_DEBUG_PLUGINS=1

Napari window doesn't appear

Problem: Server starts but no napari window shows.

Diagnosis:

# Check display connection (Linux/macOS)
echo $DISPLAY

# Test basic Qt
python -c "from PyQt6.QtWidgets import QApplication; app = QApplication([]); print('Qt works')"

# Test napari
python -c "import napari; viewer = napari.Viewer(); print('Napari works')"

Solutions: - Remote systems: Enable X11 forwarding or use offscreen mode - macOS: Check System Preferences > Security & Privacy - Windows: Ensure graphics drivers are updated

Import errors with napari

Problem: ImportError: No module named 'napari'

Solution:

# Check napari installation
pip list | grep napari

# Reinstall napari
pip install --upgrade napari[all]

# Or with uv
uv pip install napari[all]

🔌 AI Assistant Connection Issues

Claude Desktop

Claude can't see napari tools

Problem: MCP tools don't appear in Claude Desktop.

Checklist: 1. Config file location correct? - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%/Claude/claude_desktop_config.json - Linux: ~/.config/Claude/claude_desktop_config.json

1. JSON syntax valid?

   # Validate JSON
   cat claude_desktop_config.json | python -m json.tool
   

2. File paths absolute?

   // Wrong - relative path
   "args": ["fastmcp", "run", "napari_mcp_server.py"]
   
   // Correct - absolute path
   "args": ["fastmcp", "run", "/full/path/to/napari_mcp_server.py"]
   

3. Claude Desktop restarted?

4. Completely quit and restart Claude Desktop
5. Check for error messages in console

MCP server connection failed

Problem: Claude shows connection errors.

Debug steps:

# Test server starts manually
uv run --with fastmcp fastmcp run napari_mcp_server.py

# Check for error messages
# Look for FastMCP startup banner

# Test MCP protocol
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}' | \
  uv run --with fastmcp fastmcp run napari_mcp_server.py

Cursor & Claude Code

FastMCP CLI installation failed

Problem: fastmcp install command fails.

Solutions:

# Update fastmcp
pip install --upgrade fastmcp

# Check installation
fastmcp --version

# Manual installation
fastmcp install cursor napari_mcp_server.py --with napari --with imageio

Server not appearing in IDE

Problem: Installed server doesn't show up in Cursor/Claude Code.

Debug:

# Check installation location
fastmcp list

# Reinstall for specific IDE
fastmcp uninstall cursor napari
fastmcp install cursor napari_mcp_server.py --with napari

📦 Dependency Issues

Package Installation Problems

Package conflicts

Problem: Version conflicts between dependencies.

Solution:

# Use virtual environment
python -m venv fresh-env
source fresh-env/bin/activate
pip install -e .

# Or specify versions
uv run --with "napari>=0.5.5" --with "PyQt6>=6.5.0" \
  fastmcp run napari_mcp_server.py

Qt backend conflicts

Problem: Multiple Qt installations causing issues.

Diagnosis:

import qtpy
print(f"Using Qt API: {qtpy.API}")
print(f"Qt version: {qtpy.QT_VERSION}")

Solution:

# Force specific Qt backend
export QT_API=pyqt6

# Or reinstall clean
pip uninstall PyQt5 PyQt6 PySide2 PySide6
pip install PyQt6

Network and Firewall

Connection timeouts

Problem: Network timeouts when downloading dependencies.

Solutions:

# Increase timeout
pip install --timeout=60 napari

# Use different index
pip install -i https://pypi.python.org/simple/ napari

# Check proxy settings
pip install --proxy http://proxy:port napari

🔧 Performance Issues

Slow Startup

Server takes long to start

Problem: 30+ seconds to start server.

Optimizations:

# Pre-warm uv cache
uv run --with napari --help

# Use local installation
pip install -e .
napari-mcp  # Faster than uv run

# Check startup time
time uv run --with napari fastmcp run napari_mcp_server.py

Memory Issues

High memory usage

Problem: Excessive memory consumption.

Monitoring:

# Monitor memory usage
ps aux | grep napari

# Python memory profiling
python -m memory_profiler napari_mcp_server.py

Solutions: - Close unused napari viewers - Reduce image resolution for testing - Use gc.collect() in custom code - Monitor for memory leaks in long-running sessions

🖥️ Platform-Specific Issues

macOS

Gatekeeper blocks execution

Problem: "Cannot be opened because the developer cannot be verified"

Solution:

# Remove quarantine attribute
xattr -d com.apple.quarantine napari_mcp_server.py

# Or allow in System Preferences > Security & Privacy

Rosetta compatibility (Apple Silicon)

Problem: Performance issues on M1/M2 Macs.

Solution:

# Use native ARM Python
/opt/homebrew/bin/python3 -m pip install napari

# Check architecture
python -c "import platform; print(platform.machine())"

Windows

PowerShell execution policy

Problem: Scripts blocked by execution policy.

Solution:

# Set execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or run directly
python napari_mcp_server.py

Path length limitations

Problem: File paths too long on Windows.

Solution: - Enable long path support in Windows - Use shorter directory names - Move project closer to root drive

Linux

Display server issues

Problem: GUI doesn't work on headless systems.

Solutions:

# Virtual display
sudo apt-get install xvfb
xvfb-run -a python napari_mcp_server.py

# Or use offscreen
export QT_QPA_PLATFORM=offscreen

🐛 Debugging Tools

Logging and Debug Output

# Enable verbose logging
export MCP_LOG_LEVEL=DEBUG
export NAPARI_ASYNC=1

# Python debugging
python -u napari_mcp_server.py  # Unbuffered output

# FastMCP debugging
fastmcp run --debug napari_mcp_server.py

Testing Commands

# Test napari import
python -c "import napari; print('✅ napari works')"

# Test FastMCP
python -c "import fastmcp; print('✅ FastMCP works')"

# Test Qt
python -c "from PyQt6.QtWidgets import QApplication; app = QApplication([]); print('✅ Qt works')"

# Full integration test
python -c "
import napari
import fastmcp
viewer = napari.Viewer()
print('✅ Full integration works')
viewer.close()
"

System Information

# Collect system info for bug reports
echo "=== System Information ==="
python --version
pip --version
uv --version
echo "Platform: $(python -c 'import platform; print(platform.platform())')"
echo "Qt API: $(python -c 'import qtpy; print(qtpy.API)')"
echo "Napari: $(python -c 'import napari; print(napari.__version__)')"
echo "FastMCP: $(python -c 'import fastmcp; print(fastmcp.__version__)')"

🆘 Getting Help

If you've tried all the solutions above and still have issues:

Before Asking for Help

1. Collect information:
2. Error messages (full traceback)
3. System information (OS, Python version)
4. Steps to reproduce the issue

5. What you've tried already

6. Create minimal example:

   # Simplest possible test
   python -c "import napari; viewer = napari.Viewer()"
   

7. Check existing issues:

8. Search GitHub Issues
9. Check napari and FastMCP issue trackers

Where to Get Help

• GitHub Issues: Report bugs and ask questions
• Discussions: Community discussions
• Napari Community: Napari forum

Issue Template

When reporting bugs, please include:

## Bug Description
Brief description of the issue

## Steps to Reproduce
1. First step
2. Second step
3. See error

## Expected Behavior
What should happen

## Actual Behavior
What actually happens (include full error messages)

## Environment
- OS: [e.g., macOS 14.0, Ubuntu 22.04, Windows 11]
- Python: [e.g., 3.11.5]
- Napari: [e.g., 0.5.5]
- Installation method: [Zero install, traditional, etc.]

## Additional Context
Any other relevant information

---

Still stuck? Don't hesitate to ask for help! The community is here to support you. 🤝