{"id":45652312,"url":"https://github.com/lydakis/mcpx","last_synced_at":"2026-03-01T09:03:58.683Z","repository":{"id":340283587,"uuid":"1165339831","full_name":"lydakis/mcpx","owner":"lydakis","description":"Unix-native CLI wrapper for MCP servers","archived":false,"fork":false,"pushed_at":"2026-02-24T07:36:02.000Z","size":116,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-24T10:28:24.799Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lydakis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-24T04:11:08.000Z","updated_at":"2026-02-24T07:00:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lydakis/mcpx","commit_stats":null,"previous_names":["lydakis/mcpx"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/lydakis/mcpx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lydakis%2Fmcpx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lydakis%2Fmcpx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lydakis%2Fmcpx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lydakis%2Fmcpx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lydakis","download_url":"https://codeload.github.com/lydakis/mcpx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lydakis%2Fmcpx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29965419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T06:55:38.174Z","status":"ssl_error","status_checked_at":"2026-03-01T06:53:04.810Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-24T06:50:22.972Z","updated_at":"2026-03-01T09:03:58.672Z","avatar_url":"https://github.com/lydakis.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcpx\n\nTurn MCP servers into composable CLIs.\n\n`mcpx` turns MCP tools into shell commands so agents can use standard CLI composition (`|`, redirection, `jq`, `head`) and skill workflows.\n\n`mcpx` keeps the command contract simple:\n\n- `mcpx` lists servers\n- `mcpx \u003cserver\u003e` lists tools\n- `mcpx \u003cserver\u003e \u003ctool\u003e` calls a tool\n\nTool names are used exactly as exposed by each server (no client-side renaming/aliasing).\n\nUtility commands:\n\n- `mcpx add \u003csource\u003e [--name \u003cserver\u003e] [--header KEY=VALUE]... [--overwrite]` bootstraps a server config from an install link, manifest URL, direct MCP endpoint URL, or local manifest file\n- `mcpx shim install \u003cserver\u003e` installs a local passthrough command shim (`\u003cserver\u003e ...` -\u003e `mcpx \u003cserver\u003e ...`)\n- `mcpx shim remove \u003cserver\u003e` and `mcpx shim list` manage installed shims\n- `mcpx completion \u003cbash|zsh|fish\u003e` prints shell completion scripts\n- `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)\n\nIt is designed for agent workflows and shell composition:\n\n- schema-aware `--help` (inputs + declared outputs)\n- native flag surface from MCP `inputSchema`\n- standardized exit mapping (`0/1/2/3`)\n- optional response caching with TTL and config overrides\n- optional Codex Apps compatibility via virtual per-app servers\n- stdio + HTTP transports via a local daemon\n- generated shell completions and packaged root man page (`man mcpx`)\n\n## Install\n\n### Homebrew\n\n```bash\nbrew tap lydakis/mcpx\nbrew install --cask mcpx\n```\n\n### npm\n\n```bash\nnpm install -g mcpx-go\nmcpx --version\n```\n\n### PyPI\n\n```bash\npip install mcpx-go\nmcpx --version\n```\n\n### Build from source\n\n```bash\ngo build ./...\n./mcpx --version\n```\n\nWindows users: use WSL2 and run install commands inside your Linux distro shell.\n\n## Quick Start\n\nIf you already use MCP in Cursor/Claude Code/Cline/Codex/Kiro, `mcpx` will auto-discover those server configs. Start with:\n\n```bash\nmcpx\nmcpx \u003cserver\u003e\nmcpx \u003cserver\u003e \u003ctool\u003e --help\n```\n\nWhen Codex Apps are enabled in local Codex config and authenticated, `mcpx` also exposes connected apps as MCP servers.\n\nIf `mcpx` shows no servers, create `~/.config/mcpx/config.toml`:\n\n```toml\n[servers.github]\ncommand = \"npx\"\nargs = [\"-y\", \"@modelcontextprotocol/server-github\"]\nenv = { GITHUB_TOKEN = \"${GITHUB_TOKEN}\" }\ndefault_cache_ttl = \"30s\"\n```\n\nRun:\n\n```bash\nmcpx\nmcpx github\nmcpx github search-repositories --help\nmcpx github search-repositories --query=mcp\nmcpx shim install github\ngithub search-repositories --query=mcp | jq -r '.items[:3][].full_name'\n```\n\n## Command Shims (Optional)\n\n```bash\nmcpx shim install github\nmcpx shim list\nmcpx shim remove github\n```\n\nShims are pass-through wrappers (`\u003cserver\u003e ...` -\u003e `mcpx \u003cserver\u003e ...`) 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`.\n\n## Output Modes\n\n`--json` applies only to mcpx-owned output surfaces:\n\n- `mcpx`\n- `mcpx \u003cserver\u003e`\n- `mcpx \u003cserver\u003e \u003ctool\u003e --help`\n\nNormal tool-call output (`mcpx \u003cserver\u003e \u003ctool\u003e ...`) is not transformed by `--json`.\n\nUse `mcpx -v` (or `mcpx --json -v`) to include per-server `origin` metadata (config/fallback-derived `kind`; JSON also includes optional `path`).\n\n## More Examples\n\n```bash\nmcpx --json\nmcpx github --json\nmcpx github -v\nmcpx github search-repositories --help --json\nmcpx add \"cursor://anysphere.cursor-deeplink/mcp/install?name=postgres\u0026config=...\"\nmcpx add https://mcp.deepwiki.com/mcp\nmcpx add https://mcp.devin.ai/mcp --name deepwiki --header \"Authorization=Bearer \\${DEEPWIKI_API_KEY}\"\nmcpx skill install\n```\n\n## Codex Apps (Optional)\n\nWhen 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:\n\n```bash\nmcpx linear\nmcpx linear \u003ctool\u003e --help\nmcpx linear \u003ctool\u003e ...\n```\n\nAuth is still managed by Codex. `mcpx` does not run OAuth flows or store third-party app credentials.\n\n## MCP Smoke Test Commands\n\nUse these to validate a local MCP quickly:\n\n```bash\nmcpx \u003cserver\u003e\nmcpx \u003cserver\u003e --json       # machine-readable list output\nmcpx \u003cserver\u003e -v            # full tool descriptions\nmcpx \u003cserver\u003e \u003ctool\u003e --help\nmcpx \u003cserver\u003e \u003ctool\u003e --help --json\nmcpx \u003cserver\u003e \u003ctool\u003e -v\necho $?    # inspect exit code contract\n```\n\nFor your current fallback setup, a working `browser-tools` entry should use `-y`:\n\n```toml\n[servers.browser-tools]\ncommand = \"npx\"\nargs = [\"-y\", \"@agentdeskai/browser-tools-mcp@1.1.0\"]\n```\n\n## Versioning Behavior\n\n- Local/dev builds show `mcpx dev`.\n- Tagged release builds show the tag version in `mcpx --version` (for example `mcpx v0.1.0`) via GoReleaser ldflags.\n\n## Release\n\n- Tag pushes `v*` run the release workflow.\n- GoReleaser publishes artifacts and updates `lydakis/homebrew-mcpx`.\n- Notarization uses standard Apple Developer and App Store Connect secrets.\n\nDetailed docs:\n\n- [design](docs/design.md)\n- [usage](docs/usage.md)\n- [release](docs/release.md)\n- [roadmap](docs/roadmap.md)\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flydakis%2Fmcpx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flydakis%2Fmcpx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flydakis%2Fmcpx/lists"}