# 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

```bash
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:

```bash
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`:

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

## quick sanity check without a full MCP client

```python
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