jupyter-mcp-server: an MCP bridge between agents and live Jupyter notebooks

The gap jupyter-mcp-server fills between an agent and a running notebook

An MCP client can call tools, but it has no built-in way to touch a Jupyter kernel. The usual workaround is to have the model emit a code block, copy it into a notebook, run it, and paste the output back. That loop loses state between turns and gives the agent no way to read what is already in a cell. jupyter-mcp-server exists to close that loop: it is an MCP server that connects to Jupyter and lets an agent manage notebooks in real time, per the README's own description. The audience is narrow and specific. It is for engineers who already have Jupyter running locally or on JupyterHub and want an agent to operate inside it, and for teams running code sandboxes who want the same interface to point at a remote kernel. The README states plainly that you can point it at any Jupyter you already run, local or JupyterHub, with no account needed. That sentence is the whole positioning: the project does not ship a notebook server, a kernel, or a hosted compute layer in its open source form. It ships the adapter.

What the server actually is: an MCP front end over an existing Jupyter

The repository is Python, published on PyPI as jupyter-mcp-server, and built on the MCP Python SDK. From v2.0.0 onward it requires mcp>=2,<3; earlier releases require mcp<2. The README is explicit that this SDK bump changes nothing in how you start or configure the server, in the tools, or for connecting MCP clients, because the protocol is negotiated per client. The change is confined to the Python environment. That is a useful design property: the server is a translation layer, and the translation layer's internals are not part of its contract with clients. The tools the README names are notebook-oriented rather than kernel-oriented in the abstract: reading notebooks, writing to them, and executing code. The hosted variant advertises three slash commands in the Claude Code plugin, /datalayer:notebook, /datalayer:run and /datalayer:status, which map to the same three concerns. What the material does not give is a full tool schema, so the exact argument names and return shapes have to be read from the documentation site rather than assumed from the README.

Two ways to run it, and the version pinning that decides which one works

The self-hosted path starts with pip. The README gives the install command as pip install "jupyter-mcp-server>=1.5.0" "code-sandboxes>=1.1.1" for current versions, or pip install "jupyter-mcp-server<1.5.0" "code-sandboxes<=1.0.9" if you are staying on an older server. The reason is a rename: the sandbox variant jupyter became jupyter-server in code-sandboxes 1.1.1, and the two packages have to agree on the name. The failure mode is documented and unpleasant. An older server with a newer code-sandboxes installs cleanly and then fails on the first execution with Unknown sandbox variant: jupyter. Nothing warns you at install time. This is the single most concrete operational constraint in the material, and it is the reason the README carries a hot-fix badge about pinning code-sandboxes to match jupyter-mcp-server. The second path is the hosted endpoint at https://mcp.datalayer.run/mcp, which the README describes as having no process to run, with browser sign-in and server-side continuation of work after the agent disconnects. For Claude Code there is a plugin path: /plugin marketplace add datalayer/jupyter-mcp-server followed by /plugin install datalayer. Configuration keys beyond the install commands are not listed in the excerpt, so treat the documentation site as the source for the server's config surface.

Authentication: OAuth 2.1 scopes versus a personal access token

The README describes a two-layer authorization model, and the separation is the interesting part. Scopes you approve (notebooks:read, notebooks:write, code:execute, data:read) decide what kind of operation an agent may perform. Your own Datalayer permissions still decide which notebooks it may touch. The stated consequence is that an agent can never reach a notebook you cannot. In the OAuth 2.1 flow, an unauthenticated agent is told where to authenticate, opens your browser, and you sign in; the agent receives a token scoped to what you approved and never sees your password. Disconnecting one agent does not affect the others. Personal access tokens remain supported and the README calls them the simpler path for a CLI or a script. That is a real trade-off rather than a marketing line: a PAT is one secret with whatever scope it was issued, while the OAuth flow gives per-agent revocation and an approval step. If you are wiring this into a script, the PAT is less work. If you are handing it to an interactive agent, the scope separation is the thing that keeps notebooks:write from being ambient.

Where it is the wrong tool, and what to use instead

jupyter-mcp-server assumes a Jupyter to connect to. If you have no notebook server, no kernel, and no interest in keeping one alive, this project adds a layer without adding a runtime. It also does not present itself as a sandboxing boundary: the scopes govern operations, and Datalayer permissions govern reach, but the README does not claim that agent-generated code is contained. If your requirement is isolation for untrusted generated code, you are looking at the wrong component. The nearest alternative in the same space is Jupyter's own kernel and messaging protocol accessed directly, or a notebook-aware tool that ships its own execution environment. The difference in approach matters. A tool that bundles its own runtime gives you a controlled environment and no dependency on your existing Jupyter, at the cost of not being able to operate on the notebooks you already have, with the data already mounted, in the kernel that is already warm. jupyter-mcp-server takes the opposite bet: it contributes no compute and instead attaches to yours. That is why the README's claim about pointing at any Jupyter you run is the load-bearing one, and why the project is less useful to someone who has nothing to point at.

Maintenance cost: two packages in lockstep and a major SDK bump

There are two upgrade hazards visible in the README, and both are version-coupling problems rather than feature problems. The first is the code-sandboxes rename described above, which produces a clean install and a first-execution failure. The second is the mcp SDK major version. From 2.0.0 the package pins mcp>=2,<3; before that it pinned mcp<2. The README notes that pip sorts this out because both are pinned in the package, but adds the real constraint: an environment holding another package that still pins mcp<2 has to stay on jupyter-mcp-server<2 until that package moves. So the upgrade path for jupyter-mcp-server is gated by whatever else in your environment depends on the MCP Python SDK. If you are writing an extension or a custom token verifier against the SDK, the release notes list renamed imports, which means extension code is not shielded from the bump the way client-facing behaviour is. On licensing: the project is BSD-3-Clause, a permissive licence that permits use and redistribution with the copyright notice and disclaimer retained. The README also links a sponsorship page and a hosted commercial offering from the same maintainer. That combination is common and not itself a problem, but it is worth knowing that the hosted endpoint and the GPU code sandboxes are commercial surfaces alongside the open source server. Nothing here is legal advice; read the licence text and your own obligations.

Who should adopt it, and what to check before you install

The project fits teams that already run Jupyter or JupyterHub and want an MCP client to work inside those notebooks, and it fits anyone already using Datalayer's sandboxes who wants the same server locally and remotely. It does not fit anyone looking for a managed execution environment, isolation guarantees for untrusted code, or a notebook product that stands alone. Three things are worth verifying before you commit. First, the compatibility table: confirm your jupyter-mcp-server version against the code-sandboxes range in the README, because the mismatch fails at execution rather than install. Second, run a dependency check for other packages pinning mcp<2, since that determines whether you can move to 2.x at all. Third, decide the auth path up front, because a script using a personal access token and an interactive agent using the OAuth flow have different revocation properties. The README's own framing is the honest summary: free and open source, point it at any Jupyter you already run. If you cannot complete that sentence with a Jupyter you run, the server has nothing to attach to.

Editorial conclusion

Adopt it if you already run Jupyter or JupyterHub and want an MCP client to drive real notebooks rather than a chat scratchpad; skip it if you need a sandboxed execution environment the project does not provide, or if you cannot keep jupyter-mcp-server and code-sandboxes version-matched. Before installing, check the compatibility table for your server version, confirm whether your environment pins mcp<2 through another package, and decide between a personal access token and the OAuth 2.1 flow.

Official sources

1. datalayer/jupyter-mcp-server on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases