pyrepl-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PYREPL_CWD | No | Kernel working directory (CLI flag: --cwd). Defaults to the first of: --cwd, the first file:// root reported by the host, or the server's own working directory. | |
| PYREPL_PYTHON | No | Python interpreter for the kernel (CLI flag: --python). Set to "auto" to use $VIRTUAL_ENV/bin/python, then ./.venv/bin/python, then the server interpreter. Defaults to the server interpreter. | |
| PYREPL_RESTORE | No | Set to 1 to auto-save and auto-restore the namespace per working directory (CLI flag: --restore). | off |
| PYREPL_TIMEOUT | No | Seconds a call waits before the cell detaches (CLI flag: --timeout). Keep it below the host's tool timeout. | 45 |
| PYREPL_STATE_DIR | No | Directory where snapshots are stored (CLI flag: --state-dir). Defaults to $XDG_STATE_HOME/pyrepl-mcp or ~/.local/state/pyrepl-mcp. | |
| PYREPL_MAX_OUTPUT | No | Response output cap in characters (CLI flag: --max-output). One third head and two thirds tail are kept. | 30000 |
| PYREPL_MAX_TIMEOUT | No | Upper bound for the per-call timeout argument (CLI flag: --max-timeout). | 600 |
| PYREPL_RESTORE_TTL | No | Ignore auto-snapshots older than this many seconds (CLI flag: --restore-ttl). | 604800 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
pyrepl provides one tool, ipython: a persistent Python kernel whose variables, imports, cwd and background jobs survive across calls. Prefer it for multi-step work on files, logs and data, keeping intermediate results in variables instead of re-reading them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| ipythonA | 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. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.