AJ
b16c0fd526
Claude Code stores user-scope MCP servers in ~/.claude.json (what 'claude mcp add' writes); ~/.claude/settings.json is for permissions and hooks and rejects an mcpServers key with a schema error, so BCC was reading (and writing) servers where Claude Code never looks. If servers are found parked in settings.json, that file is still listed as 'Claude Code (legacy settings.json)' so they can be copied into the real config via Copy to. Docs updated; verified against docs.claude.com/en/docs/claude-code/settings.
120 lines
5.2 KiB
Markdown
120 lines
5.2 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'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.
|
|
|
|
## 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).
|