Jupyter MCP Server

https://jupyter-mcp-server.datalayer.tech
Admin
Jupyter MCP Server is a Model Context Protocol server that enables real-time interaction with...
Tokens:22,662
Snippets:203
Trust Score:5.6
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install Claude Desktop on Linux (Unofficial Nix Build)

Source: https://jupyter-mcp-server.datalayer.tech/clients/claude_desktop

This snippet provides an unofficial method to install Claude Desktop on Linux using a Nix build script. It requires Nix to be installed and may need specific experimental features enabled. The command uses a GitHub repository for the build.

```bash
NIXPKGS_ALLOW_UNFREE=1 nix run github:k3d3/claude-desktop-linux-flake \
  --impure \
  --extra-experimental-features flakes \
  --extra-experimental-features nix-command
```

--------------------------------

### Start Jupyter MCP Server Command

Source: https://jupyter-mcp-server.datalayer.tech/reference/configuration

Starts the Jupyter MCP Server with various configuration options. Supports different transport mechanisms, provider types, JupyterLab integration, and runtime/document specific settings. Allows customization of allowed tools and port for streamable-http transport.

```bash
jupyter-mcp-server start --help
```

```bash
jupyter-mcp-server start \
  --transport streamable-http \
  --jupyter-url http://localhost:8888 \
  --jupyter-token MY_TOKEN \
  --allowed-jupyter-mcp-tools "notebook_run-all-cells,notebook_get-selected-cell" \
  --port 4040
```

```bash
jupyter-mcp-server start \
  --transport streamable-http \
  --runtime-url http://localhost:8888 \
  --runtime-token MY_TOKEN \
  --start-new-runtime false
```

--------------------------------

### Start Jupyter Lab with a Token

Source: https://jupyter-mcp-server.datalayer.tech/reference/security

Demonstrates how to start a JupyterLab server and enforce authentication using a specific token. This token is then used to authenticate API requests.

```bash
jupyter lab --IdentityProvider.token MY_TOKEN
```

--------------------------------

### Start Jupyter MCP Server (Python)

Source: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-streamable-http-standalone

Installs and starts the Jupyter MCP server using Python. It configures the server to use streamable HTTP transport and specifies the URL and token for connecting to the Jupyter server.

```python
pip install jupyter-mcp-server  
jupyter-mcp-server start \  
  --transport streamable-http \  
  --jupyter-url http://localhost:8888 \  
  --jupyter-token MY_TOKEN \  
  --port 4040  
```

--------------------------------

### Install JupyterHub and Generate Config

Source: https://jupyter-mcp-server.datalayer.tech/reference/multi-users

Installs the JupyterHub package and generates a default configuration file. This is the first step in setting up JupyterHub for multi-user environments.

```python
pip install jupyterhub
jupyterhub --generate-config
```

--------------------------------

### Start JupyterLab Server

Source: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-streamable-http-standalone

Launches the JupyterLab server on a specified port with a given token for authentication. This command is essential for providing the environment for the MCP server to connect to.

```bash
jupyter lab --port 8888 --IdentityProvider.token MY_TOKEN  
```

--------------------------------

### Simplified Jupyter MCP Server Docker Configuration (JSON)

Source: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-stdio

This configuration uses Docker to run the Jupyter MCP server with essential environment variables for basic setup. It's recommended for most use cases and simplifies the deployment process.

```json
{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "JUPYTER_URL",
        "-e", "JUPYTER_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "--network=host",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

```

--------------------------------

### Start Jupyter Lab with Token for XSRF Workaround

Source: https://jupyter-mcp-server.datalayer.tech/reference/security

Recommended workaround for XSRF-only environments: start JupyterLab with a token and configure MCP server to use the same token for authentication.

```bash
jupyter lab --IdentityProvider.token YOUR_SECURE_TOKEN
```

--------------------------------

### Start JupyterLab with MCP Extension (Shell)

Source: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-streamable-http-extension

Starts the JupyterLab server with the integrated MCP server extension. It specifies the port to run on and an identity provider token for authentication. This command assumes the MCP server extension is installed in the Jupyter environment.

```shell
jupyter lab --port 4040 --IdentityProvider.token MY_TOKEN  
```

--------------------------------

### Problematic Shared JupyterLab Setup (Diagram)

Source: https://jupyter-mcp-server.datalayer.tech/reference/multi-users

A visual representation of a problematic setup where multiple user agents connect to a single MCP server, which then connects to a shared JupyterLab instance. This highlights the issue of shared state and concurrency problems.

```text
❌ PROBLEMATIC SETUP:

User 1 Agent  ─┐
               ├──▶ Single MCP Server ──▶ Shared JupyterLab
User 2 Agent  ─┘      (shared state)       (all users)

Problem: Both users' agents share the same "active notebook" state
```

--------------------------------

### Logging Configuration (JupyterHub)

Source: https://jupyter-mcp-server.datalayer.tech/reference/multi-users

Example configuration for setting up logging in JupyterHub. It defines the log level, log format, and specifies a file path for storing logs, enabling better monitoring and debugging.

```python
# jupyterhub_config.py
import logging

c.JupyterHub.log_level = 'INFO'
c.Application.log_format = '%(asctime)s [%(name)s] %(levelname)s: %(message)s'

# Log to file
c.JupyterHub.extra_log_file = '/var/log/jupyterhub/jupyterhub.log'
```

--------------------------------

### Verify Jupyter Server Extension List

Source: https://jupyter-mcp-server.datalayer.tech/reference/multi-users

This command, executed within a single-user Jupyter server environment, lists all installed and enabled Jupyter server extensions. It's used to verify that the `jupyter_mcp_server` extension has been successfully installed and is active, ensuring its functionality is available to the user.

```bash
# Inside single-user server
jupyter server extension list
# Should show: jupyter_mcp_server enabled

```

--------------------------------

### Start Jupyter Lab without Token for XSRF

Source: https://jupyter-mcp-server.datalayer.tech/reference/security

Command to start JupyterLab without enforcing token-based authentication, relying instead on XSRF cookies. This is typically used in specific enterprise or managed environments.

```bash
jupyter lab --IdentityProvider.token ''
```

--------------------------------

### Install Jupyter Packages (Python)

Source: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-streamable-http-standalone

Installs necessary Jupyter packages for real-time collaboration and MCP server integration. It also handles the uninstallation and reinstallation of specific datalayer packages to ensure compatibility.

```python
pip install jupyterlab==4.4.1 jupyter-collaboration==4.0.2 jupyter-mcp-tools>=0.1.4 ipykernel  
pip uninstall -y pycrdt datalayer_pycrdt  
pip install datalayer_pycrdt==0.12.17  
```

--------------------------------

### Start Jupyter MCP Server (Docker - MacOS/Windows)

Source: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-streamable-http-standalone

Launches the Jupyter MCP server using Docker on MacOS or Windows. It maps the container's port 4040 to the host and sets environment variables for the Jupyter server URL and token.

```bash
docker run \  
  -e JUPYTER_URL="http://host.docker.internal:8888" \  
  -e JUPYTER_TOKEN="MY_TOKEN" \  
  -p 4040:4040 \  
  datalayer/jupyter-mcp-server:latest \  
  --transport streamable-http  
```

--------------------------------

### Example HTTPS Configuration for MCP Client

Source: https://jupyter-mcp-server.datalayer.tech/reference/security

Illustrates the environment variables required for an MCP client to connect to a Jupyter server over HTTPS. It includes the server URL with a port and a placeholder for the API token. This is crucial for secure communication.

```json
{
  "env": {
    "JUPYTER_URL": "https://jupyter.example.com:8888",
    "JUPYTER_TOKEN": "your-token-here"
  }
}
```

--------------------------------

### Install Jupyter MCP Server Packages (Python)

Source: https://jupyter-mcp-server.datalayer.tech/providers/jupyterhub-streamable-http

Installs necessary packages for Jupyter MCP Server, JupyterLab, Jupyter Collaboration, and ipykernel. It also handles the uninstallation and reinstallation of specific versions of pycrdt and datalayer_pycrdt to ensure compatibility.

```python
pip install "jupyter-mcp-server>=0.15.0" "jupyterlab==4.4.1" "jupyter-collaboration==4.0.2" "ipykernel"  
pip uninstall -y pycrdt datalayer_pycrdt  
pip install datalayer_pycrdt==0.12.17  
```

--------------------------------

### Migrate User Notebooks

Source: https://jupyter-mcp-server.datalayer.tech/reference/multi-users

Copies user notebooks from a shared location to their respective home directories and sets the correct ownership. This is crucial for migrating from a shared environment to a per-user isolated setup.

```bash
# Copy notebooks to user directories
cp -r /shared/notebooks/alice/* /home/alice/
chown -R alice:alice /home/alice/
```

--------------------------------

### Start Jupyter MCP Server (Docker - Linux)

Source: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-streamable-http-standalone

Launches the Jupyter MCP server using Docker on Linux. It uses the host network for connectivity and sets environment variables for the Jupyter server URL and token, mapping port 4040.

```bash
docker run \  
  --network=host \  
  -e JUPYTER_URL="http://localhost:8888" \  
  -e JUPYTER_TOKEN="MY_TOKEN" \  
  -p 4040:4040 \  
  datalayer/jupyter-mcp-server:latest \  
  --transport streamable-http  
```

--------------------------------

### Configure Jupyter MCP Server (Simplified) in VS Code User Settings

Source: https://jupyter-mcp-server.datalayer.tech/clients/vscode

This JSON configuration snippet is for the `settings.json` file in VS Code. It sets up the 'DatalayerJupyter' MCP server using a simplified Docker command. This is the recommended approach for basic configurations.

```json
{
  "mcp": {
    "servers": {
    "DatalayerJupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "JUPYTER_URL",
        "-e",
        "JUPYTER_TOKEN",
        "-e",
        "DOCUMENT_ID",
        "-e",
        "ALLOW_IMG_OUTPUT",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://host.docker.internal:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}


```

--------------------------------

### Use Notebook

Source: https://jupyter-mcp-server.datalayer.tech/reference/tools

Activates a specified notebook for subsequent cell operations. It can connect to an existing notebook or create a new one.

```APIDOC
## use_notebook

### Description
Use a notebook and activate it for following cell operations.

### Method
POST

### Endpoint
/websites/jupyter-mcp-server_datalayer_tech/tools/use_notebook

### Parameters
#### Query Parameters
- **notebook_name** (string) - Unique identifier for the notebook
- **notebook_path** (string) - Path to the notebook file, relative to the Jupyter server root (e.g. "notebook.ipynb")
- **mode** (string) - Notebook operation mode: "connect" to connect to existing and activate it, "create" to create new and activate it (default: "connect")
- **kernel_id** (string, optional) - Specific kernel ID to use (will create new if skipped)

### Request Example
```json
{
  "notebook_name": "my_analysis",
  "notebook_path": "notebooks/analysis.ipynb",
  "mode": "connect"
}
```

### Response
#### Success Response (200)
- **message** (string) - Success message with notebook information including activation status, kernel details, and notebook overview

#### Response Example
```json
{
  "message": "Notebook 'my_analysis' activated. Kernel ID: abcdef123456. Overview: ..."
}
```
```

--------------------------------

### List Notebooks

Source: https://jupyter-mcp-server.datalayer.tech/reference/tools

Lists all notebooks that have been previously used with the `use_notebook` tool, providing their status and associated kernel information.

```APIDOC
## list_notebooks

### Description
List all notebooks that have been used via use_notebook tool.

### Method
POST

### Endpoint
/websites/jupyter-mcp-server_datalayer_tech/tools/list_notebooks

### Parameters
#### Query Parameters
None

### Request Example
```json
{
  "tool_code": "list_notebooks"
}
```

### Response
#### Success Response (200)
- **Name** (string) - Unique identifier for the notebook
- **Path** (string) - Path to the notebook file
- **Kernel_ID** (string) - Kernel ID associated with the notebook
- **Kernel_Status** (string) - Current status of the kernel
- **Activate** (string) - "✓" if this is the currently active notebook, empty otherwise

#### Response Example
```json
{
  "Name": "my_analysis",
  "Path": "notebooks/analysis.ipynb",
  "Kernel_ID": "abcdef123456",
  "Kernel_Status": "idle",
  "Activate": "✓"
}
```
```

--------------------------------

### Data Visualization with Matplotlib and Pandas

Source: https://jupyter-mcp-server.datalayer.tech/reference/configuration

This code snippet demonstrates how to create a bar chart for monthly revenue using Matplotlib and Pandas. It reads data from a CSV file and displays the chart, enabling AI to analyze its content.

```python
import matplotlib.pyplot as plt
import pandas as pd

df = pd.read_csv('sales_data.csv')
df.plot(kind='bar', x='month', y='revenue')
plt.title('Monthly Revenue')
plt.show()
# AI can now "see" and analyze the chart content

```

--------------------------------

### Connect Jupyter MCP Server Command

Source: https://jupyter-mcp-server.datalayer.tech/reference/configuration

Connects a Jupyter MCP Server to a specific document and runtime. Requires specifying provider type, document and runtime URLs, tokens, and optionally the Jupyter MCP Server URL. Useful for advanced workflows where the server needs to be explicitly linked to resources.

```bash
jupyter-mcp-server connect --help
```

```bash
jupyter-mcp-server connect \
  --provider datalayer \
  --document-url <url> \
  --document-id <document> \
  --document-token <token> \
  --runtime-url <url> \
  --runtime-id <runtime-id> \
  --runtime-token <token> \
  --jupyter-mcp-server-url http://localhost:4040
```

--------------------------------

### Configure Jupyter MCP Server (Simplified) in VS Code Workspace Settings

Source: https://jupyter-mcp-server.datalayer.tech/clients/vscode

This JSON configuration snippet is for the `.vscode/mcp.json` file in your VS Code workspace. It sets up the 'DatalayerJupyter' MCP server using a simplified Docker command. This enables workspace-specific configuration.

```json
{
  "servers": {
    "DatalayerJupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "JUPYTER_URL",
        "-e",
        "JUPYTER_TOKEN",
        "-e",
        "DOCUMENT_ID",
        "-e",
        "ALLOW_IMG_OUTPUT",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "JUPYTER_URL": "http://host.docker.internal:8888",
        "JUPYTER_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}


```

--------------------------------

### Configure Jupyter MCP Server (Advanced) in VS Code User Settings

Source: https://jupyter-mcp-server.datalayer.tech/clients/vscode

This JSON configuration snippet is for the `settings.json` file in VS Code. It sets up the 'DatalayerJupyter' MCP server using a Docker command for advanced deployments with separate document and runtime servers. Ensure to update with actual configuration details.

```json
{
  "mcp": {
    "servers": {
    "DatalayerJupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DOCUMENT_URL",
        "-e",
        "DOCUMENT_TOKEN",
        "-e",
        "DOCUMENT_ID",
        "-e",
        "RUNTIME_URL",
        "-e",
        "RUNTIME_TOKEN",
        "-e",
        "ALLOW_IMG_OUTPUT",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "DOCUMENT_URL": "http://host.docker.internal:8888",
        "DOCUMENT_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "RUNTIME_URL": "http://host.docker.internal:8888",
        "RUNTIME_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}


```

--------------------------------

### List Kernels

Source: https://jupyter-mcp-server.datalayer.tech/reference/tools

Lists all available kernels in the Jupyter server. This tool shows all running and available kernel sessions, including their IDs, names, states, and connection information.

```APIDOC
## list_kernels

### Description
List all available kernels in the Jupyter server. This tool shows all running and available kernel sessions on the Jupyter server, including their IDs, names, states, connection information, and kernel specifications. Useful for monitoring kernel resources and identifying specific kernels for connection.

### Method
POST

### Endpoint
/websites/jupyter-mcp-server_datalayer_tech/tools/list_kernels

### Parameters
#### Query Parameters
None

### Request Example
```json
{
  "tool_code": "list_kernels"
}
```

### Response
#### Success Response (200)
- **ID** (string) - Unique kernel identifier
- **Name** (string) - Kernel name/type (e.g., "python3", "ir", etc.)
- **Display_Name** (string) - Human-readable kernel name from kernel spec
- **Language** (string) - Programming language supported by the kernel
- **State** (string) - Current execution state ("idle", "busy", "unknown")
- **Connections** (integer) - Number of active connections to this kernel
- **Last_Activity** (string) - Timestamp of last kernel activity in YYYY-MM-DD HH:MM:SS format
- **Environment** (string) - Environment variables defined in the kernel spec (truncated if long)

#### Response Example
```json
{
  "ID": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "Name": "python3",
  "Display_Name": "Python 3 (ipykernel)",
  "Language": "python",
  "State": "idle",
  "Connections": 1,
  "Last_Activity": "2023-10-27 11:30:00",
  "Environment": "{\"PATH\": \"/usr/local/bin:/usr/bin:/bin\"}"
}
```
```

--------------------------------

### Advanced Jupyter MCP Server Docker Configuration (JSON)

Source: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-stdio

This advanced configuration is for deployments requiring separate document storage and runtime execution. It includes additional environment variables for managing document URLs, tokens, and runtime configurations.

```json
{
  "mcpServers": {
    "jupyter": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DOCUMENT_URL",
        "-e", "DOCUMENT_TOKEN",
        "-e", "DOCUMENT_ID",
        "-e", "RUNTIME_URL",
        "-e", "RUNTIME_TOKEN",
        "-e", "ALLOW_IMG_OUTPUT",
        "--network=host",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "DOCUMENT_URL": "http://localhost:8888",
        "DOCUMENT_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "RUNTIME_URL": "http://localhost:8888",
        "RUNTIME_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}

```

--------------------------------

### Connect to Jupyter Server

Source: https://jupyter-mcp-server.datalayer.tech/reference/tools

Connects to a Jupyter server dynamically using its URL and an optional token. This allows switching between different Jupyter servers without restarting the MCP server.

```APIDOC
## connect_to_jupyter

### Description
Connect to a Jupyter server dynamically with URL and token. This tool allows you to connect to different Jupyter servers without needing to restart the MCP server or modify configuration files.

### Method
POST

### Endpoint
/websites/jupyter-mcp-server_datalayer_tech/tools/connect_to_jupyter

### Parameters
#### Query Parameters
- **jupyter_url** (string) - Jupyter server URL to connect to (e.g., "http://localhost:8888")
- **jupyter_token** (string, optional) - Jupyter server authentication token
- **provider** (string, optional) - Provider type (default: "jupyter")

### Request Example
```json
{
  "jupyter_url": "http://localhost:8888",
  "jupyter_token": "your_jupyter_token"
}
```

### Response
#### Success Response (200)
- **message** (string) - Connection status message confirming successful connection to the Jupyter server

#### Response Example
```json
{
  "message": "Successfully connected to Jupyter server at http://localhost:8888"
}
```

### Notes
- Not available when running MCP server as a Jupyter extension.
- For production use, pre-configure connection details in server configuration. Providing tokens to LLMs in production is not secure.
```

--------------------------------

### Verify MCP Server Running (curl)

Source: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-streamable-http-standalone

A simple command to verify if the MCP server is running and accessible on the specified port. It sends a GET request to the MCP endpoint and expects a response.

```bash
curl http://localhost:4040/mcp
```

--------------------------------

### Dockerfile for Single-User Jupyter Environment

Source: https://jupyter-mcp-server.datalayer.tech/reference/multi-users

This Dockerfile defines a custom image for a single-user Jupyter environment, intended for use with JupyterHub. It installs essential packages including `jupyter-mcp-server`, `jupyterlab`, `jupyter-collaboration`, and `ipykernel`. It also specifies a particular version of `datalayer_pycrdt` and uninstalls potentially conflicting packages.

```dockerfile
# Dockerfile for single-user image
FROM jupyter/minimal-notebook:latest

RUN pip install "jupyter-mcp-server>=0.15.0" \
                "jupyterlab==4.4.1" \
                "jupyter-collaboration==4.0.2" \
                "ipykernel"
RUN pip uninstall -y pycrdt datalayer_pycrdt && \
    pip install datalayer_pycrdt==0.12.17

```

--------------------------------

### List Files

Source: https://jupyter-mcp-server.datalayer.tech/reference/tools

Lists all files and directories recursively in the Jupyter server's file system. This tool is used to explore the file system structure or find specific files.

```APIDOC
## list_files

### Description
List all files and directories recursively in the Jupyter server's file system. Used to explore the file system structure of the Jupyter server or to find specific files or directories.

### Method
POST

### Endpoint
/websites/jupyter-mcp-server_datalayer_tech/tools/list_files

### Parameters
#### Query Parameters
- **path** (string, optional) - The starting path to list from (empty string means root directory, default: "")
- **max_depth** (int, optional) - Maximum depth to recurse into subdirectories (default: 1, max: 3)
- **start_index** (int, optional) - Starting index for pagination (0-based, default: 0)
- **limit** (int, optional) - Maximum number of items to return (0 means no limit, default: 25)
- **pattern** (string, optional) - Glob pattern to filter file paths (default: "")

### Request Example
```json
{
  "path": "/data",
  "max_depth": 2,
  "limit": 10
}
```

### Response
#### Success Response (200)
- **Path** (string) - Full path to the file or directory
- **Type** (string) - File type ("file", "directory", "notebook", or "error" if inaccessible)
- **Size** (string) - File size formatted as B, KB, or MB (empty for directories)
- **Last_Modified** (string) - Last modification timestamp in YYYY-MM-DD HH:MM:SS format

#### Response Example
```json
{
  "Path": "/data/file.txt",
  "Type": "file",
  "Size": "1.5 KB",
  "Last_Modified": "2023-10-27 10:00:00"
}
```
```

--------------------------------

### Configure Jupyter MCP Server (Advanced) in VS Code Workspace Settings

Source: https://jupyter-mcp-server.datalayer.tech/clients/vscode

This JSON configuration snippet is for the `.vscode/mcp.json` file in your VS Code workspace. It sets up the 'DatalayerJupyter' MCP server using a Docker command for advanced deployments with separate document and runtime servers. This enables workspace-specific configuration.

```json
{
  "servers": {
    "DatalayerJupyter": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DOCUMENT_URL",
        "-e",
        "DOCUMENT_TOKEN",
        "-e",
        "DOCUMENT_ID",
        "-e",
        "RUNTIME_URL",
        "-e",
        "RUNTIME_TOKEN",
        "-e",
        "ALLOW_IMG_OUTPUT",
        "datalayer/jupyter-mcp-server:latest"
      ],
      "env": {
        "DOCUMENT_URL": "http://host.docker.internal:8888",
        "DOCUMENT_TOKEN": "MY_TOKEN",
        "DOCUMENT_ID": "notebook.ipynb",
        "RUNTIME_URL": "http://host.docker.internal:8888",
        "RUNTIME_TOKEN": "MY_TOKEN",
        "ALLOW_IMG_OUTPUT": "true"
      }
    }
  }
}


```

--------------------------------

### Jupyter Core Prompt - jupyter-cite

Source: https://jupyter-mcp-server.datalayer.tech/reference/prompts

The `jupyter-cite` prompt allows users to cite specific cells in a notebook, enabling LLMs to perform precise subsequent operations on those cells.

```APIDOC
## POST /api/prompts/jupyter-cite

### Description
This endpoint allows users to cite specific cells in a notebook for LLM operations.

### Method
POST

### Endpoint
/api/prompts/jupyter-cite

### Parameters
#### Query Parameters
- **prompt** (string) - Required - User prompt for the cited cells.
- **cell_indices** (string) - Required - Cell indices to cite. Supports single index, range format (e.g., "0-2"), mixed format (e.g., "0-2,4"), and open-ended range (e.g., "3-").
- **notebook_path** (string) - Optional - Name of the notebook to cite cells from. Defaults to the current activated notebook.

### Request Example
```json
{
  "prompt": "Summarize the key findings from these cells.",
  "cell_indices": "0-2,4",
  "notebook_path": "my_notebook.ipynb"
}
```

### Response
#### Success Response (200)
- **output** (string) - The formatted output string including cited cells and the user's instruction.

#### Response Example
```json
{
  "output": "USER Cite cells 0-2,4 from notebook my_notebook.ipynb, here are the cells: \n=====Cell 0 | type: code | execution count: 1=====\nprint('Hello')\n=====Cell 1 | type: code | execution count: 2=====\nx = 10\n=====Cell 2 | type: code | execution count: 3=====\ny = 20\n=====Cell 4 | type: code | execution count: 5=====\nprint(x+y)\n=====End of Cited Cells=====\nUSER's Instruction are follow: Summarize the key findings from these cells."
}
```
```

--------------------------------

### Verify Jupyter Server Running (Shell)

Source: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-stdio

This command verifies if the Jupyter server is running by sending an HTTP request to its default URL. It's a basic troubleshooting step to ensure the server is accessible.

```bash
curl http://localhost:8888

```

--------------------------------

### Run Docker Container with Least Privilege

Source: https://jupyter-mcp-server.datalayer.tech/reference/security

Provides a command to run a Docker container with minimal privileges, enhancing security. It uses options like `--read-only`, `--cap-drop=ALL`, and `--security-opt=no-new-privileges:true` to restrict the container's capabilities.

```bash
docker run \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  datalayer/jupyter-mcp-server
```

--------------------------------

### Secure Docker Token Handling

Source: https://jupyter-mcp-server.datalayer.tech/reference/security

Demonstrates secure methods for passing API tokens to Docker containers running Jupyter MCP Server. It contrasts the insecure method of exposing tokens directly in `docker run` commands with the recommended approach of using environment files (`.env`).

```bash
# ❌ BAD - Token visible in docker ps
docker run -e JUPYTER_TOKEN=my-secret-token ...

# ✅ GOOD - Use Docker secrets or environment file
docker run --env-file .env ...
```

--------------------------------

### Cell Management API

Source: https://jupyter-mcp-server.datalayer.tech/reference/tools

A collection of tools for managing cells within the currently activated notebook, including insertion, overwriting, execution, reading, and deletion.

```APIDOC
## POST /insert_cell

### Description
Insert a cell to specified position from the currently activated notebook.

### Method
POST

### Endpoint
/insert_cell

### Parameters
#### Request Body
- **cell_index** (int) - Required - Target index for insertion (0-based), use -1 to append at end
- **cell_type** (string) - Required - Type of cell to insert ("code" or "markdown")
- **cell_source** (string) - Required - Source content for the cell

### Response
#### Success Response (200)
- **message** (string) - Success message with insertion confirmation
- **surrounding_cells** (array) - Structure of the surrounding cells (up to 5 cells above and below)
```

```APIDOC
## POST /overwrite_cell_source

### Description
Overwrite the source of a specific cell from the currently activated notebook.

### Method
POST

### Endpoint
/overwrite_cell_source

### Parameters
#### Request Body
- **cell_index** (int) - Required - Index of the cell to overwrite (0-based)
- **cell_source** (string) - Required - New complete cell source

### Response
#### Success Response (200)
- **message** (string) - Success message with diff style comparison showing changes made (e.g. `+` for new lines, `-` for deleted lines)
```

```APIDOC
## POST /execute_cell

### Description
Execute a cell from the currently activated notebook with timeout and return it's outputs.

### Method
POST

### Endpoint
/execute_cell

### Parameters
#### Request Body
- **cell_index** (int) - Required - Index of the cell to execute (0-based)
- **timeout** (int) - Optional - Maximum seconds to wait for execution (default: 90)
- **stream** (bool) - Optional - Enable streaming progress updates for long-running cells (default: false)
- **progress_interval** (int) - Optional - Seconds between progress updates when stream=true (default: 5)

### Response
#### Success Response (200)
- **outputs** (list[Union[str, ImageContent]]) - List of outputs from the executed cell including text, HTML, and images. Supports streaming mode with progress updates for long-running cells.
```

```APIDOC
## POST /insert_execute_code_cell

### Description
Insert a cell at specified index from the currently activated notebook and then execute it with timeout and return it's outputs. Recommended for inserting and executing a cell simultaneously.

### Method
POST

### Endpoint
/insert_execute_code_cell

### Parameters
#### Request Body
- **cell_index** (int) - Required - Index of the cell to insert and execute (0-based)
- **cell_source** (string) - Required - Code source for the cell
- **timeout** (int) - Optional - Maximum seconds to wait for execution (default: 90)

### Response
#### Success Response (200)
- **message** (string) - Insertion confirmation message
- **outputs** (list[Union[str, ImageContent]]) - List of outputs from the executed cell including text, HTML, and images.
```

```APIDOC
## GET /read_cell

### Description
Read a specific cell from the currently activated notebook and return its metadata, source, and outputs (for code cells).

### Method
GET

### Endpoint
/read_cell

### Parameters
#### Query Parameters
- **cell_index** (int) - Required - Index of the cell to read (0-based)
- **include_outputs** (bool) - Optional - Include outputs in the response (only for code cells, default: true)

### Response
#### Success Response (200)
- **cell_data** (object) - Contains cell metadata (index, type, execution count), source code, and outputs (if requested and applicable).
```

```APIDOC
## DELETE /delete_cell

### Description
Delete a specific cell or multiple cells from the currently activated notebook and return the cell source of deleted cells (if include_source=True). Delete cells in descending order of index to avoid index shifting.

### Method
DELETE

### Endpoint
/delete_cell

### Parameters
#### Query Parameters
- **cell_indices** (list[int]) - Required - List of indices of the cells to delete (0-based)
- **include_source** (bool) - Optional - Whether to include the source of deleted cells (default: true)

### Response
#### Success Response (200)
- **message** (string) - Success message with deletion confirmation
- **deleted_sources** (list[string]) - The source code of the deleted cells (if include_source=True)
```

--------------------------------

### Machine Learning Model Visualization with Matplotlib

Source: https://jupyter-mcp-server.datalayer.tech/reference/configuration

This code snippet illustrates how to plot training and validation loss curves for a machine learning model using Matplotlib. It helps AI evaluate the training effectiveness by visualizing the loss trends over epochs.

```python
import matplotlib.pyplot as plt

# Plot training curves
plt.plot(epochs, train_loss, label='Training Loss')
plt.plot(epochs, val_loss, label='Validation Loss')
plt.legend()
plt.show()
# AI can evaluate training effectiveness from the visual curves

```

--------------------------------

### Verify File Permissions

Source: https://jupyter-mcp-server.datalayer.tech/reference/multi-users

Checks the file permissions of a user's home directory. Incorrect file permissions can lead to users seeing each other's notebooks.

```bash
ls -la ~
```

--------------------------------

### Read Notebook

Source: https://jupyter-mcp-server.datalayer.tech/reference/tools

Read a notebook and return index, source content, type, and execution count of each cell. Supports brief and detailed formats for different use cases.

```APIDOC
## GET /read_notebook

### Description
Read a notebook and return index, source content, type, execution count of each cell. Supports brief and detailed formats.

### Method
GET

### Endpoint
/read_notebook

### Parameters
#### Query Parameters
- **notebook_name** (string) - Required - Notebook identifier to read
- **response_format** (string) - Optional - Response format: "brief" (default) or "detailed"
- **start_index** (int) - Optional - Starting index for pagination (0-based, default: 0)
- **limit** (int) - Optional - Maximum number of items to return (0 means no limit, default: 20)

### Response
#### Success Response (200)
- **notebook_content** (object) - Notebook content in the requested format with cell details, metadata, and pagination information
```

--------------------------------

### Per-User MCP Client Configuration (JSON)

Source: https://jupyter-mcp-server.datalayer.tech/reference/multi-users

Defines the configuration for an MCP client for a specific user, including the command to run, arguments, and environment variables like the JupyterHub API token. This is typically part of a user's local configuration.

```json
{
  "mcpServers": {
    "jupyter": {
      "command": "npx",
      "args": ["mcp-remote", "https://hub.example.com/user/alice/mcp"],
      "env": {
        "JUPYTERHUB_API_TOKEN": "alice-api-token"
      }
    }
  }
}
```

--------------------------------

### Unuse Notebook

Source: https://jupyter-mcp-server.datalayer.tech/reference/tools

Unuse from a specific notebook and release its resources. This action disconnects the client from the notebook and frees up associated resources.

```APIDOC
## POST /unuse_notebook

### Description
Unuse from a specific notebook and release its resources.

### Method
POST

### Endpoint
/unuse_notebook

### Parameters
#### Query Parameters
- **notebook_name** (string) - Required - Notebook identifier to disconnect

### Response
#### Success Response (200)
- **message** (string) - Success message confirming the notebook has been disconnected and resources released
```

--------------------------------

### Datalayer Hosted Platform MCP Configuration (JSON)

Source: https://jupyter-mcp-server.datalayer.tech/reference/multi-users

Configuration for using the MCP server with the Datalayer hosted platform. It specifies the command to run, arguments, and environment variables including provider details and authentication tokens.

```json
{
  "mcpServers": {
    "datalayer": {
      "command": "uvx",
      "args": ["jupyter-mcp-server@latest"],
      "env": {
        "PROVIDER": "datalayer",
        "DATALAYER_URL": "https://app.datalayer.ai",
        "DATALAYER_TOKEN": "your-user-token"
      }
    }
  }
}
```

--------------------------------

### Test Jupyter Server Token Authentication (Shell)

Source: https://jupyter-mcp-server.datalayer.tech/providers/jupyter-stdio

This command tests the authentication token for the Jupyter server by making a request to the API sessions endpoint. It helps in diagnosing authentication errors.

```bash
curl -H "Authorization: token YOUR_TOKEN" http://localhost:8888/api/sessions

```

--------------------------------

### Configure MCP Client Environment Variables

Source: https://jupyter-mcp-server.datalayer.tech/reference/security

JSON configuration for the MCP client, specifying the JupyterHub URL and the API token. This allows the MCP client to authenticate and connect to the JupyterHub environment. Replace placeholders with actual values.

```json
{
  "env": {
    "JUPYTER_URL": "https://jupyterhub.example.com/user/username",
    "JUPYTER_TOKEN": "your-api-token-here"
  }
}
```

--------------------------------

### Configure DockerSpawner for JupyterHub

Source: https://jupyter-mcp-server.datalayer.tech/reference/multi-users

Sets the spawner class to DockerSpawner and specifies the Docker image to use for user servers. This configuration is part of the jupyterhub_config.py file.

```python
# jupyterhub_config.py
c.JupyterHub.spawner_class = 'dockerspawner.DockerSpawner'
c.DockerSpawner.image = 'your-mcp-enabled-image:latest'
```
Tokens:
Raw