Turn MCP servers into composable CLIs with Unix pipe support, transparent caching, and auto-discovery.
mcpx is a CLI client that turns MCP servers into composable command-line tools. It adopts a daemon/client architecture where the CLI acts as a thin client translating GNU-style flags into JSON-RPC requests, while the background mcpxd daemon manages both stdio and HTTP MCP transport connections.
The project is built around four design fundamentals: Output Schema Awareness (--help shows both input parameters and output format), Transparent Caching (on-demand TTL caching keyed by server/tool/args hash), Error Normalization (unified Exit Code semantics with errors routed exclusively to stderr), and Native Output Passthrough (stripping MCP protocol envelopes, raw content goes straight to stdout).
mcpx auto-discovers MCP server configurations from existing clients like Cursor, Claude Code, Cline, Codex, and Kiro for zero-config onboarding. Command Shims let you install servers as standalone shell commands, and Agent Skill integration generates skill files for Claude Code/Kiro/OpenClaw. It supports ad-hoc remote invocation by passing a URL directly without pre-adding configuration.
On security, the daemon communicates via Unix domain socket (permission 0600), verifies peer UID on each connection, and uses nonce handshake to prevent socket hijacking. Configuration and caching strictly follow XDG Base Directory specifications. Primarily written in Go (92.6%), distributed via Homebrew Cask, npm, and PyPI. Latest version: v1.0.2.
Installation#
# Homebrew (macOS)
brew tap lydakis/mcpx
brew install --cask mcpx
# npm
npm install -g mcpx-go
# PyPI
pip install mcpx-go
# Source
go build ./...
Quick Start#
mcpx skill install # Install agent skill (recommended first-day action)
mcpx # List discovered servers
mcpx github # List tools for a server
mcpx github search-repositories --query=mcp | jq -r '.items[:3][].full_name'
mcpx add https://mcp.deepwiki.com/mcp # Add remote server
Configuration#
Path: ~/.config/mcpx/config.toml
[servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }
default_cache_ttl = "30s"
[servers.apify]
url = "https://mcp.apify.com"
headers = { Authorization = "Bearer ${APIFY_TOKEN}" }
Global Flags#
| Flag | Description |
|---|---|
--cache=<duration> | Cache TTL (e.g. 30s, 5m, 1h) |
--no-cache | Bypass cache |
-v, --verbose | Verbose output to stderr |
-q, --quiet | Suppress stderr |
--json | JSON output for mcpx interface |
Platform support: macOS native (with Homebrew Cask + notarization); Linux native; Windows via WSL2. Licensed under MIT.