Installation
Install Switchboard with npm. It needs Node.js 24 or later.
Switchboard is published to npm as mcp-switchboard. The package installs one command, switchboard. It needs Node.js 24 or later on macOS, Linux or Windows.
Run the latest version without installing anything:
npx mcp-switchboard upAny other command works the same way, as in npx mcp-switchboard status.
switchboard up starts the daemon in the foreground and opens the web UI at http://127.0.0.1:7690. Add --detach (-d) to run it in the background, and --no-open to skip the browser. Check that everything is in order with:
switchboard doctorWhere Switchboard keeps its files
Everything lives in one directory, ~/.switchboard, created with mode 700:
| Path | Contents |
|---|---|
config.json | servers, profiles, client rules and the default profile (format) |
catalog.json | the cached tool list of each server |
secrets.json | secret values, only when no OS keychain is available (mode 600) |
admin-token | the token that protects the admin API used by the web UI and CLI |
audit.jsonl | a log of tool calls, without arguments or results |
daemon.json | the running daemon's pid and port |
logs/ | daemon.log, the output of a daemon started with --detach |
backups/ | copies of client configuration files taken before Switchboard edits them |
Secret values live in your OS keychain when one is available. See Secrets and OAuth.
Environment variables
| Variable | Default | Effect |
|---|---|---|
SWITCHBOARD_HOME | ~/.switchboard | the state directory |
SWITCHBOARD_PORT | 7690 | the port the daemon listens on |
SWITCHBOARD_LOG | info | log level: debug, info, warn or error |
SWITCHBOARD_DEBUG | unset | print stack traces when a command fails |
Uninstall
Disconnect your clients first, so their configuration files no longer point at Switchboard, then remove the package and the state directory:
switchboard client disconnect cursor # for each connected client
switchboard stop # if it runs detached
npm uninstall -g mcp-switchboard
rm -rf ~/.switchboard