├── docs ├── docs │ ├── _category_.yaml │ ├── prompts │ │ ├── _category_.yaml │ │ └── index.mdx │ ├── tools │ │ └── _category_.yaml │ ├── clients │ │ ├── _category_.yaml │ │ ├── cline │ │ │ ├── _category_.yaml │ │ │ └── index.mdx │ │ ├── cursor │ │ │ ├── _category_.yaml │ │ │ └── index.mdx │ │ ├── vscode │ │ │ ├── _category_.yaml │ │ │ └── index.mdx │ │ ├── windsurf │ │ │ ├── _category_.yaml │ │ │ └── index.mdx │ │ ├── claude_desktop │ │ │ ├── _category_.yaml │ │ │ └── index.mdx │ │ └── index.mdx │ ├── releases │ │ ├── _category_.yaml │ │ └── index.mdx │ ├── contribute │ │ ├── _category_.yaml │ │ └── index.mdx │ ├── resources │ │ ├── _category_.yaml │ │ └── index.mdx │ ├── configuration │ │ └── _category_.yaml │ ├── jupyter │ │ ├── _category_.yaml │ │ ├── stdio │ │ │ └── _category_.yaml │ │ ├── streamable-http │ │ │ ├── _category_.yaml │ │ │ ├── jupyter-extension │ │ │ │ └── index.mdx │ │ │ └── standalone │ │ │ │ └── index.mdx │ │ └── index.mdx │ ├── datalayer │ │ ├── _category_.yaml │ │ └── streamable-http │ │ │ └── index.mdx │ ├── getting_started │ │ ├── _category_.yaml │ │ └── index.mdx │ └── index.mdx ├── static │ └── img │ │ ├── favicon.ico │ │ ├── datalayer │ │ ├── logo.png │ │ └── logo.svg │ │ ├── feature_2.svg │ │ └── feature_1.svg ├── babel.config.js ├── src │ ├── pages │ │ ├── markdown-page.md │ │ ├── testimonials.tsx │ │ └── index.module.css │ ├── components │ │ ├── HomepageFeatures.module.css │ │ ├── HomepageProducts.module.css │ │ ├── HomepageFeatures.js │ │ └── HomepageProducts.js │ └── theme │ │ └── CustomDocItem.tsx ├── .gitignore ├── .yarnrc.yml ├── sidebars.js ├── README.md ├── LICENSE ├── package.json ├── Makefile └── docusaurus.config.js ├── tests ├── __init__.py ├── test_config.py ├── test_prompts.py └── test_jupyter_extension.py ├── pytest.ini ├── jupyter_mcp_server ├── __version__.py ├── jupyter_extension │ ├── backends │ │ ├── __init__.py │ │ ├── remote_backend.py │ │ └── base.py │ ├── protocol │ │ ├── __init__.py │ │ └── messages.py │ ├── __init__.py │ └── context.py ├── log.py ├── __main__.py ├── __init__.py ├── tools │ ├── _base.py │ ├── __init__.py │ ├── list_notebooks_tool.py │ ├── read_notebook_tool.py │ ├── read_cell_tool.py │ ├── restart_notebook_tool.py │ └── unuse_notebook_tool.py ├── server_modes.py ├── enroll.py ├── models.py ├── config.py ├── server_context.py └── tool_cache.py ├── jupyter-config ├── jupyter_notebook_config │ └── jupyter_mcp_server.json └── jupyter_server_config.d │ └── jupyter_mcp_server.json ├── .vscode ├── settings.json └── mcp.json ├── .github ├── workflows │ ├── lint.sh │ ├── test.yml │ ├── fix-license-header.yml │ ├── build.yml │ └── release.yml └── dependabot.yml ├── .dockerignore ├── .licenserc.yaml ├── dev ├── README.md └── content │ ├── README.md │ └── new.ipynb ├── Dockerfile ├── smithery.yaml ├── .pre-commit-config.yaml ├── LICENSE ├── prompt ├── README.md └── general │ ├── README.md │ └── AGENT.md ├── .gitignore ├── pyproject.toml ├── CODE_OF_CONDUCT.md ├── RELEASE.md ├── Makefile └── CONTRIBUTING.md /docs/docs/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Overview" 2 | position: 1 3 | -------------------------------------------------------------------------------- /docs/docs/prompts/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Prompts" 2 | position: 6 -------------------------------------------------------------------------------- /docs/docs/tools/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Tools" 2 | position: 5 3 | -------------------------------------------------------------------------------- /docs/docs/clients/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Clients" 2 | position: 7 3 | -------------------------------------------------------------------------------- /docs/docs/releases/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Releases" 2 | position: 11 3 | -------------------------------------------------------------------------------- /docs/docs/clients/cline/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Cline" 2 | position: 4 3 | -------------------------------------------------------------------------------- /docs/docs/clients/cursor/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Cursor" 2 | position: 3 3 | -------------------------------------------------------------------------------- /docs/docs/clients/vscode/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "VS Code" 2 | position: 2 3 | -------------------------------------------------------------------------------- /docs/docs/contribute/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Contribute" 2 | position: 9 3 | -------------------------------------------------------------------------------- /docs/docs/resources/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Resources" 2 | position: 12 3 | -------------------------------------------------------------------------------- /docs/docs/clients/windsurf/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Windsurf" 2 | position: 5 3 | -------------------------------------------------------------------------------- /docs/docs/configuration/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Configuration" 2 | position: 5 3 | -------------------------------------------------------------------------------- /docs/docs/jupyter/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Jupyter Notebooks" 2 | position: 3 3 | -------------------------------------------------------------------------------- /docs/docs/datalayer/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Datalayer Notebooks" 2 | position: 4 3 | -------------------------------------------------------------------------------- /docs/docs/getting_started/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Getting Started" 2 | position: 2 3 | -------------------------------------------------------------------------------- /docs/docs/jupyter/stdio/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "STDIO Transport" 2 | position: 1 3 | -------------------------------------------------------------------------------- /docs/docs/clients/claude_desktop/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Claude Desktop" 2 | position: 1 3 | -------------------------------------------------------------------------------- /tests/__init__.py: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2024- Datalayer, Inc. 2 | # 3 | # BSD 3-Clause License 4 | -------------------------------------------------------------------------------- /docs/docs/jupyter/streamable-http/_category_.yaml: -------------------------------------------------------------------------------- 1 | label: "Streamable HTTP Transport" 2 | position: 2 3 | -------------------------------------------------------------------------------- /docs/static/img/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/datalayer/jupyter-mcp-server/HEAD/docs/static/img/favicon.ico -------------------------------------------------------------------------------- /docs/static/img/datalayer/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/datalayer/jupyter-mcp-server/HEAD/docs/static/img/datalayer/logo.png -------------------------------------------------------------------------------- /docs/docs/datalayer/streamable-http/index.mdx: -------------------------------------------------------------------------------- 1 | # Streamable HTTP Transport 2 | 3 | :::warning 4 | Documentation under construction. 5 | ::: 6 | -------------------------------------------------------------------------------- /pytest.ini: -------------------------------------------------------------------------------- 1 | ; Copyright (c) 2024- Datalayer, Inc. 2 | ; 3 | ; BSD 3-Clause License 4 | 5 | [pytest] 6 | addopts = -rqA 7 | log_cli = true 8 | log_level = INFO 9 | -------------------------------------------------------------------------------- /jupyter_mcp_server/__version__.py: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2024- Datalayer, Inc. 2 | # 3 | # BSD 3-Clause License 4 | 5 | """Jupyter MCP Server.""" 6 | 7 | __version__ = "0.21.1" 8 | -------------------------------------------------------------------------------- /jupyter-config/jupyter_notebook_config/jupyter_mcp_server.json: -------------------------------------------------------------------------------- 1 | { 2 | "ServerApp": { 3 | "nbserver_extensions": { 4 | "jupyter_mcp_server": true 5 | } 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /jupyter-config/jupyter_server_config.d/jupyter_mcp_server.json: -------------------------------------------------------------------------------- 1 | { 2 | "ServerApp": { 3 | "jpserver_extensions": { 4 | "jupyter_mcp_server": true 5 | } 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /jupyter_mcp_server/jupyter_extension/backends/__init__.py: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2024- Datalayer, Inc. 2 | # 3 | # BSD 3-Clause License 4 | 5 | """Backend implementations for notebook and kernel operations""" 6 | -------------------------------------------------------------------------------- /jupyter_mcp_server/jupyter_extension/protocol/__init__.py: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2024- Datalayer, Inc. 2 | # 3 | # BSD 3-Clause License 4 | 5 | """MCP Protocol implementation for Jupyter Server extension""" 6 | -------------------------------------------------------------------------------- /docs/babel.config.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024- Datalayer, Inc. 3 | * 4 | * BSD 3-Clause License 5 | */ 6 | 7 | module.exports = { 8 | presets: [require.resolve('@docusaurus/core/lib/babel/preset')], 9 | }; 10 | -------------------------------------------------------------------------------- /jupyter_mcp_server/log.py: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2024- Datalayer, Inc. 2 | # 3 | # BSD 3-Clause License 4 | 5 | """Logging Configuration for Jupyter MCP Server""" 6 | 7 | import logging 8 | 9 | logger = logging.getLogger(__name__) 10 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "python-envs.pythonProjects": [ 3 | { 4 | "path": "", 5 | "envManager": "ms-python.python:conda", 6 | "packageManager": "ms-python.python:conda" 7 | } 8 | ] 9 | } -------------------------------------------------------------------------------- /docs/src/pages/markdown-page.md: -------------------------------------------------------------------------------- 1 | 6 | 7 | --- 8 | title: Markdown page example 9 | --- 10 | 11 | # Markdown page example 12 | 13 | You don't need React to write simple standalone pages. 14 | -------------------------------------------------------------------------------- /.github/workflows/lint.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | # Copyright (c) 2024- Datalayer, Inc. 3 | # 4 | # BSD 3-Clause License 5 | 6 | pip install -e ".[lint,typing]" 7 | mypy --install-types --non-interactive . 8 | ruff check . 9 | mdformat --check *.md 10 | pipx run 'validate-pyproject[all]' pyproject.toml 11 | -------------------------------------------------------------------------------- /.dockerignore: -------------------------------------------------------------------------------- 1 | __pycache__ 2 | *.pyc 3 | *.pyo 4 | *.pyd 5 | .Python 6 | env 7 | pip-log.txt 8 | pip-delete-this-directory.txt 9 | .tox 10 | .coverage 11 | .coverage.* 12 | .cache 13 | nosetests.xml 14 | coverage.xml 15 | *.cover 16 | *.log 17 | .git 18 | .github 19 | .mypy_cache 20 | .pytest_cache 21 | dev 22 | docs -------------------------------------------------------------------------------- /docs/.gitignore: -------------------------------------------------------------------------------- 1 | # Dependencies 2 | /node_modules 3 | 4 | # Production 5 | /build 6 | 7 | # Generated files 8 | .docusaurus 9 | .cache-loader 10 | 11 | # Misc 12 | .DS_Store 13 | .env.local 14 | .env.development.local 15 | .env.test.local 16 | .env.production.local 17 | 18 | npm-debug.log* 19 | yarn-debug.log* 20 | yarn-error.log* 21 | 22 | *.lock 23 | -------------------------------------------------------------------------------- /.licenserc.yaml: -------------------------------------------------------------------------------- 1 | header: 2 | license: 3 | content: | 4 | Copyright (c) 2024- Datalayer, Inc. 5 | 6 | BSD 3-Clause License 7 | 8 | 9 | paths-ignore: 10 | - '**/*.ipynb' 11 | - '**/*.json' 12 | - '**/*.yaml' 13 | - '**/*.yml' 14 | - '**/.*' 15 | - 'docs/**/*' 16 | - 'LICENSE' 17 | 18 | comment: on-failure -------------------------------------------------------------------------------- /jupyter_mcp_server/__main__.py: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2024- Datalayer, Inc. 2 | # 3 | # BSD 3-Clause License 4 | 5 | """ 6 | Entry point for running jupyter_mcp_server as a module. 7 | 8 | This allows the package to be run with: python -m jupyter_mcp_server 9 | """ 10 | 11 | from jupyter_mcp_server.CLI import server 12 | 13 | if __name__ == "__main__": 14 | server() 15 | 16 | -------------------------------------------------------------------------------- /dev/README.md: -------------------------------------------------------------------------------- 1 | 6 | 7 | [![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io) 8 | 9 | [![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) 10 | -------------------------------------------------------------------------------- /dev/content/README.md: -------------------------------------------------------------------------------- 1 | 6 | 7 | [![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io) 8 | 9 | [![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) 10 | -------------------------------------------------------------------------------- /docs/src/components/HomepageFeatures.module.css: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024- Datalayer, Inc. 3 | * 4 | * BSD 3-Clause License 5 | */ 6 | 7 | /* stylelint-disable docusaurus/copyright-header */ 8 | 9 | .features { 10 | display: flex; 11 | align-items: center; 12 | padding: 2rem 0; 13 | width: 100%; 14 | } 15 | 16 | .featureSvg { 17 | height: 200px; 18 | width: 200px; 19 | } 20 | -------------------------------------------------------------------------------- /docs/src/components/HomepageProducts.module.css: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024- Datalayer, Inc. 3 | * 4 | * BSD 3-Clause License 5 | */ 6 | 7 | /* stylelint-disable docusaurus/copyright-header */ 8 | 9 | .product { 10 | display: flex; 11 | align-items: center; 12 | padding: 2rem 0; 13 | width: 100%; 14 | } 15 | 16 | .productSvg { 17 | height: 200px; 18 | width: 200px; 19 | } 20 | -------------------------------------------------------------------------------- /jupyter_mcp_server/__init__.py: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2024- Datalayer, Inc. 2 | # 3 | # BSD 3-Clause License 4 | 5 | """Jupyter MCP Server.""" 6 | 7 | from jupyter_mcp_server.__version__ import __version__ 8 | from jupyter_mcp_server.jupyter_extension.extension import _jupyter_server_extension_points 9 | 10 | 11 | __all__ = [ 12 | "__version__", 13 | "_jupyter_server_extension_points", 14 | ] 15 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: "github-actions" 4 | directory: "/" 5 | schedule: 6 | interval: "monthly" 7 | groups: 8 | actions: 9 | patterns: 10 | - "*" 11 | - package-ecosystem: "pip" 12 | directory: "/" 13 | schedule: 14 | interval: "monthly" 15 | groups: 16 | pip: 17 | patterns: 18 | - "*" 19 | -------------------------------------------------------------------------------- /docs/src/theme/CustomDocItem.tsx: -------------------------------------------------------------------------------- 1 | import React from "react"; 2 | import { ThemeProvider } from '@primer/react-brand'; 3 | import DocItem from "@theme/DocItem"; 4 | 5 | import '@primer/react-brand/lib/css/main.css' 6 | 7 | export const CustomDocItem = (props: any) => { 8 | return ( 9 | <> 10 | 11 | 12 | 13 | 14 | ) 15 | } 16 | 17 | export default CustomDocItem; 18 | -------------------------------------------------------------------------------- /jupyter_mcp_server/jupyter_extension/__init__.py: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2024- Datalayer, Inc. 2 | # 3 | # BSD 3-Clause License 4 | 5 | """ 6 | Jupyter to MCP Adapter Package 7 | 8 | This package provides the adapter layer to expose MCP server tools as a Jupyter Server extension. 9 | It supports dual-mode operation: standalone MCP server and embedded Jupyter server extension. 10 | """ 11 | 12 | from jupyter_mcp_server.jupyter_extension.context import ServerContext, get_server_context 13 | 14 | __all__ = ["ServerContext", "get_server_context"] 15 | -------------------------------------------------------------------------------- /docs/docs/clients/windsurf/index.mdx: -------------------------------------------------------------------------------- 1 | # Windsurf 2 | 3 | ![](https://assets.datalayer.tech/jupyter-mcp/windsurf.png) 4 | 5 | ## Install Windsurf 6 | 7 | Install the Windsurf app from the [Windsurf website](https://windsurf.com/download). 8 | 9 | ## Configure Jupyter MCP Server 10 | 11 | To use Jupyter MCP Server with Windsurf, add the [Jupyter MCP Server configuration](/jupyter/stdio#2-setup-jupyter-mcp-server) to your `mcp_config.json` file, read more on the [MCP Windsurf documentation website](https://docs.windsurf.com/windsurf/cascade/mcp). 12 | -------------------------------------------------------------------------------- /docs/docs/clients/cursor/index.mdx: -------------------------------------------------------------------------------- 1 | # Cursor 2 | 3 | ![](https://assets.datalayer.tech/jupyter-mcp/cursor.png) 4 | 5 | ## Install Cursor 6 | 7 | Install the Cursor app from the [Cursor website](https://www.cursor.com/downloads). 8 | 9 | ## Configure Jupyter MCP Server 10 | 11 | To use Jupyter MCP Server with Cursor, add the [Jupyter MCP Server configuration](/jupyter/stdio#2-setup-jupyter-mcp-server) to your `.cursor/mcp.json` file, read more on the [MCP Cursor documentation website](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers). 12 | -------------------------------------------------------------------------------- /docs/docs/contribute/index.mdx: -------------------------------------------------------------------------------- 1 | # Contribute 2 | 3 | We invite you to contribute by [opening issues](https://github.com/datalayer/jupyter-mcp-server/issues) and submitting [pull requests](https://github.com/datalayer/jupyter-mcp-server/pulls). 4 | 5 | We welcome contributions of all kinds, including: 6 | - 🐛 Bug fixes 7 | - 📝 Improvements to existing features or documentation 8 | - ✨ New feature development 9 | 10 | Your contributions help us improve the project and make it more useful for everyone! 11 | 12 | See more in [CONTRIBUTING.md](https://github.com/datalayer/jupyter-mcp-server/blob/main/CONTRIBUTING.md) 13 | -------------------------------------------------------------------------------- /docs/docs/clients/cline/index.mdx: -------------------------------------------------------------------------------- 1 | # Cline 2 | 3 | ![](https://assets.datalayer.tech/jupyter-mcp/cline.png) 4 | 5 | ## Install Cline VS Code extension 6 | 7 | Install the Cline VS Code extension from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev). 8 | 9 | ## Configure Jupyter MCP Server 10 | 11 | To use Jupyter MCP Server with Cline, add the [Jupyter MCP Server configuration](/jupyter/stdio#2-setup-jupyter-mcp-server) to your `.cline_mcp_settings.json` file, read more on the [Cline documentation](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev). 12 | -------------------------------------------------------------------------------- /docs/src/pages/testimonials.tsx: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024- Datalayer, Inc. 3 | * 4 | * BSD 3-Clause License 5 | */ 6 | 7 | import React from 'react'; 8 | import Layout from '@theme/Layout'; 9 | import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; 10 | import HomepageFeatures from '../components/HomepageFeatures'; 11 | 12 | export default function Home() { 13 | const {siteConfig} = useDocusaurusContext(); 14 | return ( 15 | 18 |
19 | 20 |
21 | 22 | ); 23 | } 24 | -------------------------------------------------------------------------------- /docs/.yarnrc.yml: -------------------------------------------------------------------------------- 1 | # Copyright (c) Datalayer, Inc. https://datalayer.io 2 | # Distributed under the terms of the MIT License. 3 | 4 | enableImmutableInstalls: false 5 | enableInlineBuilds: false 6 | enableTelemetry: false 7 | httpTimeout: 60000 8 | nodeLinker: node-modules 9 | npmRegistryServer: "https://registry.yarnpkg.com" 10 | checksumBehavior: update 11 | 12 | # This will fix the build error with @lerna/legacy-package-management 13 | # See https://github.com/lerna/repro/pull/11 14 | packageExtensions: 15 | "@lerna/legacy-package-management@*": 16 | dependencies: 17 | "@lerna/child-process": "*" 18 | "js-yaml": "*" 19 | "rimraf": "*" 20 | peerDependencies: 21 | "nx": "*" -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2024- Datalayer, Inc. 2 | # 3 | # BSD 3-Clause License 4 | 5 | FROM python:3.12-slim 6 | 7 | WORKDIR /app 8 | 9 | COPY pyproject.toml LICENSE README.md ./ 10 | COPY jupyter_mcp_server/ jupyter_mcp_server/ 11 | COPY jupyter-config/ jupyter-config/ 12 | 13 | ENV PIP_NO_CACHE_DIR=1 \ 14 | PIP_DEFAULT_TIMEOUT=120 \ 15 | PIP_DISABLE_PIP_VERSION_CHECK=1 16 | RUN python -m pip install --upgrade pip wheel setuptools && pip --version 17 | 18 | RUN pip install --no-cache-dir -e . && \ 19 | pip uninstall -y pycrdt datalayer_pycrdt && \ 20 | pip install --no-cache-dir datalayer_pycrdt==0.12.17 21 | 22 | EXPOSE 4040 23 | 24 | ENTRYPOINT ["python", "-m", "jupyter_mcp_server"] 25 | -------------------------------------------------------------------------------- /docs/sidebars.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024- Datalayer, Inc. 3 | * 4 | * BSD 3-Clause License 5 | */ 6 | 7 | /** 8 | * Creating a sidebar enables you to: 9 | - create an ordered group of docs 10 | - render a sidebar for each doc of that group 11 | - provide next/previous navigation 12 | 13 | The sidebars can be generated from the filesystem, or explicitly defined here. 14 | 15 | Create as many sidebars as you want. 16 | */ 17 | 18 | // @ts-check 19 | 20 | /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ 21 | const sidebars = { 22 | jupyterMCPServerSidebar: [ 23 | { 24 | type: 'autogenerated', 25 | dirName: '.', 26 | }, 27 | ] 28 | }; 29 | 30 | module.exports = sidebars; 31 | -------------------------------------------------------------------------------- /docs/src/pages/index.module.css: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2024- Datalayer, Inc. 3 | * 4 | * BSD 3-Clause License 5 | */ 6 | 7 | /* stylelint-disable docusaurus/copyright-header */ 8 | 9 | /** 10 | * CSS files with the .module.css suffix will be treated as CSS modules 11 | * and scoped locally. 12 | */ 13 | 14 | .heroBanner { 15 | padding: 4rem 0; 16 | text-align: center; 17 | position: relative; 18 | overflow: hidden; 19 | } 20 | 21 | @media screen and (max-width: 966px) { 22 | .heroBanner { 23 | padding: 2rem; 24 | } 25 | } 26 | 27 | .buttons { 28 | display: flex; 29 | align-items: center; 30 | justify-content: center; 31 | } 32 | 33 | .tag { 34 | font-size: small; 35 | padding: 4px; 36 | border-radius: 5px; 37 | border-width: thick; 38 | border-color: red; 39 | background: orange; 40 | } 41 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | 6 | 7 | [![Datalayer](https://assets.datalayer.tech/datalayer-25.svg)](https://datalayer.io) 8 | 9 | [![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) 10 | 11 | # Jupyter MCP Server Docs 12 | 13 | > Source code for the [Jupyter MCP Server Documentation](https://datalayer.io), built with [Docusaurus](https://docusaurus.io). 14 | 15 | ```bash 16 | # Install the dependencies. 17 | conda install yarn 18 | yarn 19 | ``` 20 | 21 | ```bash 22 | # Local Development: This command starts a local development server and opens up a browser window. 23 | # Most changes are reflected live without having to restart the server. 24 | npm start 25 | ``` 26 | -------------------------------------------------------------------------------- /docs/docs/clients/index.mdx: -------------------------------------------------------------------------------- 1 | # Clients 2 | 3 | We have tested and validated the Jupyter MCP Server with the following clients: 4 | 5 | - [Claude Desktop](./claude_desktop) 6 | - [VS Code](./vscode) 7 | - [Cursor](./cursor) 8 | - [Cline](./cline) 9 | - [Windsurf](./windsurf) 10 | 11 | The Jupyter MCP Server is also compatible with **ANY** MCP client — see the growing list in [MCP clients](https://modelcontextprotocol.io/clients). This means that you are **NOT** limited to the clients listed above. Both [STDIO](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio) and [streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) transports are supported. 12 | 13 | If you prefer a CLI approach as client, you can use for example the python [mcp-client-cli](https://github.com/adhikasp/mcp-client-cli) package. 14 | -------------------------------------------------------------------------------- /.vscode/mcp.json: -------------------------------------------------------------------------------- 1 | { 2 | "servers": { 3 | // https://github.com/github/github-mcp-server 4 | "Github": { 5 | "url": "https://api.githubcopilot.com/mcp" 6 | }, 7 | // This configuration is for Docker on Linux, read https://jupyter-mcp-server.datalayer.tech/clients/ 8 | "DatalayerJupyter": { 9 | "command": "docker", 10 | "args": [ 11 | "run", 12 | "-i", 13 | "--rm", 14 | "-e", 15 | "DOCUMENT_URL", 16 | "-e", 17 | "DOCUMENT_TOKEN", 18 | "-e", 19 | "DOCUMENT_ID", 20 | "-e", 21 | "RUNTIME_URL", 22 | "-e", 23 | "RUNTIME_TOKEN", 24 | "datalayer/jupyter-mcp-server:latest" 25 | ], 26 | "env": { 27 | "DOCUMENT_URL": "http://host.docker.internal:8888", 28 | "DOCUMENT_TOKEN": "MY_TOKEN", 29 | "DOCUMENT_ID": "notebook.ipynb", 30 | "RUNTIME_URL": "http://host.docker.internal:8888", 31 | "RUNTIME_TOKEN": "MY_TOKEN" 32 | } 33 | } 34 | } 35 | } 36 | -------------------------------------------------------------------------------- /.github/workflows/test.yml: -------------------------------------------------------------------------------- 1 | name: Test 2 | 3 | on: 4 | push: 5 | branches: ["main"] 6 | pull_request: 7 | branches: ["main"] 8 | 9 | defaults: 10 | run: 11 | shell: bash -eux {0} 12 | 13 | jobs: 14 | test: 15 | runs-on: ${{ matrix.os }} 16 | strategy: 17 | fail-fast: false 18 | matrix: 19 | os: [ubuntu-latest, macos-latest, windows-latest] 20 | python-version: ["3.10", "3.13"] 21 | 22 | steps: 23 | - name: Checkout 24 | uses: actions/checkout@v5 25 | 26 | - name: Set up Python ${{ matrix.python-version }} 27 | uses: actions/setup-python@v6 28 | with: 29 | python-version: ${{ matrix.python-version }} 30 | 31 | - name: Install the extension 32 | run: | 33 | python -m pip install ".[test]" 34 | pip uninstall -y pycrdt datalayer_pycrdt 35 | pip install datalayer_pycrdt==0.12.17 36 | 37 | - name: Test the extension 38 | run: | 39 | make test-mcp-server 40 | make test-jupyter-server 41 | -------------------------------------------------------------------------------- /smithery.yaml: -------------------------------------------------------------------------------- 1 | # Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml 2 | 3 | startCommand: 4 | type: stdio 5 | configSchema: 6 | # JSON Schema defining the configuration options for the MCP. 7 | type: object 8 | required: 9 | - serverUrl 10 | - token 11 | - notebookPath 12 | properties: 13 | serverUrl: 14 | type: string 15 | description: The URL of the JupyterLab server that the MCP will connect to. 16 | token: 17 | type: string 18 | description: The token for authenticating with the JupyterLab server. 19 | notebookPath: 20 | type: string 21 | description: The path to the Jupyter notebook to work with. 22 | commandFunction: 23 | # A function that produces the CLI command to start the MCP on stdio. 24 | |- 25 | (config) => ({ command: 'docker', args: ['run', '-i', '--rm', '-e', `DOCUMENT_URL=${config.serverUrl}`, '-e', `TOKEN=${config.token}`, '-e', `DOCUMENT_ID=${config.notebookPath}`, 'datalayer/jupyter-mcp-server:latest'] }) 26 | -------------------------------------------------------------------------------- /docs/LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2021-2023 Datalayer, Inc. 2 | 3 | MIT License 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /.pre-commit-config.yaml: -------------------------------------------------------------------------------- 1 | ci: 2 | autoupdate_schedule: monthly 3 | 4 | repos: 5 | - repo: https://github.com/pre-commit/pre-commit-hooks 6 | rev: v5.0.0 7 | hooks: 8 | - id: end-of-file-fixer 9 | - id: check-case-conflict 10 | - id: check-executables-have-shebangs 11 | - id: requirements-txt-fixer 12 | - id: check-added-large-files 13 | - id: check-case-conflict 14 | - id: check-toml 15 | - id: check-yaml 16 | - id: debug-statements 17 | - id: forbid-new-submodules 18 | - id: check-builtin-literals 19 | - id: trailing-whitespace 20 | 21 | - repo: https://github.com/python-jsonschema/check-jsonschema 22 | rev: 0.29.4 23 | hooks: 24 | - id: check-github-workflows 25 | 26 | - repo: https://github.com/executablebooks/mdformat 27 | rev: 0.7.19 28 | hooks: 29 | - id: mdformat 30 | additional_dependencies: 31 | [mdformat-gfm, mdformat-frontmatter, mdformat-footnote] 32 | 33 | - repo: https://github.com/charliermarsh/ruff-pre-commit 34 | rev: v0.8.0 35 | hooks: 36 | - id: ruff 37 | args: ["--fix"] 38 | - id: ruff-format 39 | -------------------------------------------------------------------------------- /dev/content/new.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "id": "a70f6bd9", 6 | "metadata": {}, 7 | "source": [ 8 | "# A New Notebook" 9 | ] 10 | }, 11 | { 12 | "cell_type": "code", 13 | "execution_count": 1, 14 | "id": "3c3442e4", 15 | "metadata": {}, 16 | "outputs": [ 17 | { 18 | "name": "stdout", 19 | "output_type": "stream", 20 | "text": [ 21 | "Hello, World!\n" 22 | ] 23 | } 24 | ], 25 | "source": [ 26 | "print(\"Hello, World!\")" 27 | ] 28 | }, 29 | { 30 | "cell_type": "code", 31 | "execution_count": null, 32 | "id": "68d7d9e9", 33 | "metadata": {}, 34 | "outputs": [], 35 | "source": [] 36 | } 37 | ], 38 | "metadata": { 39 | "kernelspec": { 40 | "display_name": "base", 41 | "language": "python", 42 | "name": "python3" 43 | }, 44 | "language_info": { 45 | "codemirror_mode": { 46 | "name": "ipython", 47 | "version": 3 48 | }, 49 | "file_extension": ".py", 50 | "mimetype": "text/x-python", 51 | "name": "python", 52 | "nbconvert_exporter": "python", 53 | "pygments_lexer": "ipython3", 54 | "version": "3.13.5" 55 | } 56 | }, 57 | "nbformat": 4, 58 | "nbformat_minor": 5 59 | } 60 | -------------------------------------------------------------------------------- /docs/docs/clients/claude_desktop/index.mdx: -------------------------------------------------------------------------------- 1 | # Claude Desktop 2 | 3 | ![Jupyter MCP Server](https://assets.datalayer.tech/jupyter-mcp/mcp-demo-multimodal.gif) 4 | 5 | ## Install Claude Desktop 6 | 7 | Claude Desktop can be downloaded [from this page](https://claude.ai/download) for macOS and Windows. 8 | 9 | For Linux, we had success using this [UNOFFICIAL build script based on nix](https://github.com/k3d3/claude-desktop-linux-flake) 10 | 11 | ```bash 12 | # ⚠️ UNOFFICIAL 13 | # You can also run `make claude-linux` 14 | NIXPKGS_ALLOW_UNFREE=1 nix run github:k3d3/claude-desktop-linux-flake \ 15 | --impure \ 16 | --extra-experimental-features flakes \ 17 | --extra-experimental-features nix-command 18 | ``` 19 | 20 | ## Configure Jupyter MCP Server 21 | 22 | To use Jupyter MCP Server with Claude Desktop, add the [Jupyter MCP Server configuration](/jupyter/stdio#2-setup-jupyter-mcp-server) to your `claude_desktop_config.json` file, read more on the [MCP documentation website](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server). 23 | 24 | **📺 Watch the setup demo** 25 | 26 |