A small terminal debugger for Model Context Protocol
servers. No npm install, no build step — just Node 18+ and a folder of
plain JavaScript.
mcpx connect "node my-server.js"
A keyboard-driven TUI that connects to an MCP server (stdio or HTTP/SSE), lists its tools, resources, and prompts, lets you invoke them, and shows the response in a syntax-coloured JSON tree. You can also record a session to a small text file and replay it later as a regression test.
- Not a replacement for the official browser-based inspector. They're complementary; mcpx is for the times you'd rather stay in the terminal.
- Not an LLM client. mcpx doesn't connect to Claude/GPT — it talks to the MCP server directly and renders the protocol traffic.
- Not a server scaffolder. If you need
mcpx new my-server, that's a different project.
- People building MCP servers who want a fast feedback loop without alt-tabbing to a browser tab.
- Teams running MCP servers in production who want a one-line CI step that fails on response drift.
- Anyone reviewing a colleague's MCP server change and wanting to see, in a PR diff, exactly what the wire output now looks like.
If you don't write or operate MCP servers, this isn't for you. Tools should be sharp.
Requires Node 18 or newer. Clone and go:
git clone https://github.com/your-username/mcpx.git
cd mcpx
node bin/mcpx --helpWant it on your PATH?
chmod +x bin/mcpx
ln -s "$(pwd)/bin/mcpx" ~/.local/bin/mcpxOr via npm (no extra deps will be installed — there aren't any):
npm install -g .Three demo servers ship with the repo so you don't need your own to play around:
node bin/mcpx connect "node examples/math-server.mjs"
node bin/mcpx connect "node examples/echo-server.mjs"
node bin/mcpx connect "node examples/time-server.mjs"Once the TUI is open: ↓ to highlight a tool, i to fill in arguments,
Enter to invoke. Press ? for the full keymap.
A few habits make mcpx pay for itself quickly.
Record from day one. Whenever you're working on a server, hit R early
and S before you log out. Recordings cost nothing and the value compounds.
Drop replay in CI. Treat one of those recordings as a fixture:
- run: node bin/mcpx replay tests/regression.mcpxreplay exits non-zero on any drift. The .mcpx file lives in your repo
and shows up in PR diffs so reviewers see what the protocol actually does.
Use diff before/after a refactor. Record once on the old code, once on
the new code, then mcpx diff old.mcpx new.mcpx. Beats vibes-based code
review.
Keep secrets out of recordings. Fields named token, api_key,
secret, password, etc. are redacted automatically before recordings hit
disk. Still — eyeball your recordings before sharing them.
mcpx open the TUI
mcpx connect "<command>" spawn an MCP server over stdio
mcpx connect --http <url> connect over HTTP/SSE
mcpx replay <file.mcpx> rerun a recording, exit 1 on drift
mcpx diff <a.mcpx> <b.mcpx> line-level diff between two recordings
mcpx --help the full reference
Tab / Shift-Tab cycle tabs
1..4 jump to tab
↑ ↓ k j move cursor
PgUp PgDn scroll detail pane
Ctrl-N / Ctrl-P switch active server
Space / x collapse a JSON node
Enter invoke / read / get
i open invoke form
c connect a new server
R / S start record / save record
P / D pick recording to replay / diff
/ search
: command palette
? help overlay
q quit
node test/run.mjsSpawns the example servers and exercises the client, recorder, replay, and TUI render pipeline against them. No mocks, no framework.
bin/mcpx launcher
src/main.mjs CLI entry
src/mcp/ MCP client + transports
src/recorder/ .mcpx format, recorder, replay, diff
src/tui/ TUI engine and views
examples/ demo MCP servers
docs/DESIGN.md design rationale
docs/PROTOCOL_NOTES.md quirks I ran into building this
test/ no-deps test suite
recordings/ sample .mcpx files
MIT. See LICENSE.