claude-code-desktop-sync MCP server
Commit Nov 13, 2026Synchronizes MCP server configurations between Claude Code and Claude Desktop to prevent configuration drift.
Also known as haiggoh/claude-code-desktop-sync
- Stars
- 2
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is claude-code-desktop-sync MCP?
claude-code-desktop-sync synchronizes MCP server configurations between Claude Code and Claude Desktop to prevent configuration drift.
Summary generated from the project's README
About claude-code-desktop-sync MCP server
Keeping your MCP server configurations identical across Claude Code and Claude Desktop is what this tool accomplishes. It automates the mirroring of stdio MCP servers between the ~/.claude.json file and the Claude Desktop configuration, preventing manual copy-paste errors and configuration drift. It is designed for developers using both environments on macOS, Windows, or Linux who want a unified toolset without managing two separate configuration files.
The synchronization runs automatically via a SessionStart hook in Claude Code. It handles complex transitions by rewriting relative launchers like npx into absolute paths so they function correctly in the Desktop environment. For servers that cannot be automatically synced, such as those requiring HTTP header authentication or specific connectors, the tool provides explicit manual instructions instead of failing. It prioritizes safety by creating timestamped backups of your configuration files before making any changes and uses a content-based reconciliation method to avoid overwriting conflicting updates.
What you can do with it
- 1Automate server mirroringSynchronize your stdio MCP servers between Claude Code and Claude Desktop automatically.
- 2Fix path issues for DesktopEnsure npx and other relative launchers work in Claude Desktop by converting them to absolute paths.
- 3Manage non-syncable connectorsIdentify HTTP or header-authenticated servers that require manual setup in the Desktop UI.
- 4Troubleshoot configuration statusUse the companion skill to check why a specific server is not appearing in your Desktop environment.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablehaiggoh/claude-code-desktop-sync is public and reachablegithub.com/haiggoh/claude-code-desktop-sync ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/haiggoh/claude-code-desktop-sync ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubclaude-code-desktop-sync
Keep Claude Code and Claude Desktop in sync. Add or change an MCP server in one, and it is mirrored to the other automatically — no manual copy-paste, no drifting configs. For everything that can't be synced (a hard platform limit), the tool tells you the exact manual step instead of failing silently.
It installs on a vanilla Claude Code + Claude Desktop setup, merges cleanly into existing config (never clobbers), backs up before every change, and is fully reversible.
What it does
- ✅ Auto-syncs stdio MCP servers both ways between
~/.claude.json(Code) and Claude Desktop's config file. Relative launchers likenpxare rewritten to absolute paths for Desktop (which has no shellPATH). - ⚠️ Detects HTTP / header-auth MCP servers (e.g. a PAT-authenticated
githubconnector) that can't live in the Desktop config file, and prints the one-time manual step (Desktop → Connectors UI). - ❌ Clearly documents what is not syncable — skills, memory, settings, extensions, and sessions/conversations live in separate stores the two apps don't share.
Runs automatically via a Claude Code SessionStart hook, and stays silent unless something changed.
Why not everything? Claude Desktop is a separate application that does not read Claude Code's files, hooks, or memory. Only configuration that lives in a file both apps read (the MCP server list) can be synced automatically. See
docs/SYNC-REFERENCE.mdfor the full matrix and the reasoning.
Requirements
- Claude Code and/or Claude Desktop installed (the sync is a no-op if only one is present).
- Python 3.8+ (standard library only — no pip installs). The plugin hook runs
python3, so it must be onPATH(it is on macOS/Linux and with Microsoft Store Python on Windows). On Windows with python.org Python (which installspython/py, notpython3), use the standaloneinstall.pyinstead — it resolves whichever interpreter you have and writes an absolute path into the hook. - macOS, Windows, or Linux.
Install
Option A — as a Claude Code plugin (recommended)
This repo is a Claude Code plugin, part of the haiggoh marketplace (catalog now hosted
at haiggoh/get-haiggoh, not here). From inside
Claude Code:
/plugin marketplace add haiggoh/get-haiggoh
/plugin install claude-code-desktop-sync@haiggoh
That's it — the plugin registers the SessionStart hook itself (no files copied into your
settings.json) and ships a companion skill. Restart Claude Code (and Claude Desktop, if it was open)
so each app reloads its config.
Option B — standalone (no plugin system)
If you'd rather just wire the hook directly into your own config:
git clone https://github.com/haiggoh/claude-code-desktop-sync.git
cd claude-code-desktop-sync
python3 install.py # or: python3 install.py --dry-run
The standalone installer:
- Copies the engine to
~/.claude/desktop-sync/sync_code_desktop.py. - Adds a
SessionStarthook to~/.claude/settings.json(merged into any existing hooks). - Adds a marker-bounded instruction block to
~/.claude/CLAUDE.mdso Claude Code sessions know the sync rules and always surface manual steps. - Runs an initial sync.
Restart Claude Code (and Claude Desktop, if it was open) so each app reloads its config.
The companion skill
The plugin bundles a model-invoked skill, desktop-sync, for on-demand help — run a sync now, check
what is/isn't syncing, or troubleshoot a missing server. Invoke it with
/claude-code-desktop-sync:desktop-sync, or just ask Claude in natural language (e.g. "sync my MCP
servers to Desktop" / "why isn't my github connector in Desktop?") and it loads automatically.
Usage
Once installed there's nothing to do — it runs at each Code session start. To sync on demand:
-
Plugin install (Option A): ask Claude to "sync my MCP servers to Desktop", or invoke the companion skill
/claude-code-desktop-sync:desktop-sync. The engine lives in the versioned plugin cache (e.g.~/.claude/plugins/cache/haiggoh/claude-code-desktop-sync/<version>/bin/sync_code_desktop.py), so don't hardcode its path — the skill resolves it for you. -
Standalone install (Option B): run the copied engine directly:
python3 ~/.claude/desktop-sync/sync_code_desktop.py
Example output when you've added a server in Code:
[claude-sync] updated Claude Desktop config (backup: ~/.claude/desktop-sync/backups/claude_desktop_config.json.20260701-183531.bak)
+ added to Desktop: my-new-server
Conflict handling
Reconciliation is per-server and content-based (a snapshot of the last-synced value on each side), never timestamp-based. For each server: a change on exactly one side is propagated to the other; an add is mirrored; a delete (present in the snapshot, now gone) is mirrored. If the same server was changed differently on both sides, it is a conflict: both sides are left untouched and reported by name for you to resolve — nothing is silently overwritten. A name that is a stdio server in one app but an HTTP/connector in the other is likewise held and reported (so a connector and its token are never clobbered). On the first run, servers present on only one side are added to the other (a safe union — nothing is deleted).
Safety
- Backs up every file before writing it (timestamped, under
~/.claude/desktop-sync/backups/; mode600since~/.claude.jsonmay hold a plaintext token). - Only ever changes the
mcpServersblock — all other keys and values are preserved (the file is re-serialized with 2-space indentation andensure_ascii=False, so values are kept but original whitespace/formatting is normalized). - The hook never raises: if anything goes wrong it exits cleanly so it can't block a session from starting.
Uninstall
python3 uninstall.py # remove hook + CLAUDE.md block
python3 uninstall.py --purge # also delete ~/.claude/desktop-sync
How it works
See docs/SYNC-REFERENCE.md for config locations, the full sync matrix,
conflict rules, and the backup/restore procedure.
License
MIT — see LICENSE.
Not affiliated with Anthropic. "Claude" is a trademark of Anthropic. This is a community tool.
claude-code-desktop-sync MCP questions
Does this tool sync HTTP or header-authenticated MCP servers?
No, HTTP or header-authenticated servers cannot be synced to the Desktop config file; the tool will instead print the manual step required to add them via the Desktop Connectors UI.
Is my configuration safe during the sync process?
Yes, the tool backs up every configuration file before writing any changes and only modifies the mcpServers block, preserving all other keys.
What are the system requirements for installation?
You need Claude Code and/or Claude Desktop installed, along with Python 3.8 or higher on macOS, Windows, or Linux.