mcp-local-hub
One managed local hub for every MCP server you use — N duplicate processes per server collapse to 1 shared daemon.
Run one copy of each Model Context Protocol server on your workstation, shared across every MCP client that needs it — instead of each client spawning its own redundant stdio process. Install the binary (mcphub) once with npm, point your clients at the hub, and stop paying for the same server N times.

[!WARNING] Preview version:
mcp-local-hubis actively under development. Interfaces, manifests, GUI flows, install/migration behavior, and supported-client wiring may still change. Windows 11 is the primary tested path, but not every feature, server, client combination, or platform path is fully tested yet; use dry-runs and backups before applying changes to important MCP client configs.
Install (npm)
For version 0.4.37, the npm distribution targets Windows x64 only; other
platforms are deferred and the 0.4.37 shim will reject them. The npm
package is mcp-local-hub; the command it installs is mcphub.
# 1. Install globally (npm places the `mcphub` command on PATH)
npm install -g [email protected]
# 2. Open the GUI — install servers with one click, see every daemon's health
mcphub gui
npm launches its native Product directly from the installed package. mcphub setup
is optional for explicit local testing/install mode, not an npm prerequisite.
# Or run once without installing:
npx [email protected] version
The meta package ships no postinstall download script (the top npm
supply-chain attack vector) — npm installs the Windows x64 binary via an
optional dependency, and a tiny Node shim execs it. Building from source is
still supported for dev iteration — see
Building from source below.
Detailed setup, per-client behaviour, and troubleshooting in INSTALL.md.
Why mcphub — the problem and the cure
The problem. Every modern coding assistant (Claude Code, Codex CLI, Cursor, VS Code, Gemini CLI, Qwen Code CLI, Antigravity, Continue, ...) speaks MCP, and each client independently execs whatever stdio servers you configure — uvx serena, npx @modelcontextprotocol/server-memory, mcp-language-server, and so on. Run three assistants side-by-side on the same project and you get three Serena processes, three gopls subprocesses, three separate memory stores. Scale that across the editors, agents, and CLIs a working developer keeps open and you get dozens of duplicate node/python processes — each per-session spawn re-downloads dependencies, re-indexes your code, and eats RAM, all to do the same work the process next to it is already doing.
The cure. mcp-local-hub is one managed local hub: install once, and every client routes through it. Each MCP server runs once per OS user, supervised, restarted on failure, and shared — so the process tail compresses from N duplicate procs → 1 managed daemon each.
What this tool does
mcp-local-hub runs each MCP server once per OS user, exposes it as a local HTTP endpoint via Streamable HTTP transport, and writes the correct client-config entry into each managed MCP client. Clients see a shared daemon instead of their own child process.
MCP clients mcphub shared daemons
(Claude Code, (one per server,
Codex, Cursor, ┌──────────────────────┐ per OS user)
VS Code, Gemini, │ mcphub supervise │ ┌──────────────┐
Qwen, …) │ ─────────────────── │ ┌────▶│ serena ×2 │
│ supervisor: owns, │ │ ├──────────────┤
┌──────────┐ HTTP │ restarts, shares │ ├────▶│ memory │
│ client A │ ───────▶ │ every daemon │ ──┤ ├──────────────┤
├──────────┤ HTTP │ │ ├────▶│ godbolt … │
│ client B │ ───────▶ │ (HTTP front + │ │ ├──────────────┤
├──────────┤ HTTP │ stdio-host / │ └────▶│ +7 more │
│ client C │ ───────▶ │ embedded Go) │ └──────────────┘
└──────────┘ └──────────────────────┘
Each MCP server runs once per OS user; every client shares the same daemon over loopback HTTP instead of spawning its own copy. See docs/supervisor-architecture.md for the full lifecycle, state-file layout, migration, and per-OS behavior.
Stdio-only MCP servers (memory, time, sequential-thinking, wolfram, gdb, paper-search-mcp) run behind a native Go stdio-host (internal/daemon/host.go): one subprocess per daemon, multiplexed across concurrent HTTP clients via JSON-RPC id rewriting and a cached initialize response. Four servers (godbolt, lldb-bridge, perftools, vcpkg) ship as Go code embedded directly in the mcphub binary — no npm/pip dependency, starts instantly.
Antigravity's Cascade agent rejects loopback-HTTP MCP entries, so mcp-local-hub bridges it via a stdio relay subprocess: mcphub relay translates between stdio JSON-RPC and the shared HTTP daemon. Cascade sees a normal stdio command; the daemon stays shared.
Building from source
The npm install above is the fastest path. To build from source instead — for dev iteration or to embed your own version metadata:
# 1. Build the admitted Windows product payload
pwsh ./build.ps1
# 2. Install to ~/.local/bin and register on user PATH (idempotent)
.\bin\mcphub.exe setup
build.sh remains the repository automation entry for supported non-Windows
build environments. On Windows, build.ps1 is the only product-payload route;
plain go build is a compile check whose output is not installable or
promotable.
Windows source builds produce one native file: bin/mcphub.exe as
WINDOWS_GUI (PE subsystem 2), plus the non-executable admitted identity
bin/windows-product-identity.json. The repository-only validator reads the
PE and version resource without executing it; no validator or launcher helper
is shipped.
The Windows platform subpackage deliberately has no npm bin mapping. The
meta package alone generates the public mcphub Node shim, which synchronously
relays arguments, standard streams, and exit status to mcphub.exe. GUI,
Explorer, shortcut, background, and explicit command modes all use that same
native product image.
--debug-console remains accepted as an exact first argument for compatibility:
mcphub --debug-console [command ...]
--debug-console must be the exact first argument. It affects only that
mcphub process, preserves redirected standard input/output/error, and is not
available through an environment variable, config key, subcommand flag, or
implicit gui, --foreground, --no-tray, supervise, or restart mode.
Background children remain console-free. GUI editor launches require a Windows
GUI-subsystem executable.
Whether you installed via npm or built from source, the rest is identical — use the CLI to install the servers you want shared and verify they connect:
# Install the MCP servers you want shared
mcphub install --server serena # default clients: Claude/Codex/Cursor
mcphub install --all # all 17 global servers, default clients
# Materialize one server in supervisor intent without touching client configs
mcphub install --server fetch --no-client-config
# Optional client targeting
mcphub install --server serena --clients qwen-cli,vscode
mcphub install --server serena --all-clients
# Verify
mcphub status
claude mcp get serena # shows: Status: ✓ Connected, Type: http
Thirteen highlighted servers
The binary embeds 18 manifests. mcphub install --all installs the 17 global
servers; mcp-language-server is workspace-scoped and is materialized through
mcphub register. The table below highlights 13 commonly used servers rather
than claiming to enumerate the complete embedded catalog.
Plus context7 as a direct HTTPS entry (no daemon, no scheduler task).
Embedded vs external servers
Four servers (godbolt, lldb-bridge, perftools, vcpkg) are implemented as Go packages inside internal/<name>/ and run as subcommands of the mcphub binary itself — no external runtime dependency. The first three also ship as independent standalone binaries via go build ./cmd/<name> for users who want just that one server without the full hub. vcpkg intentionally follows the hub-only in-binary pattern and has no standalone cmd/vcpkg executable.
Performance-review workflow combining multiple servers in one chat:
# audit real project for perf antipatterns
perftools.clang_tidy(files=["src/hot.cpp"], checks="performance-*")
# sanity-check asm on godbolt with optimization remarks
godbolt.compile_code(source=..., filters={optOutput: true, intel: true})
# statistical bench (requires opt-in: MCP_LOCAL_HUB_ENABLE_UNSAFE_HYPERFINE=1 on
# the perftools daemon — see INSTALL.md "Opting into hyperfine")
perftools.hyperfine(commands=["./old_bin", "./new_bin"], warmup=3)
# verify the LTO-linked final binary keeps the vectorization
perftools.llvm_objdump(binary="./new_bin", project_root=".", function="hot_loop")
Supported clients
Default install targets are claude-code and codex-cli.
cursor, vscode, gemini-cli, qwen-cli, antigravity, zed, kiro, windsurf,
cline, kilocode, opencode, hermes, and openclaw are opt-in via
--clients ... or --all-clients, so install does not silently mutate every
assistant installed on the workstation.
Antigravity note: Cascade rejects loopback-HTTP MCP entries, so mcp-local-hub writes a stdio relay entry instead — mcphub.exe relay --server <name> --daemon <d>. Cascade spawns the relay as a normal stdio subprocess; the relay forwards JSON-RPC to the shared HTTP daemon. No extra server process per Antigravity session.
CLI surface
The commands you reach for day to day:
The full command surface — install flags, discovery/migration, logs/backups/recovery, scheduler/secrets, and the hidden transport shims — is in docs/cli-reference.md.
Architecture highlights
- One admitted Windows Product image — the public npm command is a Node shim
that launches the native executable in the npm package. Generated background
launches use that admitted image, retaining an authenticated active Product owner.
~/.local/binremains the optional explicit-local install and fixed storage policy; production npm use requires no promotion or executable copy there. - First-run onboarding —
mcphub setup --trusted-rootblesses LSP trusted roots up front; the GUI shows a dismissable welcome banner until the first server is installed. - go:embed manifests — all 18 server manifests are baked into the binary, so the binary runs without a sibling
servers/directory.install --alltargets the 17 global manifests; the remaining manifest is workspace-scoped. - Embedded entry patterns —
godbolt,lldb-bridge, andperftoolsexpose aNewCommand()factory imported by both a standalone binary and the hub subcommand.vcpkgexposes the same factory only to the hub subcommand because it is deliberately hub-only. - Native Go stdio-host with child-exit detection — one subprocess per daemon, multiplexed across concurrent HTTP clients, with child-exit detection feeding Task Scheduler's restart policy.
See docs/architecture-highlights.md for the full prose on each highlight, and docs/supervisor-architecture.md for supervisor / lifecycle depth.
Supervisor architecture (v0.5.0)
A single long-lived mcphub supervise process per user owns every MCP daemon,
restarts it on failure, and shares it across clients. Full design — new commands
(supervise, strict-mode, autostart, install --upgrade), state-file
layout, v0.4.x migration flow, and per-OS behavior matrix — is in
docs/supervisor-architecture.md.
Current status
Preview / Phase 3B-II hardening — the core CLI, daemon layer, Windows GUI, tray, secrets, settings, backup, migration, and workspace-scoped LSP surfaces are in the tree. Phase 3A and Phase 3B-I are closed; Phase 3B-II has delivered multiple follow-up slices, but still needs the live/manual smoke matrix and backlog reconciliation before a release-ready claim.
Delivered and documented:
- 17 built-in global servers (incl. HFSS, CST, and the gdb/lldb/godbolt/perftools/drmemory/vtune/oneapi-run debug+profile suite) plus a 52-row curated catalog (one-click install across engineering/CAD, music, data/BI, creative, science, PKM, office) and the direct HTTPS
context7entry. - 22 user-facing CLI commands across install, migration, logs, backups, scheduler, secrets, settings, cleanup, and version surfaces.
- Go rewrites of godbolt and lldb, embedded as dual-entry servers.
- Perftools wrapping clang-tidy, opt-in hyperfine, llvm-objdump, and iwyu.
- PATH-based install model with
mcphub setup. - go:embed manifests for filesystem-independent binaries.
- Native stdio-host, child-exit detection, and Task Scheduler restart policy.
- Local-loopback GUI, SSE event bus, dashboard, logs, migration matrix, secrets/settings/about screens, Windows tray subprocess, and Playwright/E2E infrastructure.
- Workspace-scoped LSP lazy proxies and a Phase 3B-II live/manual smoke checklist for tray, console, reboot, daemon kill, and multi-language LSP validation.
Phase evidence:
- Phase 1 — Serena consolidation across the original 4 clients (docs/phase-1-verification.md).
- Phase 2 — 7 global daemons added, supergateway -> native Go stdio-host (docs/phase-2-verification.md).
- Phase 3A — CLI parity and Go-embedded servers (docs/phase-3a-verification.md).
- Phase 3B-I — GUI Installer MVP (docs/phase-3b-verification.md).
- Phase 3B-II — backlog and manual smoke matrix (docs/superpowers/plans/phase-3b-ii-backlog.md, docs/phase-3b-ii-verification.md).
Forward development proposals:
- Ideas to evaluate from
ravitemer/mcp-hubare captured in docs/superpowers/plans/2026-05-04-ravitemer-mcp-hub-adoption-proposals.md.
Roadmap / remaining work:
- Phase 3B-II release hardening — execute the D2/D3 live/manual smoke matrix and reconcile the remaining backlog before tagging.
- Phase 3C+ candidate work — optional unified MCP endpoint and VS Code workspace/JSON5 import compatibility. (Richer health/capability status, the curated marketplace + one-click install, and remote-server
httpmanifests have since SHIPPED — see the matrix below.) - Phase 4+ — Linux/macOS scheduler backends (systemd user units + launchd agents).
Feature & readiness matrix
A surface-by-surface map of what this project actually does today, with explicit honesty about preview-state coverage. See CONTRIBUTING.md for the promotion rules a row follows.
- ✅ Stable — fresh automated test coverage OR a recent live-smoke pass for the exact user-visible surface, AND no open critical caveat. Not "production-ready"; "works as advertised in this preview, with evidence."
- ⚠ Preview — feature is shipped and reachable, but live-smoke coverage is partial, an open caveat exists in
work-items/bugs/or the backlog, OR the surface may change in incompatible ways. Backups and dry-run before applying. - 🚧 Roadmap — feature is acknowledged in the backlog but not yet shipped, OR currently exists only as a cross-compile path with no runtime evidence.
License
Mozilla Public License Version 2.0 (MPL-2.0) — see LICENSE.
Commercial licenses and commercial versions are available by separate agreement for teams that need different licensing terms, private distribution, support, warranty, indemnity, integration, packaging, or proprietary deployment terms. To discuss a commercial version or commercial license, contact Dmitry Denisenko through GitHub at @applicate2628.
Unless and until a separate commercial agreement is signed, use, modification,
and distribution of this repository remain governed by MPL-2.0. A commercial
offer does not reduce the rights granted for the public source code under
MPL-2.0.
Copyright 2026 Dmitry Denisenko (@applicate2628)
Terms and Abbreviations
CLI: Command-Line Interface; commands such asmcphub installandmcphub status.Commercial license: separate private agreement for different licensing, support, distribution, warranty, indemnity, integration, packaging, or deployment terms.Cursor: Cursor editor/agent client; an opt-in MCP client target (--clients cursor) in this preview.GUI: Graphical User Interface; the embedded local web interface and tray surface.MCP: Model Context Protocol; the protocol used by managed clients and servers.MPL-2.0: Mozilla Public License Version 2.0; the open-source license used by this repository.Qwen Code CLI: Qwen command-line agent client; opt-in MCP client target.SSE: Server-Sent Events; the HTTP event stream used by the GUI.VS Code: Visual Studio Code; opt-in MCP client target and future workspace-import surface.