Jupyter MCP Server for Claude Code: Setup & Config

What you can do with Jupyter in Claude Code

A live notebook interface combining precise cell edits, execution feedback, and multimodal results.

• Inspect a notebook and repair failed analysis cells with output feedback.
• Trace tool calls and kernel execution with observability hooks.

Before you start: Jupyter in Claude Code

• Python
• uv 0.6.14 or later
• A running authenticated Jupyter service
• JupyterLab collaboration setup as documented
• An MCP-compatible client

The environment setup includes ipykernel, pycrdt, and jupyter-mcp-tools, with JupyterLab pinned to 4.4.1 and jupyter-collaboration to 4.0.2. It separately warns that MCP_TOKEN is required from v1.0.0; consult its linked provider setup for that token's configuration. Image output needs compatible clients and models.

Jupyter Claude Code configuration

1. Choose Claude Code configuration scope

   For Jupyter MCP Server, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add Jupyter MCP Server to Claude Code

   Use the jupyter-mcp-server entry below in mcpServers. Keep Jupyter MCP Server's documented stdio connection fields and your other Claude Code entries.

3. Check Jupyter MCP Server in Claude Code

   Jupyter MCP Server: Inspect claude mcp list and /mcp status.

{
  "mcpServers": {
    "jupyter-mcp-server": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "jupyter-mcp-server@latest"
      ],
      "env": {
        "JUPYTER_URL": "<URL of the running Jupyter service>",
        "JUPYTER_TOKEN": "<Jupyter authentication token>",
        "ALLOW_IMG_OUTPUT": "<true for image-capable clients, otherwise false>",
        "MCP_TOKEN": "<MCP authentication token required by the README's version 1.0.0 notice>"
      }
    }
  }
}

claude mcp add-json --scope project 'jupyter-mcp-server' '{"type":"stdio","command":"uvx","args":["jupyter-mcp-server@latest"],"env":{"JUPYTER_URL":"<URL of the running Jupyter service>","JUPYTER_TOKEN":"<Jupyter authentication token>","ALLOW_IMG_OUTPUT":"<true for image-capable clients, otherwise false>","MCP_TOKEN":"<MCP authentication token required by the README'"'"'s version 1.0.0 notice>"}}'

Jupyter tools available to Claude Code

Jupyter's stored tool list documents 19 tools; compare it with Claude Code's connected tool list, because the stored list is not a live check.

list_files

For Jupyter's list_files, review the permission request and arguments in Claude Code before approval.

list_kernels

For Jupyter's list_kernels, review the permission request and arguments in Claude Code before approval.

connect_to_jupyter

For Jupyter's connect_to_jupyter, review the permission request and arguments in Claude Code before approval.

Change Jupyter connections without restarting; unavailable in extension mode.

use_notebook

For Jupyter's use_notebook, review the permission request and arguments in Claude Code before approval.

Open, create, or switch to a notebook.

list_notebooks

For Jupyter's list_notebooks, review the permission request and arguments in Claude Code before approval.

List available notebooks and their current status.

restart_notebook

For Jupyter's restart_notebook, review the permission request and arguments in Claude Code before approval.

Restart the kernel for a managed notebook.

unuse_notebook

For Jupyter's unuse_notebook, review the permission request and arguments in Claude Code before approval.

Disconnect a notebook and free its associated resources.

read_notebook

For Jupyter's read_notebook, review the permission request and arguments in Claude Code before approval.

read_cell

For Jupyter's read_cell, review the permission request and arguments in Claude Code before approval.

insert_cell

For Jupyter's insert_cell, review the permission request and arguments in Claude Code before approval.

delete_cell

For Jupyter's delete_cell, review the permission request and arguments in Claude Code before approval.

Remove a cell by index.

move_cell

For Jupyter's move_cell, review the permission request and arguments in Claude Code before approval.

overwrite_cell_source

For Jupyter's overwrite_cell_source, review the permission request and arguments in Claude Code before approval.

edit_cell_source

For Jupyter's edit_cell_source, review the permission request and arguments in Claude Code before approval.

execute_cell

For Jupyter's execute_cell, review the permission request and arguments in Claude Code before approval.

insert_execute_code_cell

For Jupyter's insert_execute_code_cell, review the permission request and arguments in Claude Code before approval.

Create a code cell and run it in one operation.

execute_code

For Jupyter's execute_code, review the permission request and arguments in Claude Code before approval.

Run code directly in the kernel, including magic and shell commands.

notebook_run-all-cells

For Jupyter's notebook_run-all-cells, review the permission request and arguments in Claude Code before approval.

Run current notebook cells in sequence when JupyterLab mode is enabled.

notebook_get-selected-cell

For Jupyter's notebook_get-selected-cell, review the permission request and arguments in Claude Code before approval.

Inspect the selected notebook cell in JupyterLab mode.

Jupyter: full stored tool descriptions

Troubleshooting Jupyter in Claude Code

• If Jupyter MCP Server fails to start, check uvx jupyter-mcp-server@latest (from uv, for Python tools), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• Jupyter MCP Server: check ALLOW_IMG_OUTPUT, JUPYTER_TOKEN, JUPYTER_URL, MCP_TOKEN; keep credentials out of shared .mcp.json.
• Jupyter MCP Server uses stdio here: Claude Code must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires a configured Jupyter environment and authentication tokens.
• Known limitation: Image handling depends on client and model capabilities.
• Known limitation: Dynamic server connection is unavailable in Jupyter extension mode.
• General Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions