mcp-repl
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.
Install
On macOS or Linux, install the prebuilt x86_64 or arm64 binary with:
|
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:
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>:
Start here
Open the REPL first and choose a server from inside it:
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 original direct forms remain useful
for scripts and one-server sessions:
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:
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.
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:
License
MIT or Apache-2.0, at your option.