midos-mcp-sync

Stop editing JSON files. Start building.

Detect, validate, and synchronize MCP server configurations across all your AI tools — Claude Desktop, Cursor, VS Code Copilot, Windsurf, and more.

The Problem

Using 2+ MCP clients? Every new MCP server means manually editing 3-6 separate config files in different locations and formats. Configs drift between machines and teammates. midos-mcp-sync fixes this.

Install

pip install midos-mcp-sync

Quick Start

# 1. Detect all MCP configs on your machine
midos-mcp-sync detect

# 2. Validate a config file
midos-mcp-sync validate

# 3. Preview what sync would change (dry-run by default)
midos-mcp-sync sync

# 4. Apply sync across all clients
midos-mcp-sync sync --apply

Commands

detect — Find all MCP configs

Auto-discovers configs from Claude Desktop, Cursor, VS Code Copilot, Windsurf, and project-level .mcp.json files.

midos-mcp-sync detect
midos-mcp-sync detect --project ./my-project
midos-mcp-sync detect --json

validate — Check config correctness

Validates structure, server entries, transport types, and best practices.

midos-mcp-sync validate
midos-mcp-sync validate path/to/.mcp.json

sync — Synchronize across clients

Merges all detected configs using union strategy. Conflicts resolved by newest-file-wins.

# Preview changes (dry-run, default behavior)
midos-mcp-sync sync
midos-mcp-sync sync --dry-run

# Apply changes
midos-mcp-sync sync --apply

# Output sync plan as JSON
midos-mcp-sync sync --json

diff — Compare two configs

midos-mcp-sync diff config-a.json config-b.json

merge — Combine configs

midos-mcp-sync merge base.json overlay.json
midos-mcp-sync merge base.json overlay.json -o merged.json

init — Create template config

midos-mcp-sync init
midos-mcp-sync init path/to/.mcp.json
midos-mcp-sync init --force  # overwrite existing

export — Export in different formats

midos-mcp-sync export .mcp.json --format json
midos-mcp-sync export .mcp.json --format yaml

list / register — Local config registry

midos-mcp-sync register .mcp.json --name my-project
midos-mcp-sync list

Supported Surfaces

How Sync Works

1. Detect all MCP configs across installed AI clients
2. Merge servers using union strategy (all servers from all configs)
3. Resolve conflicts — same server name with different settings: newest file wins
4. Preview changes in dry-run mode (default)
5. Apply writes the merged config back to each client's config file

Optional Dependencies

# For YAML export support
pip install midos-mcp-sync[yaml]

YAML export works without pyyaml using a built-in minimal formatter.

Development

git clone https://github.com/midos-community/midos-mcp-sync.git
cd midos-mcp-sync
pip install -e ".[dev]"
pytest

License

MIT