better-claude-config/README.md

Better Claude Config (BCC)

A small, cross-platform GUI for editing the mcpServers block of one or more Claude Desktop installs — without ever hand-writing JSON.

BCC only ever touches mcpServers (and its own _disabledMcpServers parking key). Every other key in your config is preserved verbatim, in its original order. Each write is atomic and makes a timestamped backup first.

Install & run

pip install -r requirements.txt
python bcc.py

(Python 3.10+.)

What it does

• Auto-discovers installs — scans the platform's app-support folder for any Claude* directory (so Claude and Claude-Work both show up), and lets you Add config… to point at any file manually.

• Form-based editing — name, command, args (one per line), env vars, or for remote servers: URL, transport, and headers. No raw JSON.

• Paste JSON — drop in any snippet from an MCP doc (full mcpServers block, inner map, or a single bare server object); it's parsed and merged.

• Drag & drop a .json file onto the window to import servers from it.

• Copy to ▸ — copy the selected server straight into your other install.

• Active / Disabled sections — servers are shown in two labelled lists with live counts, so a server that's switched off in the config is obvious at a glance. Toggle a server's checkbox to move it between sections (disabled servers are parked under _disabledMcpServers, which Claude ignores).

• Dependency check + diagnostics — each server shows whether its command is actually found on PATH:

  • ● green — found on the normal PATH; will work anywhere.
  • ▲ amber (PATH-risk) — found, but only in a location BCC added on top of the inherited PATH. It'll work when you launch Claude from a terminal, but a double-clicked .app may not see it. This is the usual cause of "the tool says it's fine but Claude won't start the server." One click on Use full path ↳ rewrites the bare command (npx) to its absolute path so any launch finds it.
  • ● red (broken) — not found anywhere.
  • ◆ blue — remote (url) server. Test connection does a live reachability check on a background thread (any HTTP response = reachable).

  Each section header shows a broken / PATH-risk count badge, and selecting a flagged server auto-opens a Details panel with a full, copy-pasteable report: which command resolved to what, tailored install hints, and the exact PATH that was searched (with + marking the dirs BCC added). Re-check re-scans PATH after you install something; Copy diagnostics grabs the whole report for a bug report.

After saving, restart that Claude install for changes to take effect.

Config locations it scans

OS	Base it scans for Claude*
macOS	~/Library/Application Support
Windows	%APPDATA%
Linux	~/.config

Files

• bcc.py — the GUI.
• bcc_core.py — all the file/JSON/validation/dependency logic (no GUI deps).
• test_core.py — unit suite for the core (python test_core.py).

Rebrand

The accent color is one constant (ACCENT) at the top of bcc.py.

License

MIT — see LICENSE.