Better Claude Config (BCC)

A small, cross-platform GUI for editing the mcpServers block of Claude Desktop and Claude Code 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.

Download (no Python required)

Pre-built self-contained binaries are attached to every GitHub Release:

Platform	Download	Run
macOS	BetterClaudeConfig-macOS.zip	Unzip → drag BetterClaudeConfig.app to Applications
Windows	BetterClaudeConfig-Windows.zip	Unzip → double-click BetterClaudeConfig.exe
Linux	BetterClaudeConfig-Linux.tar.gz	Extract → run BetterClaudeConfig

macOS Gatekeeper note: the app is not notarized. On first launch, right-click → Open, or run xattr -cr /Applications/BetterClaudeConfig.app in a terminal.

Verifying your download

BCC isn't code-signed — there's no budget for a paid certificate (macOS Developer ID, Windows Authenticode). Instead, every release publishes a SHA256SUMS file listing the checksum of each archive, detached-signed with Ed25519 as SHA256SUMS.sig. Both are attached to the release alongside the binaries.

What this proves: the file you downloaded is byte-for-byte what we published, and the manifest itself was signed by our release key.

What this does NOT do: it does not make the binary "safe," and it does not remove the macOS Gatekeeper or Windows SmartScreen warning — those are only suppressed by a paid OS-vendor certificate, which this project doesn't have. Verifying checksums is about detecting tampering in transit or on a mirror, not about vouching for the software.

Release signing public key (Ed25519, base64, raw 32 bytes):

<PLACEHOLDER — AJ: paste the public key from the Catalog Console (#62) here>

macOS / Linux

# From inside the folder you downloaded the release files into:
sha256sum -c SHA256SUMS

If your sha256sum complains about missing files, download SHA256SUMS into the same directory as the archive you downloaded — it lists every platform's archive, and only the one(s) present will be checked.

To also verify the manifest's signature (optional, requires Python + pip install cryptography and a checkout of this repo):

python3 scripts/sign_checksums.py verify \
  --sums SHA256SUMS --sig SHA256SUMS.sig \
  --pubkey-b64 "<the public key above>"

Windows (PowerShell)

Get-FileHash .\BetterClaudeConfig-Windows.zip -Algorithm SHA256

Compare the printed hash (case-insensitively) against the matching line in SHA256SUMS.

If a release has no SHA256SUMS.sig

The signing key is a repo secret that has to be configured manually; if a release is missing the .sig file, the checksums themselves are still valid and safe to check against — the release workflow only skips signing, never checksum generation.

Run from source

pip install -r requirements.txt
python bcc.py

(Python 3.10+, PySide6 6.6+.)

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 finds Claude Code's user-scope config at ~/.claude.json (the file claude mcp add writes). Use Add config… to point at any other file manually — e.g. a project's .mcp.json.

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

• Paste JSON — even broken 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. The paste box parses as you type and auto-repairs the stuff docs and chat windows love to break: markdown fences, surrounding prose, comments, trailing or missing commas, smart quotes, single quotes, unquoted keys, and unclosed braces — and tells you exactly what it fixed before you commit.

• 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

Claude Desktop

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

Claude Code (all platforms): ~/.claude.json (user scope). If servers are found parked in ~/.claude/settings.json — where Claude Code ignores them — that file is also listed, marked legacy, so you can copy them over.

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).
• bcc.spec — PyInstaller build spec (cross-platform).
• scripts/build_icons.py — regenerates icons/app.icns and icons/app.ico from source PNGs.
• scripts/sign_checksums.py — generates and Ed25519-signs the release SHA256SUMS manifest (see Verifying your download).

Building from source

pip install -r requirements-dev.txt
python scripts/build_icons.py   # regenerate icons if needed
pyinstaller bcc.spec
# macOS  → dist/BetterClaudeConfig.app
# Windows → dist/BetterClaudeConfig.exe
# Linux  → dist/BetterClaudeConfig

Releases are built automatically by GitHub Actions (.github/workflows/release.yml) when a version tag is pushed:

git tag v1.0.0 && git push --tags

Rebrand

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

License

MIT — see LICENSE.