AJ Avezzano
dd7557ea62
- Auto-discovers Claude Code (~/.claude/settings.json) alongside Claude Desktop - Generated icons/app.icns (macOS) and icons/app.ico (Windows) from rounded PNGs - bcc.spec: PyInstaller spec for all platforms (.app on macOS, onefile on Windows/Linux) - .github/workflows/release.yml: builds and publishes GitHub Release on version tags - scripts/build_icons.py: regenerates icon files from source PNGs - requirements-dev.txt: adds pyinstaller and pillow for building - CLAUDE.md: initial repo guidance for Claude Code Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
113 lines
4.6 KiB
Markdown
113 lines
4.6 KiB
Markdown
# 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](../../releases):
|
|
|
|
| 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.
|
|
|
|
## Run from source
|
|
|
|
```bash
|
|
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 at `~/.claude/settings.json`. Use **Add config…** to point at any
|
|
other 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
|
|
|
|
**Claude Desktop**
|
|
|
|
| OS | Base it scans for `Claude*` |
|
|
|---------|----------------------------------|
|
|
| macOS | `~/Library/Application Support` |
|
|
| Windows | `%APPDATA%` |
|
|
| Linux | `~/.config` |
|
|
|
|
**Claude Code** (all platforms): `~/.claude/settings.json`
|
|
|
|
## 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.
|
|
|
|
## Building from source
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](LICENSE).
|