pyrepl-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pyrepl-mcp load every .log under ./logs into a dict and tell me which have ERROR"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
pyrepl-mcp
An MCP server with a single tool, ipython, backed by a persistent Python kernel. It plugs into existing coding-agent CLIs (Antigravity CLI agy, Claude Code, Codex CLI) over stdio and keeps their auth, TUI and slash commands as they are.
Variables, imports, the working directory, os.environ, asyncio tasks and background shell jobs persist across tool calls, across turns and across context compaction. The model can load a log once and filter it many times, define a helper and reuse it, or start a build and check on it later. It does not have to re-read files and re-run commands every turn.
How it works
The MCP server is a small supervisor that never runs user code. Cells run in a separate kernel process that does not own the MCP stdout, so nothing user code prints (C extensions and child processes included) can corrupt JSON-RPC framing. A runaway cell cannot wedge the server: when a call reaches its deadline it returns, and the cell keeps running in the background.
Requirements: Python 3.11 or newer, uv, macOS or Linux.
Related MCP server: kernel-mcp
Install
uv tool install git+https://github.com/zsxawerdu/pyrepl-mcpThis puts a pyrepl-mcp executable in ~/.local/bin (run uv tool update-shell if that is not on your PATH). Upgrade with uv tool upgrade pyrepl-mcp, remove with uv tool uninstall pyrepl-mcp.
From a checkout, mise run install (uv tool install --editable --force .) installs the same executable but tracks the working tree. To run without installing, use uvx --from git+https://github.com/zsxawerdu/pyrepl-mcp pyrepl-mcp or uv run --project /path/to/pyrepl-mcp pyrepl-mcp. Do not use uv run --directory: it changes the working directory the kernel inherits.
The kernel runs on the server's own interpreter by default. Pass --python auto to run cells in the project's virtualenv instead ($VIRTUAL_ENV, then ./.venv), so project packages can be imported. The kernel needs only the standard library; dill is needed only for save()/load().
Install with an LLM
Paste this into your coding agent (agy, Claude Code, Codex):
Install the pyrepl-mcp MCP server for this CLI by following the "Instructions for LLM agents"
section of https://github.com/zsxawerdu/pyrepl-mcp/blob/main/README.mdInstructions for LLM agents
You are installing pyrepl-mcp for the user. Do the steps in order and report what you changed.
Check
uv --version. If uv is missing, stop and ask the user to install it (https://docs.astral.sh/uv/); do not install it yourself.Run
uv tool install git+https://github.com/zsxawerdu/pyrepl-mcp, then confirmcommand -v pyrepl-mcpprints a path. If it does not, runuv tool update-shelland use the absolute path fromuv tool dir --binin the next step.Register the server with the CLI you are running in. This edits the user's global config, so tell them which file changes before you do it. Use the command for your host from Register with a host, and apply that section's timeout setting. Register only the host you are running in unless the user asks for more.
Ask the user whether to add the usage rules. If yes, append the contents of docs/AGENTS-snippet.md to the project's
AGENTS.md(Claude Code:CLAUDE.md; agy also readsGEMINI.md). Do not overwrite existing content.Tell the user to start a new session: hosts launch MCP servers at session start, so the tool is not available in the current one.
In the new session, verify with two separate calls:
x = 6*7, thenprint(x). The second must print42.
Do not use sudo, do not install into the project's virtualenv, and do not launch the server with uv run --directory.
Use it
Once registered, start a new session and ask for work in plain language. The model calls the tool itself; naming it helps at first:
Use ipython to load every *.log under ./logs into a dict, then tell me which files contain "ERROR".
Now show the ten most common error messages. (reuses the dict, no re-reading)
Run the test suite with bash() in the background and tell me when it finishes.The host's built-in file and shell tools stay available, and the model chooses per step. To make ipython the default for bulk reads, log filtering, multi-file edits and long commands, add docs/AGENTS-snippet.md to your instruction file (see below). State lasts for the session and survives /compact; ask the model to save() before quitting, or run with --restore, to keep it across sessions.
Register with a host
The examples assume pyrepl-mcp is on your PATH (see Install). Each snippet raises the host's per-call limit to 660 s, so cells can use timeout up to the 600 s --max-timeout. See docs/hosts.md for the details and their sources.
Antigravity CLI (agy)
agy mcp add pyrepl pyrepl-mcpThis writes ~/.gemini/config/mcp_config.json. Then edit the entry to raise the timeout (the default is 180 s per call):
{
"mcpServers": {
"pyrepl": {
"command": "pyrepl-mcp",
"timeoutSeconds": 660,
"tools": { "ipython": { "eager": true } }
}
}
}For a single project, put the same JSON in <workspace>/.agents/mcp_config.json. The server marks ipython with _meta antigravity/alwaysLoad, so agy loads it eagerly as mcp_pyrepl_ipython; "eager": true does the same from the config side. A lazy tool would be called through call_mcp_tool, with results over 10 KB saved to a file the model must read in an extra step.
Claude Code
claude mcp add-json -s user pyrepl '{"type":"stdio","command":"pyrepl-mcp","timeout":660000,"alwaysLoad":true}'Use -s project to write .mcp.json in the project root (shared, needs one-time approval) or -s local for this project only. The short form is claude mcp add -s user pyrepl -- pyrepl-mcp. The tool is shown as mcp__pyrepl__ipython. alwaysLoad in the entry, like the _meta anthropic/alwaysLoad the server sets on the tool, keeps it out of deferred tool search. Interactive Claude Code moves MCP calls running longer than 120 s into the background (CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS changes this).
Codex CLI
codex mcp add pyrepl -- pyrepl-mcpThen add the timeouts in ~/.codex/config.toml. Codex defaults to 60 s per tool call and 10 s for start-up:
[mcp_servers.pyrepl]
command = "pyrepl-mcp"
tool_timeout_sec = 660
startup_timeout_sec = 30For a single trusted project, use .codex/config.toml in the project. The tool is shown as mcp__pyrepl__ipython.
Teach the model when to use it
Paste docs/AGENTS-snippet.md into AGENTS.md, GEMINI.md or CLAUDE.md. It tells the model to prefer ipython for bulk reads, log filtering, multi-file edits, stateful helpers and long-running commands, and when to keep using the built-in tools. For agy, docs/hosts.md has a PreToolUse hook that steers file-reading shell commands to ipython.
Working directory
The kernel starts in the first of:
--cwd DIRthe first
file://root the host reports, when it supports MCP roots (Claude Code does; agy most likely does)the server's own working directory, which all three hosts set to the directory the CLI was started in
os.chdir() inside a cell persists, and bash() commands run in the kernel's current directory.
Flags
Flag | Env | Default | Meaning |
|
| server interpreter | interpreter for the kernel; |
|
| see above | kernel working directory |
|
| 45 | how long a call waits before the cell detaches; keep it below the host's tool timeout (Codex: 60 s unless raised) and Claude Code's 120 s auto-background |
|
| 600 | upper bound for the per-call |
|
| 30000 | response cap; one third head, two thirds tail |
|
| off | auto-save and auto-restore the namespace per working directory |
|
| 604800 | ignore auto-snapshots older than this |
|
|
| where snapshots live |
Flags go after the command in the host config, for example "args": ["--python", "auto", "--restore"].
The tool
ipython(code: str, timeout: float = <--timeout>) -> textCells behave like IPython: top-level await works, and a non-None trailing expression is shown as Out[N]: ... and bound to _. A traceback is a normal result, not a tool error. Every response ends with a one-line footer listing live names, most recent first:
[env: cwd=/work/proj | log: list[40000], errors: list[12], find_flaky(), df: DataFrame(1000, 8), np(module) | bash: 1 running]Control inputs
| Effect |
Python source | run it and wait up to |
| wait for a running cell and collect its output; when idle, return any uncollected background output, or |
| interrupt the running cell (KeyboardInterrupt, or cancellation if it is awaiting) |
| kill the kernel and start a fresh one; all state is lost |
| kernel pid, Python, cwd, uptime, running cell, |
When a cell outlives timeout, the call returns what it has so far plus [cell N still running after Ts — ipython("") waits and collects, ipython("%interrupt") stops it]. The cell keeps running, and its later output is delivered by the next call. Output from asyncio tasks of finished cells, and raw writes made while the kernel is idle, show up under [background output] at the top of the next response. If the kernel dies mid-cell, the response ends with [kernel died (exit code X) while running cell N: all state is gone; the next call starts a fresh kernel] and no footer; the next call starts a new kernel and begins with [kernel restarted (exit code X): previous state is gone].
Helpers
These are injected into the namespace; help(bash) and similar work.
Helper | Behaviour |
| start |
| full, uncapped listing of user names |
| snapshot the namespace to disk with dill and return a report |
| merge a snapshot back into the namespace and return a report |
| delete all user names |
A bash() handle offers .pid, .command, .running, .returncode, .timed_out, .poll(), .tail(n=20) (never blocks), .output(timeout=None) (waits for exit), .wait(timeout=None), .kill(), and await h. Its repr shows the status and the last ten lines. stdout and stderr are merged, stdin is /dev/null, and the command sees the kernel's current os.getcwd() and os.environ. The first 256 KiB and the last 1 MiB of output are kept. When timeout expires, or on .kill(), the whole process group gets SIGTERM, then SIGKILL two seconds later. Every group is killed when the kernel or the server shuts down, so dev servers do not outlive the session.
h = bash("pytest -x -q")
hprint(h.tail(30)) if h.running else print(h.output()[-3000:])Persistence
Within a host session: everything persists for as long as the host keeps the server process, which is for the whole CLI session. That includes turns,
/compactand, in agy and Claude Code, subagents (they share the one kernel). The server is not told about compaction; the[env: ...]footer is how the model relearns what it has.Across sessions: quitting the CLI ends the kernel, and
--resume/--continuestarts a fresh one.save()/load()keep snapshots under--state-dir, one directory per working directory. Each variable is pickled separately with dill. Unpicklable or oversized values (more than 64 MiB each, 512 MiB in total) are skipped and listed, and modules are stored as imports. With--restore, the namespace is saved automatically on clean shutdown and every five minutes after a cell. It is restored when the next kernel starts in the same directory, if the snapshot is younger than--restore-ttl.%restartneither saves nor restores.
Limitations
No wake-up. An MCP server cannot start a model turn. When a detached cell or a
bash()job finishes, nothing tells the model; it has to callipython("")or check the handle.One cell runs at a time. New code sent while a cell runs is refused, not queued.
No stdin:
input()sees EOF andbash()commands get/dev/null. There is no TTY, so interactive programs do not work.Output is capped at
--max-outputcharacters per response (head and tail kept). Print summaries, not whole objects.The host's own tool timeout still applies. With a host limit shorter than the call's
timeout(a model asking fortimeout=300on Codex at its 60 s default, for example), the host reports a timeout error while the cell keeps running in the kernel. The nextipython("")still collects its output.Snapshots restore data, not live resources: open files, sockets, threads, running tasks and
bash()handles are skipped.Code runs with your user's full permissions, outside any sandbox the host applies to its own shell tool.
macOS and Linux only.
Available Tools
1 toolipythonA
Run Python in a persistent kernel. Variables, imports, cwd, os.environ and asyncio tasks persist across calls. Top-level await works; the last expression is shown as Out[N]. Each reply ends with [env: ...] listing your live names. Helpers: bash(cmd, timeout=600) starts a shell command in the background and returns a handle h: h.running, h.tail(n), h.output() (waits for exit), await h, h.wait(), h.kill(). env() lists all names; save(name)/load(name) snapshot variables to disk; reset() deletes them. A cell still running after timeout (default 45s, max 600s) keeps running detached and the call returns. Then: code "" waits and collects its output (and any background output); "%interrupt" stops it; "%restart" kills the kernel (state lost); "%status" shows kernel, running cell and bash jobs. New code is refused while a cell runs. Output is capped at ~30000 chars (head and tail kept): print slices, counts or summaries of large data, not whole objects.
Inputs: code (required), timeout.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
There is only one tool, so there is no possibility of selecting the wrong one. The only ambiguity is internal (passing an empty string to collect output, or magic strings like %interrupt/%restart/%status), which is a mode overload inside a single tool rather than a boundary between tools.
With a single tool named 'ipython', there is no inconsistency to speak of, and the name accurately signals a persistent IPython kernel. It does not follow a verb_noun pattern, but nothing else exists to pattern-match against, so the deviation is inconsequential.
For a code-execution server, one entry point is the correct granularity: bash, env, save/load and kernel control are deliberately exposed as in-kernel helpers rather than separate tools, avoiding redundancy. It sits just below the typical 3-15 range, and those helpers are discoverable only via the description rather than as first-class tools.
Arbitrary Python execution plus background bash handles, snapshot save/load, and kernel lifecycle (%interrupt, %restart, %status) cover the realistic workflow with no dead ends. Minor gaps: no way to enumerate or delete saved snapshots, no named sessions or multiple kernels for parallel work, and no explicit per-call timeout parameter surfaced in the tool schema.
Maintenance
Related MCP Connectors
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Build Apps and run code in 30 languages — sandboxed, with persistent sessions for agent loops.
Persistent Linux microVMs for agents: root, internet, sub-second resume and a public URL.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to execute Jupyter notebook cells with persistent kernel state, output persistence, and structured JSON control surface.2-
- FlicenseNot gradedqualityDmaintenanceProvides a persistent Jupyter kernel for executing code, inspecting variables and dataframes, and checking SQL query plans, enabling agents to work with stateful Python sessions.-
- AlicenseBqualityFmaintenanceEnables IDE and DeepSeek Harness agents to control an agent-kernel instance over stdio, exposing tools for auth, projects, assignments, runs, scheduler nudges, and executor settings.12MIT
- AlicenseAqualityCmaintenanceConnects to an existing IPython kernel for persistent Python code execution, preserving variables and state across calls. It enables AI agents and clients to share a live kernel for interactive coding, execution, kernel status checks, and interrupts.4MIT