the_og
febd617c56
BCC has always been dark-only -- BG #1b1d23, hardcoded at import time, with no light option and no awareness of the desktop's appearance. On a light desktop it matches nothing else on screen and there was no way to change it. Adds a Palette value type in bcc_core with DARK (byte-identical to the colours v1.3.0 shipped) and a new LIGHT, plus resolve_theme(setting, system_is_dark) so the decision is testable without a Qt app. View > Theme offers Match system / Light / Dark, persisted in QSettings under ui/theme, defaulting to following the system. The light palette's semantic colours are deliberately not the dark ones lightened: #4ade80 sits near 1.7:1 against white. They are darkened to clear WCAG AA, and a contrast test enforces >= 4.5:1 for every text colour against its surface in both palettes so nobody harmonises them back later. Three near-black literals were baked into the stylesheet (#1a1205 on-accent text, #202229 disabled table, #16181d diagnostics pane). Fine with one theme, invisible breakage with two -- each now has a palette slot, and a test asserts build_stylesheet contains no hex literals at all. The ~20 inline setStyleSheet(f"color: {MUTED}") call sites are left alone: apply_palette rebinds the module-level colour names, and an f-string resolves its names when it runs, so each call site picks up the new colour on its next render. Switching theme reapplies the global QSS and re-renders the inline-styled widgets, so nothing is left dark-on-light. Refs #75
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.appin 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.
This manifest is signed with BCC's release key, which is a different
key from the one that signs the MCP server catalog — see
Signing keys below for why, and for the public key value
to use with --pubkey-b64 below.
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 release public key from Signing keys, below>"
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.
Signing keys
BCC uses two separate Ed25519 keypairs, deliberately never the same key, because they protect different things and live in different places:
| Catalog key | Release key | |
|---|---|---|
| Signs | data/catalog.json (the MCP server catalog every user's app trusts) |
SHA256SUMS (the checksum manifest for release binaries) |
| Verified by | bcc_core.CATALOG_PUBKEYS |
scripts/sign_checksums.RELEASE_PUBKEYS |
| Lives | Offline, passphrase-encrypted, maintainer's machine only (OS keychain or an encrypted file outside the repo — see the Catalog Console, issue #62) | A Gitea Actions repo secret, RELEASE_SIGNING_KEY — intentionally CI-resident |
| Generated with | python catalog_console.py keygen |
python catalog_console.py keygen --release |
| Exported for CI with | (never — there is no supported way to export this key) | python catalog_console.py show-seed-b64 --release |
Why two keys: the catalog key is the root of trust for what BCC
actually executes on a user's machine — every command/args pair in
the shipped catalog is only there because this key signed it. If that key
and the release-checksum key were the same (as they briefly were — see
issue #68), then anything that can exfiltrate a Gitea
Actions secret (a malicious workflow-file PR, a compromised runner, a leaky
log) could sign a catalog every user's copy of BCC would trust, not just a
checksum manifest. Splitting them means a CI/secret compromise burns the
release key, never the catalog key — checksums for a future release could
be forged, which is bad, but no attacker gains the ability to make BCC run
arbitrary commands on installs that trust the catalog. That asymmetry is
the entire point of having two keys instead of one.
The catalog key is never meant to leave the maintainer's machine: it's
generated, stored, unlocked, and used to sign entirely inside the Catalog
Console (catalog_console.py), and catalog_console.py show-seed-b64
refuses to run without --release specifically so the catalog seed can't
be exported by habit or muscle memory.
Release signing public key (Ed25519, base64, raw 32 bytes) — this is the RELEASE key, not the catalog key:
<PLACEHOLDER — AJ: paste the release public key from `catalog_console.py keygen --release` here>
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 (soClaudeandClaude-Workboth show up) and finds Claude Code's user-scope config at~/.claude.json(the fileclaude mcp addwrites). 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
mcpServersblock, 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
.jsonfile 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
commandis 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
.appmay 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— regeneratesicons/app.icnsandicons/app.icofrom source PNGs.scripts/sign_checksums.py— generates and Ed25519-signs the releaseSHA256SUMSmanifest (see Verifying your download).catalog_console.py/catalog_review.py— maintainer-only, never shipped to users (excluded frombcc.spec; seetests/test_catalog_console_packaging.py). The Catalog Console: review + signdata/catalog.json, and generate/manage both signing keys (keygen,keygen --release) — see Signing keys.
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.