Jupyter & MCP

Jupyter and MCP

Embed Jupyter in the app

Set NEXT_PUBLIC_JUPYTER_LAB_URL in .env.local (e.g. http://localhost:8888/lab?token=dataviz-mcp-token) to show the real Jupyter notebook in the right panel instead of the in-app cells.

When the Jupyter panel is shown and you have no MCP servers configured, the app auto-adds the Jupyter MCP server (http://localhost:3002/mcp). Run npm run jupyter-mcp (and ensure JupyterLab is running) so the MCP server is available. The script uses work/notebook.ipynb as the target notebook to match the app’s /api/ensure-jupyter-notebook.

Jupyter-first (recommended)

Upload your dataset in the Jupyter file browser (e.g. the work folder) instead of attaching it in chat. Then in chat say the filename or use “I uploaded a file in Jupyter (work folder)”. The AI will add code to load from path (e.g. pd.read_csv('work/trades.csv')) and run analysis there. This reduces payload size and is faster.

Attach in chat

If you attach a dataset in chat and Jupyter is configured, the app uploads it to the Jupyter work folder via POST /api/upload-to-jupyter and tells the AI the path. The server uses JUPYTER_API_URL and JUPYTER_TOKEN (or DOCUMENT_URL/DOCUMENT_TOKEN) from env.

---

Jupyter MCP setup (browser app)

The app uses client-side MCP: the browser must reach the MCP server over HTTP. Use work/notebook.ipynb as the notebook (the app creates it via /api/ensure-jupyter-notebook).

1. Start JupyterLab

Docker:

docker compose -f docker-compose.jupyter-mcp.yml up -d jupyterlab

Host:

jupyter lab --port 8888 --IdentityProvider.token dataviz-mcp-token --ip 0.0.0.0

Then open http://localhost:8888, token dataviz-mcp-token, and create or open the notebook.

2. Run Jupyter MCP with HTTP

From the project root (dataviz-storyteller):

pip install jupyter-mcp-server
npm run jupyter-mcp

This starts the MCP server at http://localhost:3002; the Streamable HTTP endpoint is http://localhost:3002/mcp. The npm run jupyter-mcp script uses --document-id work/notebook.ipynb by default.

3. Add MCP in the app

1. Run the DataViz app (npm run dev).
2. Open the chat page and click the MCP config button in the message toolbar.
3. Add server URL: http://localhost:3002/mcp.
4. Save. (Or leave empty when the Jupyter panel is shown; the app pre-seeds this URL.)

Cursor / Claude Desktop (stdio): Use Docker to run the MCP server with env DOCUMENT_URL, DOCUMENT_TOKEN, DOCUMENT_ID=work/notebook.ipynb, RUNTIME_URL, RUNTIME_TOKEN. The DataViz app needs HTTP; Cursor/Desktop can use stdio.

---

Troubleshooting

Issue	Cause	Fix
kernel_id / use_notebook error	Notebook has no running kernel	Open work/notebook.ipynb in the Jupyter panel, run any cell or Kernel → Start Kernel, then retry.
list_files max_depth	Tool allows max_depth ≤ 3 only	Retry; the AI will use a smaller depth.
MCP timeout (-32001)	Server or Jupyter slow/unreachable	Ensure JupyterLab and npm run jupyter-mcp are running; open the notebook and start a kernel.
404 collaboration/session	Standard Jupyter image has no collaboration API	Use the project’s collaboration image: docker compose -f docker-compose.jupyter-mcp.yml -f docker-compose.jupyter-collab.yml up -d --build jupyterlab.
nbformat error	Missing Python package	pip install nbformat in the env used for npm run jupyter-mcp, then restart.

Useful commands

Action	Command
Start JupyterLab	docker compose -f docker-compose.jupyter-mcp.yml up -d jupyterlab
Run Jupyter MCP (HTTP)	npm run jupyter-mcp
Stop	docker compose -f docker-compose.jupyter-mcp.yml down

Checklist

1. JupyterLab is up and you can open it (e.g. http://localhost:8888) and create/edit work/notebook.ipynb (the app can create it if missing).
2. Token in MCP config matches JupyterLab’s token (dataviz-mcp-token or your JUPYTER_TOKEN).
3. DOCUMENT_ID is work/notebook.ipynb (the npm run jupyter-mcp script sets this by default).
4. For the DataViz app (browser): MCP server runs with Streamable HTTP and the app’s MCP config has http://localhost:3002/mcp.