Mcp Sync

mcp-sync

> Zero-polling MCP config sync for macOS — keeps all your IDEs' MCP server configs perfectly in sync. > Uses Apple's native FSEvents API via fswatch for instant, battery-friendly file watching.

Supported IDEs: Windsurf · VSCode · Cursor · Zed · Claude Code · OpenCode

---

What it does

~/.config/mcp-servers.json             ← canonical (single source of truth)
           │
           │  fswatch (FSEvents, zero-poll, bidirectional)
           │
           ├──► ~/.codeium/windsurf/mcp_config.json       (Windsurf)
           ├──► ~/Library/Application Support/Code/User/mcp.json  (VSCode)
           ├──► ~/.cursor/mcp.json                        (Cursor)
           ├──► ~/.config/zed/settings.json               (Zed)
           ├──► ~/.claude.json                            (Claude Code)
           └──► ~/.config/opencode/opencode.json          (OpenCode)

Bidirectional sync: Edit your MCP config in any IDE — the change propagates instantly to all others via the canonical file. Each IDE gets its native format automatically:

| IDE | Format | |-----|--------| | Windsurf | {"mcpServers": {...}} | | VSCode | {"servers": {...}} with type field | | Cursor | {"mcpServers": {...}} | | Zed | {"context_servers": {...}} with source: "custom" | | Claude Code | {"mcpServers": {...}} merged into existing ~/.claude.json | | OpenCode | {"mcpServers": {...}} |

---

Requirements

• macOS (Apple Silicon or Intel)
• Homebrew
• At least one IDE with MCP support installed

---

Install

git clone https://github.com/VrilLabs/mcp-sync.git
cd mcp-sync
chmod +x install.sh && ./install.sh

The installer will:

1. brew install fswatch jq (if not present)
2. Copy scripts to ~/.config/mcp-sync/scripts/
3. Install the mcp CLI to ~/.local/bin/
4. Bootstrap ~/.config/mcp-servers.json from your existing IDE config
5. Register + load the launchd agent (auto-starts on login, watches all IDEs)
6. Detect installed IDEs and report status

That's it — install once, forget forever. The background agent handles everything automatically.

Add to PATH (if prompted)

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

---

Uninstall

./uninstall.sh

---

CLI Reference (mcp)

Sync & Status

| Command | Description | |---------|-------------| | mcp list | List all MCP servers from canonical config | | mcp status | Full sync status (agent, fswatch, all IDEs) | | mcp sync | Manually trigger a sync right now | | mcp diff | Compare canonical vs each IDE target | | mcp paths | Print all config file paths | | mcp logs | Tail last 20 lines of sync log | | mcp logs -n 50 | Tail last N lines |

Server Management

| Command | Description | |---------|-------------| | mcp add [args] | Add a server to canonical and sync to all IDEs | | mcp remove | Remove a server from canonical and sync | | mcp install | Install an MCP server from the registry | | mcp uninstall | Uninstall an MCP server package | | mcp search [query] | Search available MCP servers in registry | | mcp test | Test an MCP server (starts it, checks protocol) |

Diagnostics

| Command | Description | |---------|-------------| | mcp doctor | Validate all IDE MCP configs | | mcp doctor vscode cursor | Validate specific IDEs | | mcp agent start\|stop\|restart\|status | Control the launchd agent |

---

Examples

# List all configured MCP servers
mcp list

# Check everything is working
mcp status

# Validate all IDE configs are correct
mcp doctor

# Validate just Cursor and Zed
mcp doctor cursor zed

# Search the MCP registry for filesystem servers
mcp search filesystem

# Install a server from the registry
mcp install @modelcontextprotocol/server-filesystem

# Add a custom server manually
mcp add my-server npx -- -y @my/mcp-server

# Add with env vars
mcp add github npx -- -y @modelcontextprotocol/server-github -e GITHUB_TOKEN=ghp_xxx

# Test a server responds to MCP protocol
mcp test my-server

# Remove a server
mcp remove old-server

# Force a manual sync
mcp sync

# Restart the background agent
mcp agent restart

---

How Sync Works

1. fswatch monitors all IDE config files using macOS FSEvents (zero CPU, no polling)
2. When any file changes, sync-mcp.sh fires
3. A re-entrancy lock prevents sync loops (writes are ignored for 5s)
4. The changed file updates the canonical ~/.config/mcp-servers.json
5. Canonical is then projected to all IDE targets in their native format
6. All writes are atomic (temp file + mv) — no partial/corrupt configs
7. Files are created with 600 permissions (owner-only read/write)

---

MCP Tool Registry

mcp-sync integrates with mcp-get to provide a curated registry of MCP servers you can install directly from the CLI:

# Browse all available servers
mcp search

# Search for specific functionality
mcp search github
mcp search filesystem

# Install a server (auto-syncs to all IDEs)
mcp install @modelcontextprotocol/server-filesystem

# Uninstall
mcp uninstall @modelcontextprotocol/server-filesystem

No API keys or authentication required — the registry is fully open and free.

---

Doctor Command

The doctor command validates your MCP configs against each IDE's specific requirements:

$ mcp doctor
mcp doctor — validating MCP configurations

  windsurf (~/.codeium/windsurf/mcp_config.json)
    ✓ Valid JSON
    ✓ Has 'mcpServers' key
    ✓ filesystem: valid
    ✓ github: valid

  vscode (~/Library/Application Support/Code/User/mcp.json)
    ✓ Valid JSON
    ✓ Has 'servers' key
    ✓ filesystem: valid

  cursor (~/.cursor/mcp.json)
    ✓ Valid JSON
    ✓ Has 'mcpServers' key
    ✓ filesystem: valid

  zed (~/.config/zed/settings.json)
    ✓ Valid JSON
    ✓ Has 'context_servers' key
    ✓ filesystem: valid

✓ All checks passed!

Checks performed per IDE:

• Valid JSON syntax
• Correct top-level key (mcpServers, servers, context_servers)
• VSCode: type field present (stdio/http)
• Zed: source field present
• Server entries have command or url
• args is an array, env is an object
• File permissions (recommends 600)

---

launchd Agent

# Check agent is running
mcp agent status

# View live log
tail -f ~/.config/mcp-sync/sync.log

# Restart after changes
mcp agent restart

---

File Locations

| File | Purpose | |------|---------| | ~/.config/mcp-servers.json | Canonical single source of truth | | ~/.codeium/windsurf/mcp_config.json | Windsurf (watched + synced) | | ~/Library/Application Support/Code/User/mcp.json | VSCode (watched + synced) | | ~/.cursor/mcp.json | Cursor (watched + synced) | | ~/.config/zed/settings.json | Zed (watched + synced) | | ~/.claude.json | Claude Code (watched + synced) | | ~/.config/opencode/opencode.json | OpenCode (watched + synced) | | ~/.config/mcp-sync/scripts/sync-mcp.sh | Core sync script | | ~/.config/mcp-sync/sync.log | Sync activity log | | ~/.config/mcp-sync/sync.err | Error log | | ~/Library/LaunchAgents/com.user.mcp-sync.plist | launchd agent | | ~/.local/bin/mcp | CLI helper |

---

Security

• All config files written with 600 permissions (owner read/write only)
• Atomic writes prevent corruption from partial writes or race conditions
• Re-entrancy lock prevents infinite sync loops
• Sensitive env vars (*KEY*, *TOKEN*, *SECRET*) are masked in mcp list output
• No network calls — everything runs locally

---

Troubleshooting

# Full status check
mcp status

# Validate configs
mcp doctor

# Check for errors
cat ~/.config/mcp-sync/sync.err

# View detailed log
mcp logs -n 50

# Force restart everything
mcp agent restart && mcp sync

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VrilLabs
• Source: VrilLabs/mcp-sync
• License: MIT
• Homepage: https://vril.li

Install and usage instructions live in the source repository linked above.