Repl

crates.io docs.rs CI license

An interactive terminal REPL for any MCP server. The server's surface is the command set: every tool becomes a top-level command with schema-coerced key=value arguments, prompts and resources get built-ins, tab completion is powered by the server itself where the protocol allows, and the command table refreshes live when the server's surface changes.

It also runs a single command and exits, so the same binary is a scriptable MCP client for a shell script, a CI job, or an agent.

Install

On macOS or Linux, install the prebuilt x86_64 or arm64 binary with:

curl -fsSL https://raw.githubusercontent.com/joshrotenberg/mcp-repl/main/install.sh | sh

It verifies the release's published checksum before unpacking, and installs to ~/.local/bin unless MCP_REPL_INSTALL_DIR says otherwise. Reading a script before piping it to a shell is the better habit, and this one is short. On Windows, download the x86_64-pc-windows-msvc.zip from the latest release, extract mcp-repl.exe, and place it on PATH.

Or install from source on any supported platform:

cargo install mcp-repl

Or run it without installing anything:

docker run --rm -it ghcr.io/joshrotenberg/mcp-repl --demo

The image suits --http and --demo; a stdio server would have to live inside it, and OAuth has no credential store there. See docs/connecting.md for what differs.

Completions and a man page come from the binary itself, and ship in the release archives. The man page includes both startup options and the same REPL built-in reference shown by help <command>:

mcp-repl --completions zsh > ~/.zfunc/_mcp-repl
mcp-repl --man > /usr/local/share/man/man1/mcp-repl.1

One call, no prompt

The prompt is one of two ways to use this. -e runs a command and exits:

$ mcp-repl --demo -e 'convert value=100 from=celsius to=fahrenheit'
212.00
[0ms]

--json makes stdout NDJSON, one value per command, and silences the banner and the timing line. Each value is the tool result as the protocol returns it:

$ mcp-repl --demo --json -e 'convert value=100 from=celsius to=fahrenheit'
{"content":[{"type":"text","text":"212.00"}]}

$ mcp-repl --demo --json -e 'convert value=100 from=celsius to=fahrenheit' \
    | jq -r '.content[0].text'
212.00

A one-shot run cannot block waiting for a person. Under -e, elicitation and sampling both default to decline, so a server that asks a question gets an immediate refusal instead of hanging the caller. --timeout bounds everything else, and exit statuses are typed, so a tool error (3) is distinguishable from an empty result.

See docs/scripting.md for tasks, waiting on them, and schema contracts.

Start here

Open the REPL first and choose a server from inside it:

mcp-repl

mcp-repl> connect demo

connect also accepts an HTTP URL, saved profile, imported path.json:entry, or stdio command. Run it again to switch servers without losing command history or global aliases. Captured variables, background task ids, resource subscriptions, and profile-scoped aliases are cleared because they belong to the server being left. The direct forms connect straight to one server, which is what a script or a single-server session wants:

mcp-repl --demo

Then point it at something real. mcp-repl speaks stdio and streamable HTTP, reads the .mcp.json files other clients use, and can keep named profiles of its own:

mcp-repl --http https://cratesio-mcp.fly.dev/   # a public server to try
mcp-repl -- ./my-server --stdio                 # spawn a stdio server
mcp-repl --scan                                 # what other clients have configured
mcp-repl .mcp.json:local                        # one entry from a client config
mcp-repl --server prod                          # a saved profile

Inside, help lists the built-ins, help <command> gives usage, detail, and runnable examples, and find <word> searches the server's surface and the REPL's own commands. If a tool and built-in share a name, the bare spelling is rejected as ambiguous; tool <name> selects the server tool and builtin <name> selects the REPL command.

See docs/connecting.md for auth, OAuth, profiles, and config imports.

What it is good at

Everything a tool declares, at the prompt. Tab completes command names, argument names, and enum values, reading them out of the tool's inputSchema and following $refs into $defs the way a generated schema is shaped. describe shows the annotations, the schema, and a line you can copy and run.

The parts of MCP other clients skip. Server-driven completion (completion/complete), elicitation, and sampling all work here, and SEP-2663 tasks run with a shell-style trailing &. When a server asks the operator a question, the REPL says which server is asking and flags fields whose names look like credentials before anything is typed. --demo has a tool for each: sign_in asks you a question, summarize asks your client's model for a completion.

A shell, not just a viewer. Capture a result into a variable, reference it in a later command, filter it with a path, alias a command you type often, and time a tool with bench. wire on traces redacted JSON-RPC frames to stderr, and last reprints the previous exchange whether or not tracing was on.

Scriptable. -e/--exec runs commands and exits; --json makes stdout NDJSON, one value per command, with typed exit statuses so a failure is distinguishable from an empty result.

The shell model

mcp-repl is a shell whose command set is the connected server. That is the organizing idea, and most of the grammar arrived by following it rather than by deciding it:

mcp-repl	the shell equivalent
name = command, then $name.path[0].field	variables
command | path	a pipe into a filter
command &, jobs, wait, cancel	job control
alias, unalias	aliases
for $var in $list: command	for
tool <name>, builtin <name>	command and builtin, for shadowed names
history, Ctrl-R	history
-e with typed exit statuses	a non-interactive shell

Naming the model is useful because it settles scope questions in advance rather than one at a time. Things that are shell constructs fit: && and ||, redirecting output to a file, reading commands from a file, a richer path selector. Things that are programming-language constructs do not: functions, arithmetic, if, string manipulation, an embedded scripting language.

That boundary is not a limitation to be worked around later. A shell's own answer to a task that outgrows it is to hand off to a real language, and here that language already exists: an MCP SDK in Python or TypeScript, called from a real program. Growing a second one inside this prompt would cost a whole ecosystem to arrive somewhere worse.

The known exception is small and worth stating. An external script cannot hand a value back to a live prompt you are sitting at, so anything whose entire point is interactive continuity belongs here rather than in a script. Nothing else does.

for is the worked example. It ships with no conditional form on purpose: iteration is a shell construct, but if is what would force expressions, comparison, and truthiness into the language. When the need is "only the high-priority ones," the answer is a more capable path selector, which is bounded, rather than a test inside the loop, which is not.

Documentation

Connecting	transports, bearer and OAuth auth, profiles, importing client configs, reconnecting, timeouts
The command set	every built-in, completion, aliases, capture and filtering, subscriptions, elicitation, output rendering
Scripting	--exec, NDJSON, exit statuses, schema contracts
Debugging a server	wire tracing, last, bench
Release pipeline	maintainer gates, native artifacts, failure and retry behavior

Other MCP clients

mcp-repl is an interactive shell for driving one server at a time, with connect switching the live target without leaving the prompt. The neighbours are shaped differently, and which one fits depends on what you are doing:

mcpc	TypeScript	A shell-oriented client built around named sessions that persist across invocations, with broad protocol and OAuth support for automation and agents.
MCP Inspector	TypeScript	The official developer tool, with web, scriptable CLI, and interactive TUI surfaces backed by one client core.
mcp-probe	Rust	A ratatui debugging dashboard for interactive execution, protocol analysis, validation, and timing.
mcptools	Go	A broader toolkit with one-shot commands, an interactive shell and web UI, plus mock, proxy, and guard modes.

mcp-repl's particular shape is the line editor: the connected server's live tool surface becomes top-level commands with schema-driven completion and coercion. The same prompt handles prompts, resources, capture and filtering, aliases, elicitation, sampling, server-driven completion, and SEP-2663 tasks; the clients above overlap with different parts of that protocol surface but organize the workflow differently.

Protocol versions

The binary compiles both the stable and the final lifecycle, and the choice is explicit. --protocol stable (the default) uses initialize/notifications/initialized; --protocol 2026-07-28 (alias final) uses server/discover and sends the selected protocol metadata on every request. Keeping stable as the default means upgrading mcp-repl cannot silently change how it talks to a server you already use.

Contributing

Bug reports and pull requests are welcome. cargo test runs the unit tests plus a black-box suite that launches the built binary against a fixture server over stdio and localhost HTTP, on both lifecycles. See CONTRIBUTING.md.

The recordings above are generated with vhs from the tapes in docs/tapes:

./scripts/recordings.sh

License

MIT or Apache-2.0, at your option.