{"id":30797025,"url":"https://github.com/royerlab/napari-mcp","last_synced_at":"2026-04-02T13:21:09.265Z","repository":{"id":312487230,"uuid":"1041693060","full_name":"royerlab/napari-mcp","owner":"royerlab","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-31T01:07:58.000Z","size":1167,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-31T01:13:21.445Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/royerlab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-20T21:52:49.000Z","updated_at":"2025-08-30T21:46:04.000Z","dependencies_parsed_at":"2025-08-31T01:24:40.095Z","dependency_job_id":null,"html_url":"https://github.com/royerlab/napari-mcp","commit_stats":null,"previous_names":["royerlab/napari-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/royerlab/napari-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/royerlab%2Fnapari-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/royerlab%2Fnapari-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/royerlab%2Fnapari-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/royerlab%2Fnapari-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/royerlab","download_url":"https://codeload.github.com/royerlab/napari-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/royerlab%2Fnapari-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273790344,"owners_count":25168669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-05T17:12:34.758Z","updated_at":"2026-04-02T13:21:09.258Z","avatar_url":"https://github.com/royerlab.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Napari MCP Server\n\n[![Tests](https://github.com/royerlab/napari-mcp/workflows/Tests/badge.svg)](https://github.com/royerlab/napari-mcp/actions)\n[![codecov](https://codecov.io/gh/royerlab/napari-mcp/graph/badge.svg?token=E1WY58V877)](https://codecov.io/gh/royerlab/napari-mcp)\n[![PyPI version](https://badge.fury.io/py/napari-mcp.svg)](https://badge.fury.io/py/napari-mcp)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)\n\nMCP 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.\n\nhttps://github.com/user-attachments/assets/d261674c-9875-4671-8c60-a7f49d6f1b84\n\n## 🚀 Quick Start (3 Steps)\n\n### 1. Install the Package\n\n```bash\npip install napari-mcp\n```\n\n### 2. Auto-Configure Your AI Application\n\n```bash\n# For Claude Desktop\nnapari-mcp-install install claude-desktop\n\n# Include a napari GUI backend in the uv environment\nnapari-mcp-install install claude-desktop --backend pyqt6\n\n# For other applications (Claude Code, Cursor, Cline, etc.)\nnapari-mcp-install install --help  # See all options\n```\n\n### 3. Restart Your Application \u0026 Start Using\n\nRestart your AI app and you're ready! Try asking:\n```\n\"Can you call session_information() to show my napari session details?\"\n```\n\n**→ See [Full Documentation](https://royerlab.github.io/napari-mcp/) for detailed guides**\n\n## 🔌 Using as a napari Plugin\n\nnapari-mcp can also be used as a **napari plugin** for direct integration with a running napari session:\n\n1. **Start napari** normally: `napari`\n2. **Open the widget**: Plugins → napari-mcp: MCP Server Control\n3. **Click \"Start Server\"** to expose your current session to AI assistants\n4. **Connect your AI app** using the standard installer: `napari-mcp-install install \u003capp\u003e`\n\nThis mode enables AI assistants to control your **current napari session** rather than starting a new viewer. Perfect for integrating with existing workflows!\n\n**→ See [Plugin Guide](https://royerlab.github.io/napari-mcp/guides/napari-plugin/) for detailed instructions**\n\n## 🎯 What Can You Do?\n\n### Basic Image Analysis\n```\n\"Load the image from ./data/sample.tif and apply a viridis colormap\"\n\"Create point annotations at coordinates [[100,100], [200,200]]\"\n\"Take a screenshot and save it\"\n```\n\n### Advanced Workflows\n```\n\"Execute this code to create a filtered version:\nfrom scipy import ndimage\nfiltered = ndimage.gaussian_filter(viewer.layers[0].data, sigma=2)\nviewer.add_image(filtered, name='filtered')\"\n\n\"Install scikit-image and segment the cells in this microscopy image\"\n```\n\n### 3D/4D Navigation\n```\n\"Switch to 3D display mode\"\n\"Navigate to time point 5, Z-slice 10\"\n\"Create a rotating animation of this volume\"\n```\n\n### Automated Workflows\nWant to automate image processing with Python scripts? Use any LLM (OpenAI, Anthropic, etc.) with napari MCP:\n\n**→ See [Python Integration Examples](docs/examples/README.md)** for batch processing and workflow automation\n\n## 🤖 Supported AI Applications\n\n| Application | Command | Status |\n|-------------|---------|--------|\n| **Claude Desktop** | `napari-mcp-install install claude-desktop` | ✅ Full Support |\n| **Claude Code** | `napari-mcp-install install claude-code` | ✅ Full Support |\n| **Cursor IDE** | `napari-mcp-install install cursor` | ✅ Full Support |\n| **Cline (VS Code)** | `napari-mcp-install install cline-vscode` | ✅ Full Support |\n| **Cline (Cursor)** | `napari-mcp-install install cline-cursor` | ✅ Full Support |\n| **Gemini CLI** | `napari-mcp-install install gemini` | ✅ Full Support |\n| **Codex CLI** | `napari-mcp-install install codex` | ✅ Full Support |\n\n**→ See [Integration Guides](docs/integrations/index.md) for application-specific instructions**\n\n## 🛠 Available MCP Tools\n\nThe server exposes 16 tools for complete napari control:\n\n### Core Functions\n- **Session Management**: `init_viewer`, `close_viewer`, `session_information`\n- **Layer Operations**: `add_layer`, `list_layers`, `get_layer`, `remove_layer`, `set_layer_properties`, `reorder_layer`, `apply_to_layers`, `save_layer_data`\n- **Viewer Controls**: `configure_viewer`\n- **Utilities**: `screenshot`, `execute_code`, `install_packages`, `read_output`\n\n## ⚠️ Security Notice\n\n!!! warning \"Code Execution Capabilities\"\n    This server includes powerful tools that allow arbitrary code execution:\n\n    - **`execute_code()`** - Runs Python code in the server environment\n    - **`install_packages()`** - Installs packages via pip\n\n    The bridge server binds to `127.0.0.1` (localhost only) with no authentication.\n    Any local process can invoke these tools.\n\n    **Use only with trusted AI assistants on local networks.**\n    Never expose to public internet without proper sandboxing.\n\n## 📖 Documentation\n\n- **[Quick Start Guide](docs/getting-started/quickstart.md)** - Get running in 3 minutes\n- **[Installation Options](docs/getting-started/installation.md)** - Advanced installation methods\n- **[Integration Guides](docs/integrations/index.md)** - Setup for specific AI applications\n- **[Python Examples](docs/examples/README.md)** - Automate workflows with custom scripts\n- **[Troubleshooting](docs/guides/troubleshooting.md)** - Common issues and solutions\n- **[API Reference](https://royerlab.github.io/napari-mcp/api/)** - Complete tool documentation\n\n## 🧪 Development Setup\n\n```bash\n\n# Clone repository\ngit clone https://github.com/royerlab/napari-mcp.git\ncd napari-mcp\n\n# Install with development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest -m \"not realgui\"  # Skip GUI tests\npytest --cov=src --cov-report=html  # With coverage\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes with tests\n4. Run pre-commit hooks: `pre-commit run --all-files`\n5. Commit changes (`git commit -m 'Add amazing feature'`)\n6. Push to branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## 📋 Architecture\n\n- **`state.py`** — `ServerState` holding all mutable state (viewer, locks, execution namespace)\n- **`server.py`** — `create_server(state)` factory; tools defined as closures over state\n- **`qt_helpers.py`** — Qt application and viewer lifecycle management\n- **`output.py`** — Output truncation utility\n- **`bridge_server.py`** — Plugin bridge server (overrides 3 tools for Qt thread safety)\n- **`viewer_protocol.py`** — `ViewerProtocol` for typed viewer backends\n- **`cli/`** — `napari-mcp-install` CLI for configuring AI applications\n\nKey features:\n- **Thread-safe**: All napari operations are serialized\n- **Non-blocking**: Qt event loop runs asynchronously\n- **Stateful**: Maintains viewer state across tool calls\n- **Extensible**: Easy to add new tools\n\n## 📚 Resources\n\n- **[napari](https://napari.org/)** - Multi-dimensional image viewer\n- **[Model Context Protocol](https://modelcontextprotocol.io/)** - MCP specification\n- **[FastMCP](https://github.com/jlowin/fastmcp)** - Python MCP framework\n- **[Claude Desktop](https://claude.ai/download)** - AI assistant with MCP support\n\n## 📄 License\n\nBSD-3-Clause License - see [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [napari team](https://napari.org/) for the excellent imaging platform\n- [FastMCP](https://github.com/jlowin/fastmcp) for the MCP framework\n- [Anthropic](https://www.anthropic.com/) for Claude and MCP development\n- [astral-sh](https://astral.sh/) for uv dependency management\n\n---\n\n**Built with ❤️ for the microscopy and AI communities**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froyerlab%2Fnapari-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froyerlab%2Fnapari-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froyerlab%2Fnapari-mcp/lists"}