|
1 | | -# McpMux - Centralized MCP Server Management |
| 1 | +# McpMux |
2 | 2 |
|
3 | 3 | [](LICENSE) |
| 4 | +[](https://github.com/MCP-Mux/mcp-mux/releases) |
4 | 5 |
|
5 | | -> A desktop application for managing Model Context Protocol (MCP) servers with spaces, credentials, and cloud sync. |
| 6 | +### Configure your MCP servers once. Connect every AI client. |
6 | 7 |
|
7 | | -## Features |
| 8 | + |
8 | 9 |
|
9 | | -- 🔐 **Secure Credentials** - OS keychain + encrypted database storage |
10 | | -- 🌐 **Spaces** - Isolated environments for different projects |
11 | | -- ⚡ **Local Gateway** - All MCP traffic stays on your machine |
12 | | -- ☁️ **Cloud Sync** - Configuration sync across devices (optional) |
13 | | -- 🔌 **Multi-Transport** - Supports stdio, HTTP, and SSE MCP servers |
| 10 | +--- |
14 | 11 |
|
15 | | -## Quick Start |
| 12 | +## The Problem |
16 | 13 |
|
17 | | -### Prerequisites |
| 14 | +Every AI client has its own MCP config file. Same servers, same credentials — duplicated everywhere. |
18 | 15 |
|
19 | | -- [Rust](https://rustup.rs/) 1.75+ |
20 | | -- [Node.js](https://nodejs.org/) 18+ |
21 | | -- [pnpm](https://pnpm.io/) 9+ |
| 16 | +``` |
| 17 | +Cursor → config.json → github, slack, db + API keys |
| 18 | +Claude Desktop → config.json → github, slack, db + API keys (again) |
| 19 | +VS Code → settings.json → github, slack, db + API keys (again) |
| 20 | +Windsurf → config.json → github, slack, db + API keys (again) |
| 21 | +``` |
22 | 22 |
|
23 | | -**Linux system dependencies** (for credential storage via Secret Service): |
24 | | -- `gnome-keyring` (or another `org.freedesktop.secrets` implementation like KWallet on KDE) |
| 23 | +Add a server? **Update every client.** Rotate an API key? **Update every client.** New project? **Reconfigure everything.** |
25 | 24 |
|
26 | | -### Development |
| 25 | +And all those credentials? Sitting in **plain-text JSON files** on disk. |
27 | 26 |
|
28 | | -```bash |
29 | | -# First time setup (installs deps, Playwright browsers, etc.) |
30 | | -pnpm setup |
| 27 | +## The Fix |
31 | 28 |
|
32 | | -# Or manually: |
33 | | -pnpm install |
| 29 | +McpMux is a desktop app that runs a local gateway. Configure your servers once, point all clients to one URL. |
34 | 30 |
|
35 | | -# Start development |
36 | | -pnpm dev |
| 31 | +``` |
| 32 | +Cursor ─┐ |
| 33 | +Claude Desktop ─┤──→ McpMux (localhost) ──→ all your MCP servers |
| 34 | +VS Code ─┤ encrypted credentials |
| 35 | +Windsurf ─┘ one config, one place |
37 | 36 | ``` |
38 | 37 |
|
39 | | -### Build |
| 38 | +Add a server in McpMux and every client has it instantly. No files to edit. |
40 | 39 |
|
41 | | -```bash |
42 | | -# Build for production |
43 | | -pnpm build |
44 | | -``` |
| 40 | +--- |
45 | 41 |
|
46 | | -## Project Structure |
| 42 | +## How It Works |
47 | 43 |
|
| 44 | +**1.** Install servers from the built-in registry (or add manually) |
| 45 | + |
| 46 | +**2.** Paste one config into your AI clients: |
| 47 | + |
| 48 | +```json |
| 49 | +{ |
| 50 | + "mcpServers": { |
| 51 | + "mcpmux": { |
| 52 | + "type": "http", |
| 53 | + "url": "http://localhost:45818/mcp" |
| 54 | + } |
| 55 | + } |
| 56 | +} |
48 | 57 | ``` |
49 | | -mcpmux/ |
50 | | -├── apps/ |
51 | | -│ └── desktop/ # Tauri desktop application |
52 | | -│ ├── src/ # React frontend |
53 | | -│ └── src-tauri/ # Rust backend |
54 | | -├── crates/ |
55 | | -│ ├── mcpmux-core/ # Domain logic and entities |
56 | | -│ ├── mcpmux-mcp/ # MCP protocol handling |
57 | | -│ └── mcpmux-storage/ # Persistence layer |
58 | | -└── packages/ |
59 | | - └── ui/ # Shared React components |
| 58 | + |
| 59 | +**3.** Done. All tools from all servers are available in every client. |
| 60 | + |
| 61 | +McpMux routes calls to the right server, refreshes OAuth tokens automatically, and keeps credentials encrypted in your OS keychain. You don't think about it. |
| 62 | + |
| 63 | +--- |
| 64 | + |
| 65 | +## Features |
| 66 | + |
| 67 | +### Server Management |
| 68 | + |
| 69 | +Add, remove, and monitor all your MCP servers in one place. See connection status, auth type, and transport at a glance. |
| 70 | + |
| 71 | + |
| 72 | + |
| 73 | +### Server Registry |
| 74 | + |
| 75 | +Browse and one-click install from a curated registry of MCP servers. Filter by category, auth type, or hosting. Cached for offline use. |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | +### Spaces |
| 80 | + |
| 81 | +Isolated workspaces with their own servers and credentials. Switch between "Work" and "Personal" in one click — your AI clients follow automatically. |
| 82 | + |
| 83 | + |
| 84 | + |
| 85 | +### Feature Sets |
| 86 | + |
| 87 | +Control exactly which tools, prompts, and resources are available. Create custom permission bundles like "Read Only" or "Dev Tools" and assign them to clients. |
| 88 | + |
| 89 | + |
| 90 | + |
| 91 | +### Connected Clients |
| 92 | + |
| 93 | +See every AI client connected to your gateway. Manage OAuth registrations and control which space each client can access. |
| 94 | + |
| 95 | + |
| 96 | + |
| 97 | +### Settings |
| 98 | + |
| 99 | +Auto-updates, launch at startup, system tray, and appearance preferences. |
| 100 | + |
| 101 | + |
| 102 | + |
| 103 | +--- |
| 104 | + |
| 105 | +## Security |
| 106 | + |
| 107 | +MCP defaults to plain-text config files with raw API keys. McpMux replaces that with: |
| 108 | + |
| 109 | +- **OS Keychain** — secrets in platform-native secure storage, not on disk |
| 110 | +- **AES-256-GCM** — field-level database encryption |
| 111 | +- **OAuth 2.1 + PKCE** — standard auth with automatic token refresh |
| 112 | +- **Local-only gateway** — binds to `127.0.0.1`, nothing exposed to the network |
| 113 | +- **Per-client access keys** — granular permissions per AI client |
| 114 | +- **Sanitized logs** — tokens never appear in log files |
| 115 | +- **Memory zeroization** — secrets wiped from memory after use |
| 116 | + |
| 117 | +All MCP traffic stays on your machine. Cloud sync (optional) only covers config metadata — never credentials or payloads. |
| 118 | + |
| 119 | +--- |
| 120 | + |
| 121 | +## Getting Started |
| 122 | + |
| 123 | +**1. [Download McpMux](https://github.com/MCP-Mux/mcp-mux/releases)** — Windows (MSI), macOS (DMG), Linux (DEB/RPM/AppImage) |
| 124 | + |
| 125 | +**2. Add servers** — Discover tab to browse the registry, or add manually |
| 126 | + |
| 127 | +**3. Paste config** — Copy the snippet from the Dashboard into your AI clients |
| 128 | + |
| 129 | +That's the last config file you'll need to touch. |
| 130 | + |
| 131 | +--- |
| 132 | + |
| 133 | +## Development |
| 134 | + |
| 135 | +```bash |
| 136 | +pnpm setup # First-time: install dependencies |
| 137 | +pnpm dev # Start development |
| 138 | +pnpm build # Production build |
| 139 | +pnpm test # Run all tests |
60 | 140 | ``` |
61 | 141 |
|
62 | | -## Architecture |
| 142 | +**Prerequisites:** Rust 1.75+, Node.js 18+, pnpm 9+. Linux also needs `gnome-keyring libsecret-1-dev librsvg2-dev pkg-config`. |
63 | 143 |
|
64 | | -McpMux acts as a local gateway that: |
| 144 | +Built with **Tauri 2** (Rust + React 19), **Axum** for the gateway, **ring** for encryption, **rmcp** for MCP. |
65 | 145 |
|
66 | | -1. **Aggregates** multiple MCP servers into a single endpoint |
67 | | -2. **Manages** credentials securely per space |
68 | | -3. **Routes** tool calls to the appropriate backend |
69 | | -4. **Syncs** configuration (not MCP traffic) to the cloud |
| 146 | +<details> |
| 147 | +<summary>Project structure</summary> |
70 | 148 |
|
71 | 149 | ``` |
72 | | -┌─────────────────────────────────────────────────────────┐ |
73 | | -│ AI Clients │ |
74 | | -│ (Cursor, Claude, etc.) │ |
75 | | -└─────────────────────┬───────────────────────────────────┘ |
76 | | - │ OAuth 2.1 + PKCE |
77 | | - ▼ |
78 | | -┌─────────────────────────────────────────────────────────┐ |
79 | | -│ McpMux Gateway │ |
80 | | -│ localhost:9315 │ |
81 | | -├─────────────────────────────────────────────────────────┤ |
82 | | -│ ┌─────────┐ ┌─────────┐ ┌─────────────┐ │ |
83 | | -│ │ Space A │ │ Space B │ │ FeatureSets │ │ |
84 | | -│ └─────────┘ └─────────┘ └─────────────┘ │ |
85 | | -└─────────────────────┬───────────────────────────────────┘ |
86 | | - │ |
87 | | - ┌─────────────┼─────────────┐ |
88 | | - ▼ ▼ ▼ |
89 | | - ┌─────────┐ ┌─────────┐ ┌─────────┐ |
90 | | - │ Backend │ │ Backend │ │ Backend │ |
91 | | - │ (stdio) │ │ (HTTP) │ │ (SSE) │ |
92 | | - └─────────┘ └─────────┘ └─────────┘ |
| 150 | +mcp-mux/ |
| 151 | +├── apps/desktop/ # Tauri desktop app (React + Rust) |
| 152 | +├── crates/ |
| 153 | +│ ├── mcpmux-core/ # Domain logic |
| 154 | +│ ├── mcpmux-gateway/ # HTTP gateway, OAuth, routing |
| 155 | +│ ├── mcpmux-storage/ # SQLite + encryption + OS keychain |
| 156 | +│ └── mcpmux-mcp/ # MCP protocol |
| 157 | +├── packages/ui/ # Shared UI components |
| 158 | +└── tests/ # Unit, integration, E2E tests |
93 | 159 | ``` |
94 | 160 |
|
95 | | -## License |
| 161 | +</details> |
96 | 162 |
|
97 | | -[GNU General Public License v3.0](LICENSE) - Free software, copyleft license. |
| 163 | +## Contributing |
| 164 | + |
| 165 | +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. |
| 166 | + |
| 167 | +## License |
98 | 168 |
|
| 169 | +[GNU General Public License v3.0](LICENSE) |
0 commit comments