Skip to main content
Glama
Sign In
ipython2-mcp

ipython2-mcp

by ledror
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

Related MCP server: PyKernel MCP

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.

Available Tools

6 tools
ipython_completeA

Tab-complete a partial expression against the session's live namespace, e.g. df.gr or os.path.jo. The cursor is taken to be at the end of the prefix. Use this to discover attributes and names that actually exist before running code.

Inputs: name (required), prefix (required).

ipython_install_depsA

Install the kernel dependencies (IPython, ipykernel, jupyter_client) into a Python 2.7 interpreter using its own python -m pip, making it usable with ipython_start. Call this when ipython_start reports missing dependencies. Requires network access and writes to that interpreter's site-packages.

Inputs: python_path (required), timeout_ms.

ipython_runA

Run code in a session and return the output transcript, exactly as a terminal would show it. A Python exception is a normal result: you get the traceback. Executions within a session are strictly serial, so a second call while one is running is rejected. On timeout the cell is interrupted and you get the partial output. Do not hold long-running work in a cell -- start it in a thread from your own code. This is a real IPython shell: use obj? and obj?? for signatures and source, %whos to list the namespace, and %history for past input.

Inputs: code (required), name (required), timeout_ms.

ipython_startA

Start a named Python 2 IPython session. python_path must be an absolute path to a Python 2.7 interpreter with this project's requirements installed -- pass a virtualenv's interpreter to work inside that virtualenv. Multiple named sessions can run at once and are fully independent.

Inputs: name (required), python_path (required), cwd, env.

ipython_statusA

List every session with its state (idle, busy, or dead), kernel pid, Python version, working directory, uptime, and execution count. A dead session keeps its name until ipython_stop clears it.

Inputs: no named parameters.

ipython_stopA

Stop a session, kill its kernel, and free the name. Always works, including while a cell is executing -- this is the escape hatch for a wedged session. The namespace is lost.

Inputs: name (required), timeout_ms.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A4.3/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool maps to a distinct lifecycle action: dependency install, session start, stop, status, code execution, and tab-completion. There is no overlap or ambiguity between tool purposes.

    Naming Consistency5/5

    All tools share the ipython_ prefix and use clear snake_case verb-based suffixes: install_deps, start, stop, status, run, complete. The naming pattern is fully consistent and predictable.

    Tool Count5/5

    Six tools is well-scoped for a session-management server. Every tool covers a necessary part of the workflow without redundancy or bloat.

    Completeness5/5

    The toolset covers the full lifecycle: dependency setup, session creation, inspection, execution, completion, and cleanup. Restarting a session is possible by combining stop and start, so there are no obvious dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Sandbox Agent

      eduresser
      A
      license
      A
      quality
      D
      maintenance
      Enables code execution in isolated Docker containers with persistent IPython, Node.js, or R kernels, supporting file import/export and cross-session transfers via MCP tools.
      6
      MIT

    • Python REPL MCP Server

      piplin-es
      A
      license
      Not graded
      quality
      D
      maintenance
      Provides a persistent Python REPL session as a tool for executing code, managing files, installing packages, and initializing projects via the MCP protocol.
      1
      MIT

    • mcp-async-repl

      jnotsknab
      A
      license
      Not graded
      quality
      D
      maintenance
      Async Python REPL + Shell execution for MCP. Provides persistent state, background jobs, interactive input() bridging, and crash isolation in a single server.
      1
      Apache 2.0