ipython2-mcp

This project allows an agent to run Python 2 IPython sessions via an MCP.

The MCP server is written in TypeScript. Each session is a Python 2 broker process owning one IPython kernel process, driven over JSON-RPC on stdio.

Tools

tool	params	what it does
ipython_install_deps	python_path, timeout_ms?	pip-installs the kernel dependencies into a Python 2.7 interpreter
ipython_start	name, python_path, cwd?, env?	starts a named session on the given Python 2.7 interpreter
ipython_stop	name, timeout_ms?	stops a session and frees the name
ipython_status	—	one line per live session
ipython_run	name, code, timeout_ms?	runs code, returns the transcript
ipython_complete	name, prefix	tab completion

Introspection, namespace listing, and history go through IPython itself (var?, var??, %whos, %history) rather than dedicated tools.

Setup

Install and build the server:

npm install
npm run build

That produces dist/ipython2-mcp.js — a single self-contained file. Register it with your MCP client as node <repo>/dist/ipython2-mcp.js.

The repo's .mcp.json already does that with a path relative to the repo root, so an MCP client started there picks the server up with no further configuration. Run npm run build first: dist/ is not committed.

To distribute, ship dist/ipython2-mcp.js together with the python/ directory beside it — those scripts are run by the user's Python 2 interpreter, so they cannot be bundled into the JS.

Then point python_path at any Python 2.7 interpreter — a venv's interpreter is the intended use. It needs the kernel dependencies, which the agent can install for itself with ipython_install_deps, or you can do by hand:

<py2>/python -m pip install -r python/requirements.txt

No kernelspec registration is needed; the kernel is launched with that interpreter directly.

SKILL.md is an agent-facing guide to working in the session; install it into .claude/skills/ if you want your agent to have it.

Distribution

dist/ipython2-mcp.js is committed, so users need nothing but node — no npm install, no TypeScript toolchain. Two things ship: that file and the python/ directory beside it. Everything else in the repo is development-only.

If you change src/, rebuild and commit the bundle in the same commit:

npm run build          # tsc -> build/, esbuild -> dist/ipython2-mcp.js
npm run check:bundle   # fails if the committed bundle is stale; wire into CI

python/ must remain a sibling of dist/ — the server resolves the broker relative to its own location. See ARCHITECTURE.md for the plugin layout and .mcp.json snippet.

Tests

npm test                                                   # TypeScript
<py2>/python -m pip install -r python/requirements-dev.txt
<py2>/python -m pytest python/tests                        # broker, against a real kernel
PYTHON2=<py2>/python npm run test:e2e                      # smoke, needs a build first

See ARCHITECTURE.md for the full design and the reasoning behind it.