mcp-cli

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)

Supported platforms

Bun ≥ 1.4.4 is required on all platforms.

macOS SQLite note: bun:sqlite on macOS uses the OS-bundled /usr/lib/libsqlite3.dylib rather than embedding SQLite (Linux statically embeds). The daemon requires SQLite ≥ 3.38 for unixepoch() support. macOS 13 Ventura ships SQLite 3.39.5, which satisfies this. macOS 12 Monterey ships 3.37.0 and is unsupported.

Install

One-line installer (macOS/Linux):

curl -fsSL https://github.com/theshadow27/mcp-cli/releases/latest/download/install.sh | sh

Installs 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/

Keeping up to date

mcx upgrade              # install latest release
mcx upgrade --check      # check without installing

Zero Config

mcp-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.

How It Works

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, work items, spans
  |     +-> event bus        unified stream of session/work-item/CI/PR/cost events
  |     +-> phase engine     `.mcx.yaml` → declarative work-item state machine
  |