MCP tools from the command line. Zero context overhead.
Here for the auto-sprint? Check out the sprint skill — the autonomous pipeline that develops this repo.
Many MCP servers inject 15,000+ tokens of tool definitions into every Claude Code conversation — every message, every subagent. The gh CLI costs 0 tokens when unused.
mcp-cli gives you the same MCP tools via Bash: discoverable, pipeable, composable, and invisible until needed.
$ mcx my-server search '{"query":"sprint planning"}' | jq '.results[].title'
"Q1 Sprint Planning"
"Sprint Planning Template"
"Sprint Planning Best Practices"
$ mcx another-server get_datetime '{}'
2026-03-02T21:48:22.122294+00:00
$ mcx grep page
getPage my-server Get a page by ID
searchPages my-server Search pages
createPage my-server Create a new page
...
14 tool(s)One-line installer (macOS/Linux):
curl -fsSL https://github.com/theshadow27/mcp-cli/releases/latest/download/install.sh | shInstalls mcx, mcpd, and mcpctl to ~/.mcp-cli/bin and adds it to your PATH.
From source (requires Bun):
git clone https://github.com/theshadow27/mcp-cli.git
cd mcp-cli
bun install
bun run build # binaries in dist/mcx upgrade # install latest release
mcx upgrade --check # check without installingmcp-cli reads your existing Claude Code configuration — ~/.claude.json and .mcp.json. If Claude Code can see a server, so can mcx.
No extra setup. No duplicate config. Just works.
You can also add servers in ~/.mcp-cli/servers.json for standalone use.
mcx call server tool '{...}'
|
+-> mcpd (daemon) auto-starts on first call, stays alive 5min
| +-> server-pool persistent connections (stdio, SSE, HTTP)
| +-> auth OAuth/PKCE + macOS Keychain (reads Claude Code tokens)
| +-> SQLite tool cache, usage stats, auth tokens
|
+-> stdout (JSON) pipe to jq, scripts, other tools
The mcx CLI is a thin client. The mcpd daemon manages connections, auth, and caching over a Unix socket. First call cold-starts the daemon (~2s); every call after that is instant.
mcx ls # list servers and their status
mcx ls <server> # list tools on a server
mcx info <server> <tool> # show tool schema (TypeScript notation)
mcx grep <pattern> # search tools across all servers
mcx search <query> # search local tools, then registrymcx call <server> <tool> [json] # call a tool with inline JSON
mcx call <server> <tool> @file.json # load args from a file
echo '{"query":"test"}' | mcx call <server> <tool> # pipe from stdin
mcx <server> <tool> [json] # shorthand (skip "call")
mcx call <server> <tool> --jq '.field' # apply jq filter to output
mcx call <server> <tool> --full # bypass output size protectionmcx add --transport stdio <name> -- <cmd> [args] # add stdio server
mcx add --transport http <name> <url> # add HTTP server
mcx add --transport http <name> <url> \
--client-id ID --client-secret SECRET # add with OAuth
mcx add-json <name> '{"type":"http","url":"..."}' # add from raw JSON
mcx remove <name> # remove a server
mcx get <name> # inspect server config and statusOptions for add: --env KEY=VALUE (repeatable), --header "Name: Value" (HTTP/SSE), --scope {user|project|local}, --callback-port PORT.
mcx auth <server> # trigger OAuth flow (opens browser)
mcx config show # show resolved config + sources
mcx config sources # list config file locations
mcx config get <key> # get CLI option or server config
mcx config set <key> <value> # set CLI option or server env var
mcx status # daemon PID, uptime, server states
mcx restart [server] # reconnect server(s)
mcx daemon restart # restart daemon (kills sessions)
mcx daemon shutdown # stop the daemon (alias: daemon stop)
mcx shutdown # stop the daemon (legacy shorthand)
mcx version # show CLI, daemon, and protocol versions
mcx upgrade # install latest release binaries
mcx upgrade --check # check for updates without installing
mcx metrics # show daemon metrics (Prometheus-style)
mcx spans # list trace spans
mcx spans prune # delete exported spans
mcx logs <server> [-f] # view server stderr output
mcx logs --daemon [-f] # view daemon log filemcx install <slug> # install server from MCP registry
mcx install <slug> --as <name> # install with custom name
mcx install <slug> --env KEY=VALUE # install with env vars
mcx registry search <query> # search registry
mcx registry list # list all registry serversmcx import # auto-find .mcp.json in parent dirs
mcx import /path/to/config.json # import from specific file
mcx import --claude # import from Claude Code config
mcx import --claude --all # import all Claude Code projects
mcx add-from-claude-desktop # import all servers from Claude Desktop config
mcx export # export to stdout
mcx export .mcp.json # export to file
mcx export --server <name> # export specific server(s)Spawn and manage headless Claude Code sessions:
mcx claude spawn --task "describe the work" # start a session (non-blocking)
mcx claude spawn -w --task "work in isolation" # start in a git worktree
mcx claude ls # list active sessions (alias: list)
mcx claude send <session> <message> # send follow-up prompt
mcx claude wait [session] # block until session event
mcx claude wait --any # race: session idle or work item event
mcx claude log <session> [--last N] # view session transcript
mcx claude interrupt <session> # interrupt current turn
mcx claude bye <session> # end session (alias: quit)
mcx claude resume <worktree-or-branch> # reattach to orphaned worktree session
mcx claude resume --all # resume all orphaned worktree sessions
mcx claude worktrees # list mcx-created worktrees (alias: wt)
mcx claude worktrees --prune # remove orphaned worktrees + merged branchesSession IDs support prefix matching (like git SHAs). Use --wait on spawn or send to block until Claude produces a result. Use --json on ls or log for machine-readable output.
mcx agent is the unified command for managing non-Claude agent providers (Codex, ACP, OpenCode, Copilot, Gemini):
mcx agent <provider> spawn --task "..." # start an agent session
mcx agent <provider> ls # list sessions for this provider
mcx agent <provider> send <session> <msg> # send a message
mcx agent <provider> wait [session] # wait for session to idle
mcx agent <provider> log <session> # view session transcript
mcx agent <provider> bye <session> # end session
mcx agent <provider> worktrees # list worktrees for this providerSupported providers: codex, acp, opencode, copilot, gemini. Each provider supports the same core subcommands as mcx claude.
Save multi-step workflows as TypeScript scripts:
mcx alias save sprint-board - <<'TS'
const issues = await mcp.projectTracker.searchIssues({
jql: "sprint in openSprints() AND assignee = currentUser()",
fields: ["summary", "status", "priority"]
});
for (const issue of issues.issues) {
console.log(`${issue.key} [${issue.fields.status.name}] ${issue.fields.summary}`);
}
TS
mcx run sprint-board
# or just: mcx sprint-boardmcx alias ls # list saved aliases
mcx alias save <name> <@file | -> # save a script
mcx alias show <name> # print source
mcx alias edit <name> # open in $EDITOR
mcx alias rm <name> # delete
mcx run <alias> [--key value ...] # run with argumentsAlias scripts get a virtual mcp-cli module with:
mcp— proxy object:mcp.<server>.<tool>(args)calls tools through the daemonargs— parsed--key valuepairs from the CLIfile(path)— read a file as stringjson(path)— read and parse a JSON file
Inter-session messaging for coordinating between Claude sessions:
echo "body" | mcx mail -s "subject" <recipient> # send a message
mcx mail -H # list message headers
mcx mail -H -u <user> # list messages for a user
mcx mail --wait --for=<recipient> # block until message arrivesmcx tty open "<command>" # run command in new terminal tab
mcx tty open --window "<command>" # run in new window
mcx tty open --headless "<command>" # run as background process
mcx config set terminal <name> # set preferred terminalSupports: iTerm, Kitty, tmux, WezTerm, Ghostty, Terminal.app. Auto-detects from $TERM_PROGRAM.
Track GitHub issues and PRs through their sprint lifecycle:
mcx track <number> # track an issue or PR by number
mcx track --branch <name> # track a branch (before PR exists)
mcx untrack <number> # stop tracking by number
mcx untrack --branch <name> # stop tracking by branch
mcx tracked # list all tracked work items
mcx tracked --json # machine-readable output
mcx tracked --phase <phase> # filter by phase (impl/review/repair/qa/done)Clone remote content (e.g. Confluence spaces) as local git repos, edit locally, and push changes back:
mcx vfs clone confluence <space> [dir] # clone a Confluence space
mcx vfs clone confluence <space> [dir] --cloud-id <id> # specify cloud ID
mcx vfs pull [dir] # pull remote changes into local repo
mcx vfs push [dir] # push local changes back to remote
mcx vfs push [dir] --dry-run # preview push without applyingAttach annotations to MCP tools — useful for prompt engineering hints or usage reminders:
mcx note set <server>.<tool> "note text" # attach a note to a tool
mcx note get <server>.<tool> # read a note
mcx note ls # list all notes
mcx note rm <server>.<tool> # remove a noteRegister directory roots by name for use with other commands:
mcx scope init [name] # register current dir as a named scope
mcx scope ls # list all registered scopes
mcx scope rm <name> # remove a scopemcx serve # run mcx as stdio MCP server
mcx serve kill <pid> # kill a specific serve instance
mcx serve kill --all # kill all serve instances
mcx serve kill --stale [hours] # kill instances older than N hours
mcx typegen # generate TypeScript types for aliases
mcx completions {bash|zsh|fish} # generate shell completionsmcx serve exposes tools as an MCP server for use in .mcp.json. Set MCP_TOOLS="server/tool,alias" to curate which tools are exposed.
mcpctl # interactive dashboard
# or: bun run packages/control/src/main.tsxTab bar with 5 views — navigate with Tab/Shift+Tab or press 1-5 to jump directly:
- Servers — server list, tool counts, connection states, restarts
- Logs — daemon and per-server log viewer
- Claude — Claude Code session list with transcript viewing
- Mail — message system (coming soon)
- Stats — usage statistics (coming soon)
Add mcp-cli as a Claude Code skill to eliminate context bloat. Instead of injecting dozens of tool definitions (15K+ tokens) into every conversation, Claude calls tools via mcx on demand — 0 tokens at rest.
See skill/SKILL.md for the skill definition.
packages/
core/ Shared types, IPC protocol, config types, env expansion
daemon/ mcpd — background daemon, server pool, auth, SQLite
command/ mcx — CLI entry point, output formatting, alias runner
control/ mcpctl — React/Ink TUI dashboard
- Runtime: Bun (build, test, compile, SQLite)
- Prod dependencies:
@modelcontextprotocol/sdk,zod(v4) - Transports: stdio, SSE, Streamable HTTP
- State:
~/.mcp-cli/— SQLite db, aliases, PID file, Unix socket
bun install # install deps
bun test # run tests
bun typecheck # TypeScript validation
bun lint # biome lint + format
bun run build # compile binaries to dist/
bun dev:daemon # run daemon directly
bun dev:mcx -- ls # run CLI directlyThis project was developed entirely by Claude Code, without any sort of IDE.
The mcx claude commands exist because they were needed here first. Every sprint is planned, executed, reviewed, and retro'd by Claude sessions talking to each other through mcx. See the sprint skill for how it works.