A production-ready template for Python-based ML/AI development in Jupyter, with the right defaults baked in from day one.
It's minimal enough to not be opinionated about your problem domain, but opinionated about the things that cause pain: environment drift, noisy git history, inconsistent formatting, and slow project setup. The hard parts (nbstripout wiring, ruff for notebooks, DevContainer config) are already done.
Reproducible Environments
- VS Code DevContainer with Python 3.13 — works identically locally, on any teammate's machine, or in GitHub Codespaces
make setupgets you running outside a container too
Scientific Stack, Pre-Configured
- NumPy, Pandas, Matplotlib, Seaborn, SciPy — ready to import
- JupyterLab with auto-save, line numbers, and port forwarding on 8888
Code Quality Built-In
rufffor linting and formatting — applied to notebooks vianbqa, not just Python files- VS Code tasks for lint, format, and quality checks with one click
Clean Git History for Notebooks
nbstripoutstrips cell outputs before every commit — no more multi-MB diffs from running a cell.gitattributesconfigures meaningful notebook diffs- Automatic install via DevContainer post-create hook and
make setup
VS Code Workflow
- 15+ pre-configured tasks: start Jupyter, lint/format notebooks, create from template, export to HTML or script, check outdated packages
- Pre-installed extensions: Jupyter, Ruff, GitHub Copilot Chat
- Launch config to start JupyterLab with no password friction
Notebook Template
- Starter notebook with imports,
%matplotlib inline, and a structured sections scaffold - VS Code task to create a new named notebook from the template
AI-Ready
- GitHub Copilot Chat pre-installed
- OpenAI API key pattern established via
template.env - CLAUDE.md with project conventions so AI assistants follow the same standards
- Optional Jupyter MCP server — gives Claude Code direct read/execute access to running notebooks
- Open this folder in VS Code
- If prompted, reopen in container
- Run
jupyter labinside the terminal - Explore
notebooks/
Outside a container: run make setup then start Jupyter.
Quarto is pre-installed in the dev container and renders notebooks to HTML, PDF, and more.
VS Code tasks (via Tasks: Run Task):
| Task | Description |
|---|---|
| Quarto Preview | Live preview at localhost:4848 |
| Quarto Render | Render all notebooks to _site/ |
| Quarto Render Active File | Render only the open file |
| Quarto Publish | Publish to Quarto Pub / GitHub Pages |
CLI equivalents:
quarto preview # live preview
quarto render # render all to _site/
quarto render notebooks/01_init_notebook.ipynb
quarto publish quarto-pub # publish to quartopub.comProject output settings are in _quarto.yml.
The dev container ships with jupyter-mcp-server and jupyter-collaboration pre-installed. When JupyterLab is running, Claude Code can read cells, execute code, and inspect outputs directly through the jupyter MCP tool — no copy-pasting needed.
Claude Code always runs inside the dev container — not on the host. This means:
localhostinside the container is the container, not the host machine- All Python, Jupyter, and MCP dependencies live in the container
- The host's
~/.claude/is bind-mounted into the container so Claude Code settings persist across rebuilds - The host cannot be configured from within the container — any host-side changes must be made manually on the host
There are two MCP connection modes depending on where Claude Code is running:
| Claude Code location | Transport | Config location |
|---|---|---|
| Inside the container | stdio (automatic) | .claude/settings.json in this repo |
| On the host machine | streamable-http via port 4040 | ~/.claude/settings.json on the host |
| Tool | What it does | Requires |
|---|---|---|
execute_code |
Run arbitrary code on the active kernel | JupyterLab running |
execute_cell |
Run a specific cell by index from a notebook | Notebook open in JupyterLab UI (collaboration session) |
read_notebook |
Read notebook cells and outputs | JupyterLab running |
Copy template.env to .env:
cp template.env .env
# JUPYTER_TOKEN=dev ← default, change if neededBoth JupyterLab and the MCP server must be running. Start them in separate terminals:
make jupyter # JupyterLab on port 8888
make mcp-server # MCP server on port 4040 (for host access)Or use the VS Code tasks: Start Jupyter Lab and Start MCP Server (Remote).
No action needed. .claude/settings.json in this repo registers jupyter-mcp-server via stdio automatically when Claude Code starts. Run /mcp in Claude Code to confirm the jupyter server is listed.
Port 4040 is forwarded from the container to the host by the devcontainer config. Once the MCP server is running inside the container, add this block to ~/.claude/settings.json on the host (one time, manually):
{
"mcpServers": {
"jupyter": {
"type": "http",
"url": "http://localhost:4040/mcp",
"headers": {
"Authorization": "Bearer dev"
}
}
}
}Restart Claude Code on the host, then run /mcp to verify the jupyter server connects.
Copy template.env to .env and fill in your keys:
cp template.env .env