| 1 | <!-- |
| 2 | ~ Copyright (c) 2024- Datalayer, Inc. |
| 3 | ~ |
| 4 | ~ BSD 3-Clause License |
| 5 | --> |
| 6 | |
| 7 | [](https://datalayer.io) |
| 8 | |
| 9 | [](https://github.com/sponsors/datalayer) |
| 10 | |
| 11 | <div align="center"> |
| 12 | |
| 13 | <!-- omit in toc --> |
| 14 | |
| 15 | # 🪐🔧 Jupyter MCP Server |
| 16 | |
| 17 | **An [MCP](https://modelcontextprotocol.io) server developed for AI to connect and manage [Jupyter](https://jupyter.org) Notebooks in real-time** |
| 18 | |
| 19 | *Developed by [Datalayer](https://github.com/datalayer)* |
| 20 | |
| 21 | [](https://pypi.org/project/jupyter-mcp-server) |
| 22 | [](https://pepy.tech/project/jupyter-mcp-server) |
| 23 | [](https://hub.docker.com/r/datalayer/jupyter-mcp-server) |
| 24 | [](https://opensource.org/licenses/BSD-3-Clause) |
| 25 | |
| 26 | |
| 27 |  |
| 28 | |
| 29 | </div> |
| 30 | |
| 31 | > [!IMPORTANT] |
| 32 | > - **Update in v1.0.2:**: Configurable timeout: `execute_cell` timeout is now configurable via `JUPYTER_MCP_EXECUTION_TIMEOUT` env var or `execution_timeout` config (default: 120s, max: 3600s). Per-call `timeout=0` uses the config default. |
| 33 | > |
| 34 | > **Hotfixes in v1.0.3:** |
| 35 | > - **Management routes security (`/api/connect`, `/api/stop`, `/api/healthz`)** has been hardened in standalone `streamable-http` mode: |
| 36 | > - local `Host` is required for all management routes |
| 37 | > - non-local browser `Origin` is rejected |
| 38 | > - `MCP_TOKEN` (Bearer) is required for state-changing routes (`/api/connect`, `/api/stop`) |
| 39 | > |
| 40 | > **Update in v1.0.2:** `pycrdt` is now supported, so installing `datalayer_pycrdt` is no longer required. |
| 41 | > |
| 42 | > **Breaking change in v1.0.0:** You must configure `MCP_TOKEN` in your MCP client setup. |
| 43 | > |
| 44 | > For setup details, see: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-streamable-http-standalone/#3-configure-your-mcp-client |
| 45 | > |
| 46 | |
| 47 | > [!NOTE] |
| 48 | > **We Need Your Feedback!** |
| 49 | > |
| 50 | > We're actively developing support for **JupyterHub** and **Google Colab** deployments. If you're using or planning to use Jupyter MCP Server with these platforms, we'd love to hear from you! |
| 51 | > |
| 52 | > - 🏢 **JupyterHub users**: Share your deployment setup and requirements |
| 53 | > - 🌐 **Google Colab users**: Help us understand your use cases and workflows |
| 54 | > |
| 55 | > Join the conversation in our [Community page](https://jupyter-mcp-server.datalayer.tech/community) - your feedback will help us prioritize features and ensure these integrations work seamlessly for your needs. |
| 56 | |
| 57 | ## 📖 Table of Contents |
| 58 | |
| 59 | - [Key Features](#-key-features) |
| 60 | - [MCP Overview](#-mcp-overview) |
| 61 | - [Getting Started](#-getting-started) |
| 62 | - [Best Practices](#-best-practices) |
| 63 | - [Contributing](#-contributing) |
| 64 | - [Resources](#-resources) |
| 65 | |
| 66 | ## 🚀 Key Features |
| 67 | |
| 68 | - ⚡ **Real-time control:** Instantly view notebook changes as they happen. |
| 69 | - 🔁 **Smart execution:** Automatically adjusts when a cell run fails thanks to cell output feedback. |
| 70 | - 🧠 **Context-aware:** Understands the entire notebook context for more relevant interactions. |
| 71 | - 📊 **Multimodal support:** Support different output types, including images, plots, and text. |
| 72 | - 📚 **Multi-notebook support:** Seamlessly switch between multiple notebooks. |
| 73 | - 🎨 **JupyterLab integration:** Enhanced UI integration like automatic notebook opening. |
| 74 | - 🤝 **MCP-compatible:** Works with any MCP client, such as Claude Desktop, Cursor, Windsurf, and more. |
| 75 | - 🔍 **Observability:** Built-in hook system with OpenTelemetry i |