royerlab/napari-mcp
If you are the rightful owner of napari-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Napari MCP Server enables remote control of napari viewers using the Model Context Protocol (MCP), facilitating AI-assisted microscopy analysis.
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 claude-desktop
# For other applications (Claude Code, Cursor, Cline, etc.)
napari-mcp-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:
- Start napari normally:
napari - Open the widget: Plugins → napari-mcp: MCP Server Control
- Click "Start Server" to expose your current session to AI assistants
- Connect your AI app using the standard installer:
napari-mcp-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 for batch processing and workflow automation
🤖 Supported AI Applications
| Application | Command | Status |
|---|---|---|
| Claude Desktop | napari-mcp-install claude-desktop | ✅ Full Support |
| Claude Code | napari-mcp-install claude-code | ✅ Full Support |
| Cursor IDE | napari-mcp-install cursor | ✅ Full Support |
| Cline (VS Code) | napari-mcp-install cline-vscode | ✅ Full Support |
| Cline (Cursor) | napari-mcp-install cline-cursor | ✅ Full Support |
| Gemini CLI | napari-mcp-install gemini | ✅ Full Support |
| Codex CLI | napari-mcp-install codex | ✅ Full Support |
→ See for application-specific instructions
🛠 Available MCP Tools
The server exposes 20+ tools for complete napari control:
Core Functions
- Session Management:
detect_viewers,init_viewer,close_viewer,session_information - Layer Operations:
add_image,add_labels,add_points,list_layers,remove_layer - Viewer Controls:
set_camera,reset_view,set_ndisplay,set_dims_current_step - Utilities:
screenshot,execute_code,install_packages
→ See for complete documentation
⚠️ 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
**Use only with trusted AI assistants on local networks.**
Never expose to public internet without proper sandboxing.
📖 Documentation
- - Get running in 3 minutes
- - Advanced installation methods
- - Setup for specific AI applications
- - Automate workflows with custom scripts
- - Common issues and solutions
- - 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 ".[test,dev]"
# Run tests
pytest -m "not realgui" # Skip GUI tests
pytest --cov=src --cov-report=html # With coverage
🤝 Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes with tests
- Run pre-commit hooks:
pre-commit run --all-files - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open a Pull Request
📋 Architecture
- FastMCP Server: Handles MCP protocol communication
- Napari Integration: Manages viewer lifecycle and operations
- Qt Event Loop: Asynchronous GUI event processing
- Tool Layer: Exposes napari functionality as MCP tools
- External Bridge: Optional connection to existing napari viewers
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 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