Content
<div align="right"><sub><a href="./README.en.md">English</a> ⇄ <b>English</b></sub></div>
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./assets/hero-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="./assets/hero-light.svg">
<img src="./assets/hero-light.svg" width="880" alt="mcpx — One command to install MCP server on all your clients">
</picture>
</p>
<p><sub>mcpx is a one-command, account-free <b>MCP</b> cross-client local installer: detect clients → write config → handshake verification.</sub></p>
<p align="center">
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-black" alt="license"></a>
<img src="https://img.shields.io/github/v/release/SuperMarioYL/mcpx" alt="latest release">
<a href="https://github.com/SuperMarioYL/mcpx/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/SuperMarioYL/mcpx/ci.yml?branch=main&label=ci" alt="ci"></a>
<img src="https://img.shields.io/badge/go-1.24-00ADD8?logo=go&logoColor=white" alt="go 1.24">
<img src="https://img.shields.io/badge/MCP-ready-5E5CE6" alt="MCP ready">
<img src="https://img.shields.io/badge/coding%20agent-native-0071E3" alt="coding agent native">
</p>
**Add an MCP server to your coding agent today, and stop manually configuring each client with a different JSON file - `mcpx add <server>` makes it a one-command process, writes to all your clients, and verifies the handshake.**
<h2><img src="https://api.iconify.design/tabler:topology-star-3.svg?color=%230071E3&width=24" height="22" align="absmiddle" alt=""> Architecture</h2>
One `mcpx add`: detect installed **Claude Code** / Claude Desktop / Codex / Cursor, backup and merge according to each client's schema (JSON key-path or TOML table) → start a subprocess to run stdio JSON-RPC handshake - all in one process, one binary, no resident service, no MCP SDK.
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./assets/atlas-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="./assets/atlas-light.svg">
<img src="./assets/atlas-light.svg" width="880" alt="Architecture: mcpx add → detect clients → client adapters (Claude Code JSON / Codex TOML / Cursor JSON) → backup + merge → handshake verification">
</picture>
</p>
<h2><img src="https://api.iconify.design/tabler:info-circle.svg?color=%230071E3&width=24" height="22" align="absmiddle" alt=""> Why You Need It</h2>
The MCP server supply side is already large (`awesome-mcp-servers` 90k★, `chrome-devtools-mcp` 45k★), but installing it on clients is still a manual process: each client has a different **configuration path and schema**, and you have to write and restart each one separately. `claude mcp add` only supports Claude Code; mcpx supports multiple clients and automates the process.
<h2><img src="https://api.iconify.design/tabler:rocket.svg?color=%230071E3&width=24" height="22" align="absmiddle" alt=""> Quick Start</h2>
```bash
go install github.com/SuperMarioYL/mcpx/cmd/mcpx@latest # single binary into PATH (< 30s)
mcpx add filesystem # detect → backup → write → handshake
mcpx list # confirm each client has the server
```
<details>
<summary>Actual Output (development machine with 3 clients)</summary>
```text
Detected 3 client(s): Claude Code, Claude Desktop, Codex
· Cursor not detected (no config at ~/.cursor/mcp.json)
Installing filesystem (npx -y @modelcontextprotocol/server-filesystem .) into 3 client(s)
Claude Code backup → write → merged
backup: ~/.claude.json.mcpx-bak-20260704-1126
✓ handshake OK (initialize + tools/list, 12 tools)
Claude Desktop backup → write → merged
✓ handshake OK (initialize + tools/list, 12 tools)
Codex backup → write → merged
✓ handshake OK (initialize + tools/list, 12 tools)
✓ 3/3 clients ready
Restart (or reload) the affected clients to pick up the new server.
```
</details>
<h2><img src="https://api.iconify.design/tabler:terminal-2.svg?color=%230071E3&width=24" height="22" align="absmiddle" alt=""> Usage</h2>
```bash
# install from built-in directory (backup → idempotent write → handshake)
mcpx add filesystem
# custom server: explicit command / args / env
mcpx add my-server --command npx --args '-y @my-scope/my-mcp-server' --env API_TOKEN=secret
# write to specific clients, skip confirmation
mcpx add git --clients claude-code,codex --yes
# dry-run, no changes
mcpx add fetch --dry-run
# remove - only delete what mcpx wrote, backups remain
mcpx remove filesystem
# list built-in directory
mcpx catalog
```
See more examples in [`examples/quickstart.sh`](./examples/quickstart.sh).
**Subcommands**: `add <server>` · `list` · `remove <server>` (alias `rm`) · `catalog`
**Global Flags**: `--clients c1,c2` · `--dry-run` · `--yes/-y` · `--version/-v` · `--help/-h`
<h2><img src="https://api.iconify.design/tabler:photo.svg?color=%230071E3&width=24" height="22" align="absmiddle" alt=""> Demo</h2>
<h2><img src="https://api.iconify.design/tabler:plug-connected.svg?color=%230071E3&width=24" height="22" align="absmiddle" alt=""> Supported Clients</h2>
| Client | Config File | Format | Status |
|---|---|---|---|
| Claude Code | `~/.claude.json` | JSON (`mcpServers.<name>`, with `type:"stdio"`) | ✓ Tested |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) | JSON (`mcpServers`) | ✓ Tested |
| Codex | `~/.codex/config.toml` | TOML (`[mcp_servers.<name>]`) | ✓ Tested |
| Cursor | `~/.cursor/mcp.json` | JSON (`mcpServers`) | fail-soft: skip if no config |
Clients not detected will not be written to - mcpx only modifies clients with confirmed paths.
<h2><img src="https://api.iconify.design/tabler:git-compare.svg?color=%230071E3&width=24" height="22" align="absmiddle" alt=""> Comparison</h2>
Honest comparison - each solution has its strengths:
| Capability | `mcpx` | `claude mcp add` | [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) | Smithery / mcp-get |
|---|:--:|:--:|:--:|:--:|
| One-command install on **all** detected clients | ✓ | — (only Claude Code) | — (directory) | partial (biased towards single-point/registry) |
| Handshake verification | ✓ | — | — | — |
| Backup + idempotent merge (preserves other keys) | ✓ | ✓ | n/a | partial |
| Local, account-free, cloud-free | ✓ | ✓ | ✓ | partial (biased towards cloud/registry) |
| Server discovery / directory scale | built-in 8 | — | ✓ **90k★, incomparable** | ✓ |
> In short: directory provides "what exists", each `add` provides "write your own", mcpx provides "write to all clients and verify handshake".
<h2><img src="https://api.iconify.design/tabler:credit-card.svg?color=%230071E3&width=24" height="22" align="absmiddle" alt=""> Pricing</h2>
Local core - detection, backup, cross-client writing, handshake - **perpetually open-source, no paywall**. Paid features are only for "team sync/audit":
| Version | For | Price | Content |
|---|---|---|---|
| **OSS Core** | individual developers | open-source, free | all features above |
| **mcpx Teams** | 5-30 person engineering teams | **$5 / seat / month** (team capped at $49/month, ≤10 people) | hosted team config list ("which servers + versions" as shared profile), `mcpx add --profile <team>` one-click alignment, CI validation, audit logs |
> Teams is a v0.3+ feature, v0.1 only lays the groundwork, no implementation. The core action of local writing is never walled.
<h2><img src="https://api.iconify.design/tabler:map-2.svg?color=%230071E3&width=24" height="22" align="absmiddle" alt=""> Roadmap</h2>
- [x] **m1** — `mcpx add`: detect → backup → idempotent write → handshake, client-by-client OK/WARN/FAIL
- [x] **m2** — `mcpx list` / `mcpx remove` (backup before deletion, preserve other entries)
- [x] **m3** — built-in 8 server directory + `--command/--args/--env` generic from-spec; cross-platform single binary, English README, demo, CI
- [ ] more client adapters (domestic coding-agent client path confirmation and implementation)
- [ ] `mcpx doctor`: inspect health of installed servers on each client
- [ ] **mcpx Teams**: shared profile + CI gate + audit (paid feature)
<h2><img src="https://api.iconify.design/tabler:license.svg?color=%230071E3&width=24" height="22" align="absmiddle" alt=""> License and Contribution</h2>
MIT. Welcome issues / PRs - please include which clients you used and which one you'd like to prioritize.
## Share this
```
mcpx — the one-command MCP installer that writes into every coding agent you have (Claude Code, Codex, Cursor) and handshake-verifies each. No account, no cloud. https://github.com/SuperMarioYL/mcpx
```
<p align="center"><sub><a href="./LICENSE">MIT</a> 2026 SuperMarioYL</sub></p>
