https://github.com/lydakis/mcpx
Unix-native CLI wrapper for MCP servers
https://github.com/lydakis/mcpx
Last synced: 4 months ago
JSON representation
Unix-native CLI wrapper for MCP servers
- Host: GitHub
- URL: https://github.com/lydakis/mcpx
- Owner: lydakis
- License: mit
- Created: 2026-02-24T04:11:08.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-24T07:36:02.000Z (4 months ago)
- Last Synced: 2026-02-24T10:28:24.799Z (4 months ago)
- Language: Go
- Size: 113 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Roadmap: docs/roadmap.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# mcpx
Turn MCP servers into composable CLIs.
`mcpx` turns MCP tools into shell commands so agents can use standard CLI composition (`|`, redirection, `jq`, `head`) and skill workflows.
`mcpx` keeps the command contract simple:
- `mcpx` lists servers
- `mcpx ` lists tools
- `mcpx ` calls a tool
Tool names are used exactly as exposed by each server (no client-side renaming/aliasing).
Utility commands:
- `mcpx add [--name ] [--header KEY=VALUE]... [--overwrite]` bootstraps a server config from an install link, manifest URL, direct MCP endpoint URL, or local manifest file
- `mcpx shim install ` installs a local passthrough command shim (` ...` -> `mcpx ...`)
- `mcpx shim remove ` and `mcpx shim list` manage installed shims
- `mcpx completion ` prints shell completion scripts
- `mcpx skill install` installs the built-in `mcpx` skill to `~/.agents/skills` and links it for Claude Code (optional flags also link for Codex/Kiro)
It is designed for agent workflows and shell composition:
- schema-aware `--help` (inputs + declared outputs)
- native flag surface from MCP `inputSchema`
- standardized exit mapping (`0/1/2/3`)
- optional response caching with TTL and config overrides
- optional Codex Apps compatibility via virtual per-app servers
- stdio + HTTP transports via a local daemon
- generated shell completions and packaged root man page (`man mcpx`)
## Install
### Homebrew
```bash
brew tap lydakis/mcpx
brew install --cask mcpx
```
### npm
```bash
npm install -g mcpx-go
mcpx --version
```
### PyPI
```bash
pip install mcpx-go
mcpx --version
```
### Build from source
```bash
go build ./...
./mcpx --version
```
Windows users: use WSL2 and run install commands inside your Linux distro shell.
## Quick Start
If you already use MCP in Cursor/Claude Code/Cline/Codex/Kiro, `mcpx` will auto-discover those server configs. Start with:
```bash
mcpx
mcpx
mcpx --help
```
When Codex Apps are enabled in local Codex config and authenticated, `mcpx` also exposes connected apps as MCP servers.
If `mcpx` shows no servers, create `~/.config/mcpx/config.toml`:
```toml
[servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }
default_cache_ttl = "30s"
```
Run:
```bash
mcpx
mcpx github
mcpx github search-repositories --help
mcpx github search-repositories --query=mcp
mcpx shim install github
github search-repositories --query=mcp | jq -r '.items[:3][].full_name'
```
## Command Shims (Optional)
```bash
mcpx shim install github
mcpx shim list
mcpx shim remove github
```
Shims are pass-through wrappers (` ...` -> `mcpx ...`) installed in `$XDG_BIN_HOME` (if set) or `~/.local/bin`. Ensure that directory is in your `PATH`. Install is collision-safe: it fails if that command name already resolves elsewhere in `PATH`.
## Output Modes
`--json` applies only to mcpx-owned output surfaces:
- `mcpx`
- `mcpx `
- `mcpx --help`
Normal tool-call output (`mcpx ...`) is not transformed by `--json`.
Use `mcpx -v` (or `mcpx --json -v`) to include per-server `origin` metadata (config/fallback-derived `kind`; JSON also includes optional `path`).
## More Examples
```bash
mcpx --json
mcpx github --json
mcpx github -v
mcpx github search-repositories --help --json
mcpx add "cursor://anysphere.cursor-deeplink/mcp/install?name=postgres&config=..."
mcpx add https://mcp.deepwiki.com/mcp
mcpx add https://mcp.devin.ai/mcp --name deepwiki --header "Authorization=Bearer \${DEEPWIKI_API_KEY}"
mcpx skill install
```
## Codex Apps (Optional)
When Codex Apps are enabled in local Codex config, `mcpx` can expose connected apps as normal MCP servers (for example, `linear` or `zillow`) through the same command contract:
```bash
mcpx linear
mcpx linear --help
mcpx linear ...
```
Auth is still managed by Codex. `mcpx` does not run OAuth flows or store third-party app credentials.
## MCP Smoke Test Commands
Use these to validate a local MCP quickly:
```bash
mcpx
mcpx --json # machine-readable list output
mcpx -v # full tool descriptions
mcpx --help
mcpx --help --json
mcpx -v
echo $? # inspect exit code contract
```
For your current fallback setup, a working `browser-tools` entry should use `-y`:
```toml
[servers.browser-tools]
command = "npx"
args = ["-y", "@agentdeskai/browser-tools-mcp@1.1.0"]
```
## Versioning Behavior
- Local/dev builds show `mcpx dev`.
- Tagged release builds show the tag version in `mcpx --version` (for example `mcpx v0.1.0`) via GoReleaser ldflags.
## Release
- Tag pushes `v*` run the release workflow.
- GoReleaser publishes artifacts and updates `lydakis/homebrew-mcpx`.
- Notarization uses standard Apple Developer and App Store Connect secrets.
Detailed docs:
- [design](docs/design.md)
- [usage](docs/usage.md)
- [release](docs/release.md)
- [roadmap](docs/roadmap.md)
## License
[MIT](LICENSE)