napari-mcp 0.1.0

MCP server for remote control of napari viewers via Model Context Protocol

Napari MCP Server

MCP server for remote control of napari viewers via Model Context Protocol (MCP). Perfect for AI-assisted microscopy analysis with Claude Desktop and other LLM applications.

https://github.com/user-attachments/assets/d261674c-9875-4671-8c60-a7f49d6f1b84

🚀 Quick Start (3 Steps)

1. Install the Package

pip install napari-mcp

2. Auto-Configure Your AI Application

# For Claude Desktop
napari-mcp-install install claude-desktop

# Include a napari GUI backend in the uv environment
napari-mcp-install install claude-desktop --backend pyqt6

# For other applications (Claude Code, Cursor, Cline, etc.)
napari-mcp-install install --help  # See all options

3. Restart Your Application & Start Using

Restart your AI app and you're ready! Try asking:

"Can you call session_information() to show my napari session details?"

→ See Full Documentation for detailed guides

🔌 Using as a napari Plugin

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

1. Start napari normally: napari
2. Open the widget: Plugins → napari-mcp: MCP Server Control
3. Click "Start Server" to expose your current session to AI assistants
4. Connect your AI app using the standard installer: napari-mcp-install install <app>

This mode enables AI assistants to control your current napari session rather than starting a new viewer. Perfect for integrating with existing workflows!

→ See Plugin Guide for detailed instructions

🎯 What Can You Do?

Basic Image Analysis

"Load the image from ./data/sample.tif and apply a viridis colormap"
"Create point annotations at coordinates [[100,100], [200,200]]"
"Take a screenshot and save it"

Advanced Workflows

"Execute this code to create a filtered version:
from scipy import ndimage
filtered = ndimage.gaussian_filter(viewer.layers[0].data, sigma=2)
viewer.add_image(filtered, name='filtered')"

"Install scikit-image and segment the cells in this microscopy image"

3D/4D Navigation

"Switch to 3D display mode"
"Navigate to time point 5, Z-slice 10"
"Create a rotating animation of this volume"

Automated Workflows

Want to automate image processing with Python scripts? Use any LLM (OpenAI, Anthropic, etc.) with napari MCP:

→ See Python Integration Examples for batch processing and workflow automation

🤖 Supported AI Applications

Application	Command	Status
Claude Desktop	napari-mcp-install install claude-desktop	✅ Full Support
Claude Code	napari-mcp-install install claude-code	✅ Full Support
Cursor IDE	napari-mcp-install install cursor	✅ Full Support
Cline (VS Code)	napari-mcp-install install cline-vscode	✅ Full Support
Cline (Cursor)	napari-mcp-install install cline-cursor	✅ Full Support
Gemini CLI	napari-mcp-install install gemini	✅ Full Support
Codex CLI	napari-mcp-install install codex	✅ Full Support

→ See Integration Guides for application-specific instructions

🛠 Available MCP Tools

The server exposes 16 tools for complete napari control:

Core Functions

• Session Management: init_viewer, close_viewer, session_information
• Layer Operations: add_layer, list_layers, get_layer, remove_layer, set_layer_properties, reorder_layer, apply_to_layers, save_layer_data
• Viewer Controls: configure_viewer
• Utilities: screenshot, execute_code, install_packages, read_output

⚠️ Security Notice

!!! warning "Code Execution Capabilities" This server includes powerful tools that allow arbitrary code execution:

- **`execute_code()`** - Runs Python code in the server environment
- **`install_packages()`** - Installs packages via pip

The bridge server binds to `127.0.0.1` (localhost only) with no authentication.
Any local process can invoke these tools.

**Use only with trusted AI assistants on local networks.**
Never expose to public internet without proper sandboxing.

📖 Documentation

• Quick Start Guide - Get running in 3 minutes
• Installation Options - Advanced installation methods
• Integration Guides - Setup for specific AI applications
• Python Examples - Automate workflows with custom scripts
• Troubleshooting - Common issues and solutions
• API Reference - Complete tool documentation

🧪 Development Setup

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

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest -m "not realgui"  # Skip GUI tests
pytest --cov=src --cov-report=html  # With coverage

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run pre-commit hooks: pre-commit run --all-files
5. Commit changes (git commit -m 'Add amazing feature')
6. Push to branch (git push origin feature/amazing-feature)
7. Open a Pull Request

📋 Architecture

• state.py — ServerState holding all mutable state (viewer, locks, execution namespace)
• server.py — create_server(state) factory; tools defined as closures over state
• qt_helpers.py — Qt application and viewer lifecycle management
• output.py — Output truncation utility
• bridge_server.py — Plugin bridge server (overrides 3 tools for Qt thread safety)
• viewer_protocol.py — ViewerProtocol for typed viewer backends
• cli/ — napari-mcp-install CLI for configuring AI applications

Key features:

• Thread-safe: All napari operations are serialized
• Non-blocking: Qt event loop runs asynchronously
• Stateful: Maintains viewer state across tool calls
• Extensible: Easy to add new tools

📚 Resources

• napari - Multi-dimensional image viewer
• Model Context Protocol - MCP specification
• FastMCP - Python MCP framework
• Claude Desktop - AI assistant with MCP support

📄 License

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

🙏 Acknowledgments

• napari team for the excellent imaging platform
• FastMCP for the MCP framework
• Anthropic for Claude and MCP development
• astral-sh for uv dependency management

---

Built with ❤️ for the microscopy and AI communities