Configure

Options

Check the help for the Jupyter MCP Server to see the available configuration options.

jupyter-mcp-server start --help

Usage: jupyter-mcp-server start [OPTIONS]

  Start the Jupyter MCP server with a transport.

Options:
  --transport [stdio|streamable-http]
                                  The transport to use for the MCP server.
                                  Defaults to 'stdio'.
  --provider [jupyter|datalayer]  The provider to use for the document and
                                  runtime. Defaults to 'jupyter'.
  --runtime-url TEXT              The runtime URL to use. For the jupyter
                                  provider, this is the Jupyter server URL.
                                  For the datalayer provider, this is the
                                  Datalayer runtime URL.
  --start-new-runtime BOOLEAN     Start a new runtime or use an existing one.
  --runtime-id TEXT               The kernel ID to use. If not provided, a new
                                  kernel should be started.
  --runtime-token TEXT            The runtime token to use for authentication
                                  with the provider. If not provided, the
                                  provider should accept anonymous requests.
  --document-url TEXT             The document URL to use. For the jupyter
                                  provider, this is the Jupyter server URL.
                                  For the datalayer provider, this is the
                                  Datalayer document URL.
  --document-id TEXT              The document id to use. For the jupyter
                                  provider, this is the notebook path. For the
                                  datalayer provider, this is the notebook
                                  path.
  --document-token TEXT           The document token to use for authentication
                                  with the provider. If not provided, the
                                  provider should accept anonymous requests.
  --port INTEGER                  The port to use for the Streamable HTTP
                                  transport. Ignored for stdio transport.
  --help                          Show this message and exit

Starting then Connecting to Existing Runtime

For example, you can start the MCP Server with the following command that will not create a new Runtime.

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

Only after you can start a local JupyterLab and open a Notebook with a Runtime.

make jupyterlab

Then, you can assign a document and runtime via the /connect endpoint by running this command.

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

Multimodal Output Support

The server supports multimodal output, allowing AI agents to directly receive and analyze visual content such as images and charts generated by code execution.

Supported Output Types

• Text Output: Standard text output from code execution
• Image Output: PNG images generated by matplotlib, seaborn, plotly, and other visualization libraries
• Error Output: Error messages and tracebacks

Environment Variable Configuration

Control multimodal output behavior using environment variables:

ALLOW_IMG_OUTPUT

Controls whether to return actual image content or text placeholders.

• Default: true
• Values: true, false, 1, 0, yes, no, on, off, enable, disable, enabled, disabled

Example Docker Configuration:

{
  "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",
        "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"
      }
    }
  }
}

Output Behavior

When ALLOW_IMG_OUTPUT=true (Default)

• Images are returned as ImageContent objects with actual PNG data
• AI agents can directly analyze visual content
• Supports advanced multimodal reasoning

When ALLOW_IMG_OUTPUT=false

• Images are returned as text placeholders: "[Image Output (PNG) - Image display disabled]"
• Maintains backward compatibility with text-only LLMs
• Reduces bandwidth and token usage

Use Cases

Data Visualization Analysis:

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

Machine Learning Model Visualization:

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