---
name: ipynb
displayName: Jupyter Notebook Reader & Converter
description: Read, inspect, and convert Jupyter notebook (.ipynb) files to text,
  Markdown, or JSON. Use when opening, summarising, or extracting content from a
  notebook.
tags:
  - jupyter
  - notebook
  - ipynb
  - convert
  - data-science
capabilities:
  - ReadNotebook
  - ConvertToMarkdown
  - ConvertToScript
  - ExtractCodeCells
  - StripOutputs
representativeQueries:
  - Read a .ipynb file and show me what's in it
  - Convert a Jupyter notebook to Markdown
  - Extract all code cells from a notebook
  - Strip outputs from a notebook and save a clean version
  - Export a .ipynb notebook as a Python script
version: 0.1.0
tier: curated
---

# Jupyter Notebook Reader & Converter

Reads a `.ipynb` file (which is plain JSON) and renders its cells as readable text, Markdown source, or a plain Python script. Works entirely with the Python standard library via `scripts/read_ipynb.py`.

## When to use

- You need to inspect, summarise, or quote content from a Jupyter notebook.
- You want to convert a notebook to Markdown or a runnable `.py` script without installing nbconvert.
- You need to extract only the code cells (with their outputs), or produce a clean (output-stripped) copy of the notebook JSON.

## Steps

1. **Detect format.** Confirm the file ends in `.ipynb` and is valid JSON with an `nbformat` key.
2. **Route by task.**
   - *Read / summarise* — run `python3 scripts/read_ipynb.py <file>` (default: pretty-printed text).
   - *Convert to Markdown* — run `python3 scripts/read_ipynb.py <file> --format markdown`.
   - *Convert to Python script* — run `python3 scripts/read_ipynb.py <file> --format script`.
   - *Extract code cells only* — run `python3 scripts/read_ipynb.py <file> --cells code`.
   - *Strip outputs* — run `python3 scripts/read_ipynb.py <file> --strip-outputs`.
3. **Deliver output.** Script prints to stdout; redirect to a file if a saved copy is needed.

## Operations

| Capability | CRUD | Resource | Tool |
|---|---|---|---|
| `ReadNotebook` | READ | .ipynb file | scripts/read_ipynb.py |
| `ConvertToMarkdown` | READ | .ipynb file | scripts/read_ipynb.py --format markdown |
| `ConvertToScript` | READ | .ipynb file | scripts/read_ipynb.py --format script |
| `ExtractCodeCells` | READ | .ipynb file | scripts/read_ipynb.py --cells code (shows code source + outputs) |
| `StripOutputs` | READ | .ipynb file | scripts/read_ipynb.py --strip-outputs |

## Output

- **Default (text):** each cell printed with its type, execution count (if any), source, and text outputs.
- **Markdown:** markdown cells rendered verbatim; code cells wrapped in fenced ` ```python ``` ` blocks; outputs as fenced blocks (HTML-only outputs use ` ```html ``` `; when both `text/plain` and `text/html` are present, `text/plain` is preferred).
- **Script:** code cells joined as executable Python; markdown cells become `# ---` comments.
- **Strip-outputs:** the original notebook JSON reprinted with all cell outputs cleared (safe to save as `.ipynb`).

## Notes

- The script requires only Python 3.6+ and stdlib `json` — no pip installs.
- For richer HTML/LaTeX/PDF export, use `jupyter nbconvert` if available.
- Image outputs (`image/png`) are noted as `[image output]` rather than embedded, since stdout is text.
- HTML-only outputs (no `text/plain` fallback) are noted as `[HTML output]` in text mode; in Markdown mode they are rendered as a fenced ` ```html ``` ` block. When a cell has both `text/plain` and `text/html`, `text/plain` is shown in both modes.
- nbformat 3 notebooks (rare, pre-2014) are supported via the `worksheets` unwrap path.

<!-- runner-fallback -->
## Remote runner (MCP)
Can't run this locally (no setup, missing dependency)? The StealthStack runner exposes the **same code** as server-side MCP tools — no local install needed: `ipynb_read`, `ipynb_strip_outputs`. Call the `application/mcp` catalog twin of this skill (its `runnerTwin`).