mcp-sync
Sync MCP (Model Context Protocol) configurations across AI tools.
Overview
mcp-sync is a command-line tool that helps you manage and synchronize MCP server configurations across different AI coding tools like Claude Desktop, Claude Code, Cline, VS Code extensions, and more.
Features
- Auto-discovery: Automatically finds MCP configs on your system
- Manual registration: Add custom config file locations for future-proofing
- Global & project configs: Supports both user-wide and project-specific servers
- Conflict resolution: Smart merging with project configs taking priority
- Dry-run mode: Preview changes before applying them
- Cross-platform: Works on macOS, Windows, and Linux
Installation
Quick Usage (Recommended)```bash
uvx mcp-sync status
uvx mcp-sync sync --dry-run
### Persistent Installation```bash
uv tool install mcp-sync
mcp-sync status
Development Install```bash
git clone <repo-url>
cd mcp-sync
./scripts/setup.sh # Installs dependencies and git hooks automatically
## Quick Start
1. **Scan for existing configs**:```bash
mcp-sync scan
```
2. **Check current status**:```bash
mcp-sync status
```
3. **Add a server to global config**:```bash
mcp-sync add-server filesystem
# Follow prompts to configure
```
4. **Preview sync changes**:```bash
mcp-sync diff
mcp-sync sync --dry-run
```
5. **Sync configurations**:```bash
mcp-sync sync
```
## Commands
### Discovery & Status
- `mcp-sync scan` - Auto-discover known MCP configs
- `mcp-sync status` - Show sync status
- `mcp-sync diff` - Show config differences
### Config Location Management
- `mcp-sync add-location [--name ]` - Register custom config file
- `mcp-sync remove-location ` - Unregister config location
- `mcp-sync list-locations` - Show all registered config paths
### Sync Operations
- `mcp-sync sync` - Sync all registered configs
- `mcp-sync sync --dry-run` - Preview changes without applying
- `mcp-sync sync --global-only` - Sync only global configs
- `mcp-sync sync --project-only` - Sync only project configs
- `mcp-sync sync --location ` - Sync specific location only
### Server Management
- `mcp-sync add-server ` - Add MCP server to sync (interactive prompts)
- `mcp-sync add-server --command --args --env --scope ` - Add server with inline parameters
- `mcp-sync remove-server ` - Remove server from sync (interactive prompts)
- `mcp-sync remove-server --scope ` - Remove server with inline scope
- `mcp-sync list-servers` - Show all managed servers
### Migration
- `mcp-sync vacuum` - Import MCP servers from discovered configs
- `--auto-resolve ` choose conflict resolution automatically
- `--skip-existing` avoid overwriting servers already in global config
**Adding Servers**: When adding a server, you need to provide:
- **Command**: The executable to run (e.g., `python`, `npx`, `node`)
- **Arguments**: Command-line arguments (comma-separated, optional)
- **Environment**: Environment variables as `KEY=value` pairs (comma-separated, optional)
- **Scope**: Whether to add to global config (synced everywhere) or project config (this project only)
Interactive example:```bash
mcp-sync add-server filesystem
# Prompts for: scope, command, args, env vars
Automated example:```bash
mcp-sync add-server filesystem --command npx --args "-y,@modelcontextprotocol/server-filesystem,/home/user/docs" --scope global
### Project Management
- `mcp-sync init` - Create project `.mcp.json`
- `mcp-sync template` - Show template config
### Client Management
- `mcp-sync list-clients` - Show all supported clients and their detection status
- `mcp-sync client-info [client-id]` - Show detailed client information and paths
- `mcp-sync edit-client-definitions` - Edit user client definitions to add custom clients
## Configuration Hierarchy
`mcp-sync` uses a three-tier configuration system:
1. **Global Config** (`~/.mcp-sync/global.json`)
- Personal development servers
- Synced across all tools
2. **Project Config** (`.mcp.json` in project root)
- Project-specific servers
- Version controlled with your project
- Takes priority over global config
3. **Tool Configs** (Auto-discovered locations)
- Claude Desktop, VS Code, Cline, etc.
- Updated by sync operations
## Supported Tools
mcp-sync uses a **configuration-driven approach** to support AI tools and editors. Client definitions are managed through JSON configuration files.
**Built-in client support:**
- **Claude Desktop** - Official Claude Desktop application
- **Claude Code** - Claude CLI for code editing
- **Cline** - VS Code extension for AI assistance
- **Roo** - Roo VS Code extension for AI assistance
- **VS Code User Settings** - VS Code global user settings
- **Cursor** - Cursor AI code editor
- **Continue** - Continue VS Code extension
Run `mcp-sync list-clients` to see which clients are detected on your system, or `mcp-sync client-info ` for detailed information about specific clients.
**Adding custom clients:** Users can add their own client definitions by running `mcp-sync edit-client-definitions`. This creates `~/.mcp-sync/client_definitions.json` where custom client configurations can be added. User definitions take precedence over built-in ones, allowing customization and adding support for new tools without modifying the codebase.
## Example Workflow```bash
# 1. Initialize project config
mcp-sync init
# 2. Add project-specific server
mcp-sync add-server database
# Choose "2. Project config"
# Command: python
# Args: /path/to/db-server.py
# Env: DB_URL=postgresql://...
# 3. Add global development server
mcp-sync add-server filesystem
# Choose "1. Global config"
# Command: npx
# Args: -y, @modelcontextprotocol/server-filesystem, /home/user
# 4. Sync to all tools
mcp-sync sync
# 5. Check status
mcp-sync status
Configuration File Format
MCP Server Configuration```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/directory"
]
},
"custom-server": {
"command": "python",
"args": ["/path/to/server.py"],
"env": {
"API_KEY": "your-api-key"
}
}
}
}
## Development
### Requirements
- Python 3.12+
- uv package manager
### Setup```bash
git clone <repo-url>
cd mcp-sync
uv sync
uv pip install -e .
Code Quality```bash
uv run ruff check . # Linting
uv run ruff format . # Formatting
uv run pytest # Tests (when available)
### Running Tests
Tests require the package to be on `PYTHONPATH`. Either install it in editable mode:```bash
uv pip install -e .
uv run pytest
or set PYTHONPATH manually when invoking pytest:bash
PYTHONPATH=$PWD uv run pytest
License
[License details here]
Contributing
[Contributing guidelines here]
