Documentation

Welcome to the Jupyters documentation. This guide will help you install, configure, and use Jupyters to give your AI assistant deep access to Jupyter notebooks.

Installation

Jupyters is distributed as a Python package. Install it with pip:

pip install jupyters-server

Requirements

Python 3.10 or higher
Jupyter kernel (automatically installed)
MCP-compatible AI client (Claude Desktop, Claude Code, etc.)

Verify Installation

# Check the command exists
which jupyters-server

# Check version
jupyters-server --version

Configuration

Configure your AI tool to use Jupyters as an MCP server.

Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

Add the Jupyters server:

{
  "mcpServers": {
    "jupyters": {
      "command": "jupyters-server"
    }
  }
}

Important: After editing the config, quit Claude Desktop completely (Cmd+Q / Alt+F4) and reopen it.

Virtual Environment

If you installed Jupyters in a virtual environment, use the full path:

{
  "mcpServers": {
    "jupyters": {
      "command": "/path/to/venv/bin/jupyters-server"
    }
  }
}

First Use

After configuration, test that Jupyters is working:

Open your AI tool (Claude Desktop)
Ask: "What MCP tools do you have access to?"
You should see 16 Jupyters tools listed

Try reading a notebook:

"Read my notebook at /path/to/notebook.ipynb and summarize it"

MCP Tools Reference

Jupyters provides 16 MCP tools organized into categories:

Notebook Operations

read_notebook

Reads a notebook and returns its content as JSON.

Parameters: path (string) - Absolute path to .ipynb file

create_notebook

Creates a new empty notebook at the specified path.

Parameters: path (string) - Path for new notebook

read_notebook_outline

Returns a simplified outline showing cell types and snippets.

Parameters: path (string) - Absolute path to .ipynb file

Cell Operations

read_cell

Reads the source code of a specific cell.

Parameters: path (string), index (integer)

update_cell

Updates the source code of a specific cell.

Parameters: path (string), index (integer), new_source (string)

add_cell

Adds a new cell to the notebook.

Parameters: path (string), source (string), cell_type (string, default: "code"), index (integer, default: -1)

split_cell

Splits a cell at the specified line number.

Parameters: path (string), index (integer), line (integer)

merge_cells

Merges multiple cells into one.

Parameters: path (string), start (integer), end (integer)

Execution

run_cell

Executes a cell in the notebook and returns the output. Includes safety checks.

Parameters: path (string), index (integer), force (boolean, default: false)

restart_kernel

Restarts the Jupyter kernel for the notebook.

Parameters: path (string)

get_execution_order

Returns cells sorted by execution order to understand actual notebook state.

Parameters: path (string)

Inspection (Pro+)

inspect_variable

Inspects a variable in the kernel with semantic understanding (DataFrame schema, tensor shapes, etc.).

Parameters: path (string), var_name (string)

Tier: Pro, Team

read_variable_sample

Reads a slice of a variable (DataFrame rows, list items).

Parameters: path (string), var_name (string), start (integer, default: 0), end (integer, default: 10)

Configuration

set_profile

Activates domain profiles for enhanced inspection (ML, Finance).

Parameters: profiles (string) - Comma-separated: "base", "ml", "finance", "all"

Tier: Team

activate_license

Activates a Jupyters license key.

Parameters: key (string) - License key (e.g., CE-PRO-XXXXXXXX)

get_server_info

Returns information about the Jupyters server version and status.

Variable Inspection

With Pro or Team tier, Jupyters provides deep semantic inspection of variables:

DataFrames

Column names and types
Shape (rows × columns)
Sample data (head)
Statistics (mean, std, etc.)
Memory usage

NumPy Arrays

Shape and dtype
Sample values
Statistics

PyTorch/TensorFlow Tensors

Shape and dtype
Device (CPU/GPU)
Gradient requirements

Code Execution

Jupyters executes code in real Jupyter kernels, capturing all outputs:

stdout/stderr - Print statements and errors
Return values - Cell execution results
Plots - Matplotlib, seaborn, plotly (Pro+)
Rich output - HTML, DataFrames, etc.

Token Budgeting: Large outputs are automatically truncated to prevent overwhelming your AI assistant.

Safety Checks

By default, Jupyters prevents potentially destructive operations:

File deletion commands
System commands (os.system, subprocess)
Network requests to external URLs
Package installation (pip install)

Team tier users can bypass safety checks with force=true.

License Activation

After purchasing a license, activate it through your AI:

"Activate my Jupyters license: CE-PRO-XXXXXXXXXX"

Or via command line:

python -c "from context_engine.license import LicenseManager; \
print(LicenseManager.instance().activate_license('CE-PRO-XXXXXXXXXX'))"

Tier Features

Feature	Free	Pro	Team
Daily Executions	5	Unlimited	Unlimited
Variable Inspection	✗	✓	✓
Plot Capture	✗	✓	✓
Domain Profiles	✗	✗	✓
Safety Override	✗	✗	✓

Common Issues

"Command not found: jupyters-server"

The command is not in your PATH. Use the full path in your config or install globally:

# Find where it's installed
which jupyters-server

# Or use pip show
pip show jupyters-server

"AI doesn't see MCP tools"

Verify config file exists and is valid JSON
Make sure you quit completely and reopened your AI tool
Test the server manually: jupyters-server

"Free tier limit reached"

You've used 10 executions today. Wait until midnight UTC or upgrade to Pro.

Kernel errors

Try restarting the kernel:

"Restart the kernel for /path/to/notebook.ipynb"

FAQ

Does Jupyters work with Python 2?

No, Jupyters requires Python 3.10 or higher.

Can I use multiple notebooks at once?

Yes, each notebook gets its own kernel instance.

Where is my license stored?

License data is stored in ~/.context-engine/license.json

How do I uninstall?

pip uninstall jupyters-server
rm -rf ~/.context-engine

Need more help?

Email support@jupyters.fun or open an issue on GitHub.