Jupiter Controller MCP (jkb-mcp)

Connects Claude Code to local Jupyter kernels as a set of native tools: start/restart/shutdown kernels, run code against a live kernel (including one backing a VS Code notebook), get stdout, results, errors and plots back, and execute whole notebooks with outputs saved into the .ipynb. The client never needs to know the kernel's connection details.

Built and tested with Claude Code on Windows. It is a standard MCP server over stdio, so other MCP clients should work too, but they are untested.

Security warning: this tool executes arbitrary code inside your live Jupyter kernel process, with that process's full OS privileges, exactly as if you typed it into the notebook yourself. Execution ships disabled by default; see "Enabling execution" below.

The realistic threat is not just a misbehaving client. It is untrusted data flowing through a trusted client (prompt injection): a notebook, CSV, or web page containing adversarial text can steer the model into running exfiltration or destructive code. Mitigations built in: the tool-based opt-in is session-scoped (dies with the server process; persistent enablement requires you to edit the config file yourself), and a disable_execution tool can always turn it off. Still: be deliberate about which files and data you let the model read while execution is enabled.

Requirements

• Windows

• Python 3.11+

• Optional: VS Code with an active Jupyter kernel, if you want to attach to an existing notebook session. start_kernel can otherwise run everything standalone.

Related MCP server: JupyterMCP

Install

pip install git+https://github.com/nufelroknidev/jupyter-kernel-bridge-mcp.git

Or from a local clone:

git clone https://github.com/nufelroknidev/jupyter-kernel-bridge-mcp.git
pip install ./jupyter-kernel-bridge-mcp

Verify it installed correctly:

jkb-mcp --help

If jkb-mcp isn't found, your Python Scripts directory isn't on PATH. Use the full path shown by pip show -f jkb-mcp, or activate the venv you installed into.

Enabling execution

The server ships with code execution off. list_kernels and get_config always work; every tool that executes code or mutates kernel state refuses until you opt in, one of two ways:

1. Via the client (session-scoped): call the enable_execution tool with confirm="I understand the risk". This enables execution only until the MCP server process restarts. It is deliberately never persisted, so the model (or injected instructions in data it read) can't quietly enable execution forever.

2. Manually (persistent): edit %APPDATA%\jkb-mcp\config.json and set "execution_enabled": true, then restart the MCP server (config is cached at startup).

disable_execution turns it off again at any time. It clears the session flag and the config-file flag.

Register with Claude Code

claude mcp add jkb-mcp -- jkb-mcp

Add -s user to make it available in every project on this machine, not just the current one:

claude mcp add jkb-mcp -s user -- jkb-mcp

No absolute paths are involved; jkb-mcp resolves through whatever Python environment you installed the package into.

Teaching Claude Code about this server

The server ships its own usage guide as MCP server instructions (the recommended workflow, kernel-addressing semantics, and security rules), which Claude Code surfaces to the model automatically, so no context-file setup is required. If you want the model to reach for these tools more proactively, add a note like this to your project's CLAUDE.md:

All Jupyter-notebook work goes through the jkb-mcp MCP server: enable execution once per session (enable_execution), start or attach to a kernel (start_kernel / list_kernels), iterate with run_python, and persist results into the .ipynb with execute_notebook. Do not run notebook code through plain python subprocesses.

The "Tool reference" table below covers every tool and its parameters.

Tool reference

kernel parameter: 0 (the default) auto-selects the most recent kernel that responds to a health check, silently falling back to the next-most-recent if it's unresponsive. Any other explicit index is honored exactly: it fails with a clear message rather than silently substituting a different kernel. Because indices are positions in the newest-first list, they shift when new kernels appear; to target a specific kernel reliably across calls, pass its connection-file name (or a unique substring of it) from list_kernels instead, e.g. kernel="kernel-jkb-1a2b3c.json".

Troubleshooting

Data locations

Nothing is ever logged above DEBUG level for the actual code/output content, since kernel output can contain secrets. Only short previews and outcomes are logged at INFO.

Uninstall

pip uninstall jkb-mcp
claude mcp remove jkb-mcp

Optionally also delete %APPDATA%\jkb-mcp and %LOCALAPPDATA%\jkb-mcp.

License

PolyForm Noncommercial 1.0.0: free for personal, research, educational, and other noncommercial use. Commercial use requires a separate paid license from the copyright holder: nufel.rokni.dev@gmail.com. See LICENSE for full terms.