mcp-sync

mcp-sync is a CLI tool designed to manage and synchronize MCP (Model Context Protocol) server configurations across multiple AI tools and editors. It supports auto-discovery of existing MCP config files on your system, as well as manual registration of new config locations. Configurations can be stored globally (for all tools) or scoped to a project, with project configs taking precedence during synchronization. The tool offers dry-run previews so you can see what would change before applying updates, and it can resolve conflicts intelligently so that your project configurations remain authoritative.

Once installed, you can scan your system for known MCP configs, inspect the current synchronization status, and then merge or push changes to registered locations. The built-in commands let you add or remove servers to sync, manage where those servers live (global vs project scope), and perform full or partial syncs across all registered configs or specific locations. It supports a range of clients and editors (Claude Desktop, Claude Code, Cline, Roo, VS Code settings, Cursor, and Continue) and allows you to add custom client definitions if you’re supporting tools outside the built-in set.

Prerequisites:

• Python 3.12+ (required for uv-based workflow shown in the documentation)
• uv (the package manager referenced in the README) installed on your system

Installation steps (recommended quick path):

1. Install the MCP Sync tool globally via uv:

uv tool install mcp-sync

2. Verify installation and see status:

mcp-sync status

Development installation (if you are contributing to the project):

git clone <repo-url>
cd mcp-sync
./scripts/setup.sh    # Installs dependencies and git hooks automatically

Upgrade or reinstall considerations:

• If you have an existing global config, run mcp-sync status to verify integrity after upgrade.
• Use mcp-sync diff before mcp-sync sync to preview changes.

Tips and common considerations:

• Global vs project config: project config takes priority during sync; use this to lock down environment-specific settings.
• Dry-run mode is your friend: always preview with mcp-sync diff or mcp-sync sync --dry-run before applying.
• Custom clients: you can add new client definitions via mcp-sync edit-client-definitions which creates ~/.mcp-sync/client_definitions.json. User definitions override built-ins.
• Auto-discovery can detect tool-specific config locations; if a location isn’t detected, use mcp-sync add-location <path> to register it manually.
• For scripting and automation, you can run mcp-sync sync --location <path> to target a single configuration location.