{"id":"01KHNJ6E0RS4V0DEPXN4S5X18G","type":"mcp_connector","title":"Jupyter MCP Server","slug":"vb-jupyter-mcp-server","short_description":"An MCP server that enables AI to connect to and manage Jupyter Notebooks in real time, providing code execution, cell manipulation, and multimodal output support across any Jupyter deployment.","description_md":"~ Copyright (c) 2024- Datalayer, Inc.\n ~\n ~ BSD 3-Clause License\n-->\n\n[![Datalayer](https://images.datalayer.io/brand/logos/datalayer-horizontal.svg)](https://datalayer.io)\n\n[![Become a Sponsor](https://img.shields.io/static/v1?label=Become%20a%20Sponsor&message=%E2%9D%A4&logo=GitHub&style=flat&color=1ABC9C)](https://github.com/sponsors/datalayer)\n\n

\n\n\n\n# 🪐🔧 Jupyter MCP Server\n\n**An [MCP](https://modelcontextprotocol.io) server developed for AI to connect and manage Jupyter Notebooks in real-time**\n\n*Developed by [Datalayer](https://github.com/datalayer)*\n\n[![PyPI - Version](https://img.shields.io/pypi/v/jupyter-mcp-server?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/jupyter-mcp-server)\n[![Total PyPI downloads](https://img.shields.io/pepy/dt/jupyter-mcp-server?style=for-the-badge&logo=python&logoColor=white)](https://pepy.tech/project/jupyter-mcp-server)\n[![Docker Pulls](https://img.shields.io/docker/pulls/datalayer/jupyter-mcp-server?style=for-the-badge&logo=docker&logoColor=white&color=2496ED)](https://hub.docker.com/r/datalayer/jupyter-mcp-server)\n[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue?style=for-the-badge&logo=open-source-initiative&logoColor=white)](https://opensource.org/licenses/BSD-3-Clause)\n\n\n![Jupyter MCP Server Demo](https://images.datalayer.io/products/jupyter-mcp-server/mcp-demo-multimodal.gif)\n\n

\n\n> [!NOTE]\n> **We Need Your Feedback!**\n> \n> 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!\n> \n> - 🏢 **JupyterHub users**: Share your deployment setup and requirements\n> - 🌐 **Google Colab users**: Help us understand your use cases and workflows\n> \n> 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.\n\n## 📖 Table of Contents\n\n- [Key Features](#-key-features)\n- [MCP Overview](#-mcp-overview)\n- [Getting Started](#-getting-started)\n- [Best Practices](#-best-practices)\n- [Contributing](#-contributing)\n- [Resources](#-resources)\n\n## 🚀 Key Features\n\n- ⚡ **Real-time control:** Instantly view notebook changes as they happen.\n- 🔁 **Smart execution:** Automatically adjusts when a cell run fails thanks to cell output feedback.\n- 🧠 **Context-aware:** Understands the entire notebook context for more relevant interactions.\n- 📊 **Multimodal support:** Support different output types, including images, plots, and text.\n- 📚 **Multi-notebook support:** Seamlessly switch between multiple notebooks.\n- 🎨 **JupyterLab integration:** Enhanced UI integration like automatic notebook opening.\n- 🤝 **MCP-compatible:** Works with any MCP client, such as Claude Desktop, Cursor, Windsurf, and more.\n\nCompatible with any Jupyter deployment (local, JupyterHub, ...) and with [Datalayer](https://datalayer.ai) hosted Notebooks.\n\n\n## 🔧 MCP Overview\n\n### 🔧 Tools Overview\n\nThe server provides a rich set of tools for interacting with Jupyter notebooks, categorized as follows. \nFor more details on each tool, their parameters, and return values, please refer to the [official Tools documentation](https://jupyter-mcp-server.datalayer.tech/tools).\n\n\n#### Server Management Tools\n\n| Name | Description |\n| :--------------- | :----------------------------------------------------------------------------------------- |\n| `list_files` | List files and directories in the Jupyter server's file system. |\n| `list_kernels` | List all available and running kernel sessions on the Jupyter server. |\n| `connect_to_jupyter` | Connect to a Jupyter server dynamically without restarting the MCP server. *Not available when running as Jupyter extension. Useful for switching servers dynamically or avoiding hardcoded configuration.* [Read more](https://jupyter-mcp-server.datalayer.tech/reference/tools/#3-connect_to_jupyter) |\n\n#### Multi-Notebook Management Tools\n\n| Name | Description |\n| :----------------- | :--------------------------------------------------------------------------------------- |\n| `use_notebook` | Connect to a notebook file, create a new one, or switch between notebooks. |\n| `list_notebooks` | List all notebooks available on the Jupyter server and their status |\n| `restart_notebook` | Restart the kernel for a specific managed notebook. |\n| `unuse_notebook` | Disconnect from a specific notebook and release its resources. |\n| `read_notebook` | Read notebook cells source content with brief or detailed format options. |\n\n#### Cell Operations and Execution Tools\n\n| Name | Description |\n| :------------------------- | :------------------------------------------------------------------------------- |\n| `read_cell` | Read the full content (Metadata, Source and Outputs) of a single cell. |\n| `insert_cell` | Insert a new code or markdown cell at a specified position. |\n| `delete_cell` | Delete a cell at a specified index. |\n| `overwrite_cell_source` | Overwrite the source code of an existing cell. |\n| `execute_cell` | Execute a cell with timeout, supports multimodal output including images. |\n| `insert_execute_code_cell` | Insert a new code cell and execute it in one step. |\n| `execute_code` | Execute code directly in the kernel, supports magic commands and shell commands. |\n\n#### JupyterLab Integration\n\n*Available only when JupyterLab mode is enabled. It is enabled by default.*\n\nWhen running in JupyterLab mode, Jupyter MCP Server integrates with [jupyter-mcp-tools](https://github.com/datalayer/jupyter-mcp-tools) to expose additional JupyterLab commands as MCP tools. By default, the following tools are enabled:\n\n| Name | Description |\n| :---------------------------- | :--------------------------------------------------------------------------------- |\n| `notebook_run-all-cells` | Execute all cells in the current notebook sequentially |\n| `notebook_get-selected-cell` | Get information about the currently selected cell |\n\n

📚 Learn how to customize additional tools

\n\nYou can now customize which tools from `jupyter-mcp-tools` are available using the `allowed_jupyter_mcp_tools` configuration parameter. This allows you to enable additional notebook operations, console commands, file management tools, and more.\n\n```bash\n# Example: Enable additional tools via command-line\njupyter lab --port 4040 --IdentityProvider.token MY_TOKEN --JupyterMCPServerExtensionApp.allowed_jupyter_mcp_tools=\"notebook_run-all-cells,notebook_get-selected-cell,notebook_append-execute,console_create\"\n```\n\nFor the complete list of available tools and detailed configuration instructions, please refer to the [Additional Tools documentation](https://jupyter-mcp-server.datalayer.tech/reference/tools-additional).\n\n

\n\n### 📝 Prompt Overview\n\nThe server also supports [prompt feature](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts) of MCP, providing a easy way for user to interact with Jupyter notebooks.\n\n| Name | Description |\n| :------------- | :--------------------------------------------------------------------------------- |\n| `jupyter-cite` | Cite specific cells from specified notebook (like `@` in Coding IDE or CLI) |\n\nFor more details on each prompt, their input parameters, and return content, please refer to the [official Prompt documentation](https://jupyter-mcp-server.datalayer.tech/reference/prompts).\n\n## 🏁 Getting Started\n\nFor comprehensive setup instructions—including `Streamable HTTP` transport, running as a Jupyter Server extension and advanced configuration—check out [our documentation](https://jupyter-mcp-server.datalayer.tech/). Or, get started quickly with `JupyterLab` and `STDIO` transport here below.\n\n### 1. Set Up Your Environment\n\n```bash\npip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel\npip uninstall -y pycrdt datalayer_pycrdt\npip install datalayer_pycrdt==0.12.17\n```\n\n> [!TIP]\n> To confirm your environment is correctly configured:\n> 1. Open a notebook in JupyterLab\n> 2. Type some content in any cell (code or markdown)\n> 3. Observe the tab indicator: you should see an \"×\" appear next to the notebook name, indicating unsaved changes\n> 4. Wait a few seconds—the \"×\" should automatically change to a \"●\" without manually saving\n> \n> This automatic saving behavior confirms that the real-time collaboration features are working properly, which is essential for MCP server integration.\n\n### 2. Start JupyterLab\n\n```bash\n# Start JupyterLab on port 8888, allowing access from any IP and setting a token\njupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0\n```\n\n> [!NOTE]\n> If you are running notebooks through JupyterHub instead of JupyterLab as above, refer to our [JupyterHub setup guide](https://jupyter-mcp-server.datalayer.tech//providers/jupyterhub-streamable-http/).\n\n### 3. Configure Your Preferred MCP Client\n\nNext, configure your MCP client to connect to the server. We offer two primary methods—choose the one that best fits your needs:\n\n- **📦 Using `uvx` (Recommended for Quick Start):** A lightweight and fast method using `uv`. Ideal for local development and first-time users.\n- **🐳 Using `Docker` (Recommended for Production):** A containerized approach that ensures a consistent and isolated environment, perfect for production or complex setups.\n\n

📦 Using uvx (Quick Start)

\n\nFirst, install `uv`:\n\n```bash\npip install uv\nuv --version\n# should be 0.6.14 or higher\n```\n\nSee more details on [uv installation](https://docs.astral.sh/uv/getting-started/installation/).\n\nThen, configure your client:\n\n```json\n{\n \"mcpServers\": {\n \"jupyter\": {\n \"command\": \"uvx\",\n \"args\": [\"jupyter-mcp-server@latest\"],\n \"env\": {\n \"JUPYTER_URL\": \"http://localhost:8888\",\n \"JUPYTER_TOKEN\": \"MY_TOKEN\",\n \"ALLOW_IMG_OUTPUT\": \"true\"\n }\n }\n }\n}\n```\n\n

\n\n

🐳 Using Docker (Production)

\n\n**On macOS and Windows:**\n\n```json\n{\n \"mcpServers\": {\n \"jupyter\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"JUPYTER_URL\",\n \"-e\", \"JUPYTER_TOKEN\",\n \"-e\", \"ALLOW_IMG_OUTPUT\",\n \"datalayer/jupyter-mcp-server:latest\"\n ],\n \"env\": {\n \"JUPYTER_URL\": \"http://host.docker.internal:8888\",\n \"JUPYTER_TOKEN\": \"MY_TOKEN\",\n \"ALLOW_IMG_OUTPUT\": \"true\"\n }\n }\n }\n}\n```\n\n**On Linux:**\n\n```json\n{\n \"mcpServers\": {\n \"jupyter\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"JUPYTER_URL\",\n \"-e\", \"JUPYTER_TOKEN\",\n \"-e\", \"ALLOW_IMG_OUTPUT\",\n \"--network=host\",\n \"datalayer/jupyter-mcp-server:latest\"\n ],\n \"env\": {\n \"JUPYTER_URL\": \"http://localhost:8888\",\n \"JUPYTER_TOKEN\": \"MY_TOKEN\",\n \"ALLOW_IMG_OUTPUT\": \"true\"\n }\n }\n }\n}\n```\n\n

\n\n> [!TIP]\n>\n> 1. **Port Configuration**: Ensure the `port` in your Jupyter URLs matches the one used in the `jupyter lab` command. For simplified config, set this in `JUPYTER_URL`.\n> 1. **Server Separation**: Use `JUPYTER_URL` when both services are on the same server, or set individual variables for advanced deployments. The different URL variables exist because some deployments separate notebook storage (`DOCUMENT_URL`) from kernel execution (`RUNTIME_URL`).\n> 1. **Authentication**: In most cases, document and runtime services use the same authentication token. Use `JUPYTER_TOKEN` for simplified config or set `DOCUMENT_TOKEN` and `RUNTIME_TOKEN` individually for different credentials.\n> 1. **Notebook Path**: The `DOCUMENT_ID` parameter specifies the path to the notebook the MCP client default to connect. It should be relative to the directory where JupyterLab was started. If you omit `DOCUMENT_ID`, the MCP client can automatically list all available notebooks on the Jupyter server, allowing you to select one interactively via your prompts.\n> 1. **Image Output**: Set `ALLOW_IMG_OUTPUT` to `false` if your LLM does not support mutimodel understanding.\n\nFor detailed instructions on configuring various MCP clients—including [Claude Desktop](https://jupyter-mcp-server.datalayer.tech/clients/claude_desktop), [VS Code](https://jupyter-mcp-server.datalayer.tech/clients/vscode), [Cursor](https://jupyter-mcp-server.datalayer.tech/clients/cursor), [Cline](https://jupyter-mcp-server.datalayer.tech/clients/cline), and [Windsurf](https://jupyter-mcp-server.datalayer.tech/clients/windsurf) — see the [Clients documentation](https://jupyter-mcp-server.datalayer.tech/clients).\n\n## ✅ Best Practices\n\n- Interact with LLMs that supports multimodal input (like Gemini 2.5 Pro) to fully utilize advanced multimodal understanding capabilities.\n- Use a MCP client that supports returning image data and can parse it (like Cursor, Gemini CLI, etc.), as some clients may not support this feature.\n- Break down complex task (like the whole data science workflow) into multiple sub-tasks (like data cleaning, feature engineering, model training, model evaluation, etc.) and execute them step-by-step.\n- Provide clearly structured prompts and rules (👉 Visit our [Prompt Templates](prompt/README.md) to get started)\n- Provide as much context as possible (like already installed packages, field explanations for existing datasets, current working directory, detailed task requirements, etc.).\n","ai_tags":["claude","cursor","windsurf"],"domain_tags":[{"child_name":"DevOps","child_slug":"devops","parent_name":"Development","parent_slug":"development"},{"child_name":"Machine Learning","child_slug":"machine-learning","parent_name":"AI & ML","parent_slug":"ai-ml"}],"author_user_id":"system-parser","author_name":null,"visibility":"public","pricing_type":"free","price_credits":0,"status":"published","version":"1.0.0","content_mode":"inline_text","inline_content":"An MCP server that enables AI to connect to and manage Jupyter Notebooks in real time, providing code execution, cell manipulation, and multimodal output support across any Jupyter deployment.\n\n## Installation\n\n### Environment Setup\n\n```bash\npip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel\npip uninstall -y pycrdt datalayer_pycrdt\npip install datalayer_pycrdt==0.12.17\n```\n\n### Running JupyterLab\n\n```bash\njupyter lab --port 8888 --IdentityProvider.token MY_TOKEN --ip 0.0.0.0\n```\n\n### Installing UV\n\n```bash\npip install uv\nuv --version\n```\n\n## Configuration\n\n### UVX Configuration\n\n```json\n{\n \"mcpServers\": {\n \"jupyter\": {\n \"command\": \"uvx\",\n \"args\": [\"jupyter-mcp-server@latest\"],\n \"env\": {\n \"JUPYTER_URL\": \"http://localhost:8888\",\n \"JUPYTER_TOKEN\": \"MY_TOKEN\",\n \"ALLOW_IMG_OUTPUT\": \"true\"\n }\n }\n }\n}\n```\n\n### Docker macOS/Windows\n\n```json\n{\n \"mcpServers\": {\n \"jupyter\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"JUPYTER_URL\",\n \"-e\", \"JUPYTER_TOKEN\",\n \"-e\", \"ALLOW_IMG_OUTPUT\",\n \"datalayer/jupyter-mcp-server:latest\"\n ],\n \"env\": {\n \"JUPYTER_URL\": \"http://host.docker.internal:8888\",\n \"JUPYTER_TOKEN\": \"MY_TOKEN\",\n \"ALLOW_IMG_OUTPUT\": \"true\"\n }\n }\n }\n}\n```\n\n### Docker Linux\n\n```json\n{\n \"mcpServers\": {\n \"jupyter\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"JUPYTER_URL\",\n \"-e\", \"JUPYTER_TOKEN\",\n \"-e\", \"ALLOW_IMG_OUTPUT\",\n \"--network=host\",\n \"datalayer/jupyter-mcp-server:latest\"\n ],\n \"env\": {\n \"JUPYTER_URL\": \"http://localhost:8888\",\n \"JUPYTER_TOKEN\": \"MY_TOKEN\",\n \"ALLOW_IMG_OUTPUT\": \"true\"\n }\n }\n }\n}\n```\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_files` | List files and directories in the Jupyter server file system |\n| `list_kernels` | List all available and running kernel sessions on the Jupyter server |\n| `use_notebook` | Connect to a notebook file, create a new one, or switch between notebooks |\n| `list_notebooks` | List all notebooks available on the Jupyter server and their status |\n| `restart_notebook` | Restart the kernel for a specific managed notebook |\n| `unuse_notebook` | Disconnect from a specific notebook and free its resources |\n| `read_notebook` | Read the source content of notebook cells with brief or detailed format options |\n| `read_cell` | Read the full content (metadata, source, and output) of a single cell |\n| `insert_cell` | Insert a new code or markdown cell at a specified position |\n| `delete_cell` | Delete a cell at the specified index |\n| `overwrite_cell_source` | Overwrite the source code of an existing cell |\n| `execute_cell` | Execute a cell with timeout, supports multimodal output including images |\n| `insert_execute_code_cell` | Insert a new code cell and execute it in one step |\n| `execute_code` | Execute code directly in the kernel, supports magic commands and shell commands |\n| `notebook_run-all-cells` | Sequentially execute all cells in the current notebook |\n\n## Capabilities\n\n- Real-time management: instantly view notebook changes as they happen\n- Intelligent execution: automatically adapt when cell execution fails through cell output feedback\n- Context awareness: understand the full notebook context for more relevant interactions\n- Multimodal support: support for various output types including images, plots, and text\n- Multi-notebook support: seamlessly switch between multiple notebooks\n- JupyterLab integration: enhanced UI integration, such as automatic notebook opening\n- MCP compatibility: works with any MCP client such as Claude Desktop, Cursor, Windsurf, and others\n\n## Environment Variables\n\n### Required\n- `JUPYTER_URL` - URL of the Jupyter server\n- `JUPYTER_TOKEN` - authentication token for accessing the Jupyter server\n\n### Optional\n- `ALLOW_IMG_OUTPUT` - enable/disable image output support for multimodal capabilities\n- `DOCUMENT_URL` - URL for notebook storage (for advanced deployments)\n- `RUNTIME_URL` - URL for kernel execution (for advanced deployments)\n- `DOCUMENT_TOKEN` - token for authenticating with the document service (for separate credentials)\n- `RUNTIME_TOKEN` - token for authenticating with the execution service (for separate credentials)\n- `DOCUMENT_ID` - path to the notebook to connect to by default (relative to JupyterLab startup directory)\n- `JUPYTERHUB_ALLOW_TOKEN_IN_URL` - allow token in URL for JupyterHub deployments## Notes\n\nCompatible with any Jupyter deployment (local, JupyterHub) and Datalayer hosted notebooks. Requires specific versions of jupyterlab, jupyter-collaboration, and datalayer_pycrdt for proper real-time collaboration functionality. Best used with multimodal LLMs to fully leverage capabilities. JupyterHub users need to set JUPYTERHUB_ALLOW_TOKEN_IN_URL=1 and ensure the API token has the access:servers scope.","metadata_json":{"original_tags":["Code","Analytics","AI","Productivity","Integration"],"original_author":"datalayer","vibebaza_featured":true},"downloads_count":0,"rating_avg":4.0,"rating_count":1,"is_featured":true,"is_verified":true,"is_free_service":false,"external_source_name":"Datalayer","external_source_url":"https://github.com/datalayer/jupyter-mcp-server","claimed_by_user_id":null,"claimed_at":null,"files":[],"bundle_items":[],"chain_steps":[],"created_at":"2026-02-17T10:26:34.307671Z","updated_at":"2026-02-26T17:33:19.122351Z"}

Jupyter MCP Server

Claim this listing