{"id":25860763,"url":"https://github.com/datalayer/jupyter-mcp-server","last_synced_at":"2026-04-02T21:10:31.428Z","repository":{"id":277406230,"uuid":"931366703","full_name":"datalayer/jupyter-mcp-server","owner":"datalayer","description":"🪐 ✨ Jupyter Model Context Protocol (MCP) Server.","archived":false,"fork":false,"pushed_at":"2025-02-28T14:35:41.000Z","size":95,"stargazers_count":8,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-28T15:06:39.500Z","etag":null,"topics":["jupyter","mcp-server"],"latest_commit_sha":null,"homepage":"https://datalayer.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datalayer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["datalayer"]}},"created_at":"2025-02-12T06:41:35.000Z","updated_at":"2025-02-28T14:35:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"0a470e83-3e51-4173-a3cc-fee3a60bb234","html_url":"https://github.com/datalayer/jupyter-mcp-server","commit_stats":null,"previous_names":["datalayer/jupyter-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datalayer%2Fjupyter-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datalayer%2Fjupyter-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datalayer%2Fjupyter-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datalayer%2Fjupyter-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datalayer","download_url":"https://codeload.github.com/datalayer/jupyter-mcp-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241435138,"owners_count":19962402,"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","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":["jupyter","mcp-server"],"created_at":"2025-03-01T22:57:32.273Z","updated_at":"2026-04-02T21:10:31.407Z","avatar_url":"https://github.com/datalayer.png","language":"Python","funding_links":["https://github.com/sponsors/datalayer"],"categories":["Data \u0026 Analytics","Development Tools MCP Servers","Data Science Tools","📚 Projects (1974 total)","پیاده‌سازی‌های سرور","🤖 AI/ML","Servers","Education and Learning","Code Execution","Python","カテゴリ","Containerised MCP Servers","A01_文本生成_文本对话","MCP Servers \u0026 Protocol","MCP Frameworks and libraries"],"sub_categories":["Jupyter \u0026 Notebooks","MCP Servers","🧮 \u003ca name=\"data-science-tools\"\u003e\u003c/a\u003eابزارهای علم داده","Developer Tools","How to Submit","🧠 \u003ca name=\"data-science--ml\"\u003e\u003c/a\u003eデータサイエンス・ML","AI \u0026 Machine Learning","大语言对话模型及数据","Python"],"readme":"\u003c!--\n  ~ Copyright (c) 2024- Datalayer, Inc.\n  ~\n  ~ BSD 3-Clause License\n--\u003e\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\u0026message=%E2%9D%A4\u0026logo=GitHub\u0026style=flat\u0026color=1ABC9C)](https://github.com/sponsors/datalayer)\n\n\u003cdiv align=\"center\"\u003e\n\n\u003c!-- omit in toc --\u003e\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\u0026logo=pypi\u0026logoColor=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\u0026logo=python\u0026logoColor=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\u0026logo=docker\u0026logoColor=white\u0026color=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\u0026logo=open-source-initiative\u0026logoColor=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\u003c/div\u003e\n\n\u003e [!NOTE]\n\u003e **We Need Your Feedback!**\n\u003e \n\u003e 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\u003e \n\u003e - 🏢 **JupyterHub users**: Share your deployment setup and requirements\n\u003e - 🌐 **Google Colab users**: Help us understand your use cases and workflows\n\u003e \n\u003e 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- 🔍 **Observability:** Built-in hook system with OpenTelemetry integration for tracing tool calls and kernel executions.\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\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📚 Learn how to customize additional tools\u003c/strong\u003e\u003c/summary\u003e\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\u003c/details\u003e\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\u003e=0.1.4 ipykernel\npip uninstall -y pycrdt datalayer_pycrdt\npip install datalayer_pycrdt==0.12.17\n```\n\n\u003e [!TIP]\n\u003e To confirm your environment is correctly configured:\n\u003e 1. Open a notebook in JupyterLab\n\u003e 2. Type some content in any cell (code or markdown)\n\u003e 3. Observe the tab indicator: you should see an \"×\" appear next to the notebook name, indicating unsaved changes\n\u003e 4. Wait a few seconds—the \"×\" should automatically change to a \"●\" without manually saving\n\u003e \n\u003e 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\u003e [!NOTE]\n\u003e 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\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📦 Using uvx (Quick Start)\u003c/b\u003e\u003c/summary\u003e\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\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🐳 Using Docker (Production)\u003c/b\u003e\u003c/summary\u003e\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\u003c/details\u003e\n\n\u003e [!TIP]\n\u003e\n\u003e 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\u003e 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\u003e 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\u003e 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\u003e 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\n## 🤝 Contributing\n\nWe welcome contributions of all kinds! Here are some examples:\n\n- 🐛 Bug fixes\n- 📝 Improvements to existing features\n- 🔧 New feature development\n- 📚 Documentation improvements and prompt templates\n\nFor detailed instructions on how to get started with development and submit your contributions, please see our [**Contributing Guide**](CONTRIBUTING.md).\n\n### Our Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=datalayer/jupyter-mcp-server)](https://github.com/datalayer/jupyter-mcp-server/graphs/contributors)\n\n## 📚 Resources\n\nLooking for blog posts, videos, or other materials about Jupyter MCP Server?\n\n👉 Visit the [**Resources section**](https://jupyter-mcp-server.datalayer.tech/resources) in our documentation for more!\n\n[![Star History Chart](https://api.star-history.com/svg?repos=datalayer/jupyter-mcp-server\u0026type=Date)](https://star-history.com/#datalayer/jupyter-mcp-server\u0026type=Date)\n\n______________________________________________________________________\n\n\u003cdiv align=\"center\"\u003e\n\n**If this project is helpful to you, please give us a ⭐️**\n\nMade with ❤️ by [Datalayer](https://github.com/datalayer)\n\n\u003c/div\u003e\n\n## Hosted deployment\n\nA hosted deployment is available on [Fronteir AI](https://fronteir.ai/mcp/datalayer-jupyter-mcp-server).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatalayer%2Fjupyter-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatalayer%2Fjupyter-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatalayer%2Fjupyter-mcp-server/lists"}