kernel-mcp

MCP server that gives an agent a real, persistent Jupyter kernel to work in, instead of the usual "here's a sandboxed exec() with no state" thing most code-tool setups give you. Also throws in two things I was tired of doing by hand while poking at data with an agent:

• dumping a dataframe's schema/nulls/stats without writing df.dtypes for the hundredth time
• checking whether a SQL query is actually going to use an index before letting an agent loose on a real table

Built this over a weekend because I couldn't find an MCP server that did "agent talks to a live kernel" - most of what's out there wraps Slack, Gmail, Notion, that kind of thing. MCP itself is new enough that there's not a ton of prior art for stuff like this yet, so some of the design here is probably non-idiomatic. Feedback welcome.

what it does

Six tools, exposed over stdio via the mcp python SDK:

• run_code(code, timeout=30, kernel="default") - executes in a persistent ipykernel process. State sticks around between calls (same kernel), so the agent can build up a session like a human would in a notebook.
• list_variables(kernel="default") - what's currently in scope, minus the usual ipython noise.
• describe_dataframe(var_name, kernel="default") - shape, dtypes, null counts, quick numeric stats, head(5). pandas only for now.
• explain_query_plan(query, db_path=":memory:") - runs EXPLAIN QUERY PLAN against a sqlite db and hands back the plan rows. Read-only, rejects anything that isn't SELECT/WITH.
• reset_kernel(kernel="default") - nukes and restarts the kernel if it gets wedged (happens if you time out mid-while True or whatever).
• shutdown_kernel(kernel="default") - stops it, next call to run_code spins a fresh one back up.

Everything runs against a locally spawned kernel process (jupyter_client.KernelManager) - no remote kernel gateway, no Docker, no auth. This is meant for local dev / agent sandboxes, not production. Do not point this at anything you don't trust the agent's code to run on.

install

pip install -e .

Needs a python3 jupyter kernelspec available, which ipykernel installs for you (python -m ipykernel install --user if for some reason it's missing - check with jupyter kernelspec list).

running it

As a standalone process talking stdio:

python -m kernel_mcp.server

Point your MCP client (Claude Desktop, whatever) at it. Example config snippet for Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "kernel-mcp": {
      "command": "python",
      "args": ["-m", "kernel_mcp.server"],
      "cwd": "/path/to/kernel-mcp"
    }
  }
}

quick sanity check without a full MCP client

from kernel_mcp import server

server.run_code("import pandas as pd; df = pd.DataFrame({'a':[1,2,None]})")
print(server.describe_dataframe("df"))
server.shutdown_kernel()

how the plumbing works

Talks to the kernel over the raw jupyter zmq protocol via jupyter_client, not through nbclient or notebook execution - didn't need a notebook doc model, just wanted request/response against a running kernel. run_code listens on iopub until it sees status: idle for the matching msg id, collecting stream output / execute_result / errors along the way.

For the structured tools (list_variables, describe_dataframe) I inject a small wrapper that builds a __kmcp_val dict/list inside the kernel, dumps it as JSON wrapped in a marker string, then parse it back out of stdout on this side. Kind of hacky but it means the profiling logic runs in the kernel's process against the actual objects, instead of me trying to pull dataframe internals across the wire some other way. If your df has some extremely weird custom dtype this JSON round-trip might choke on it - not handled yet.

known gaps / TODO

• only supports one kernel type (python3) right now, no R/Julia even though jupyter_client doesn't care either way
• describe_dataframe is pandas-only, polars would probably need its own branch, haven't gotten to it
• timeouts call interrupt_kernel() which works for normal python but won't save you from a genuinely stuck C extension
• no tests beyond the manual scripts in tests/, should probably wire up pytest at some point
• concurrent calls to the same kernel session will race on the zmq channel, there's no lock. fine for a single agent working sequentially, not fine if you're fanning out

license

MIT, do whatever