MCP Config Sync

A Python package for synchronizing Model Context Protocol (MCP) server configurations across different AI tools and applications.

Overview

MCP Config Sync helps you maintain consistent MCP server configurations across multiple tools like Claude Desktop, Amazon Q, VS Code extensions, and other MCP-compatible applications. It automatically discovers, combines, and synchronizes your MCP server configurations, ensuring all your tools have access to the same servers.

Features

• Automatic Discovery: Finds MCP configuration files across common locations
• Smart Merging: Combines unique MCP servers from multiple configuration files
• Conflict Resolution: Handles conflicting configurations intelligently
• Backup Support: Creates backups before modifying files (enabled by default)
• Cross-Platform: Works on macOS, Linux, and Windows
• Dry Run Mode: Preview changes before applying them
• Flexible Configuration: Support for custom configuration file paths

Installation

From PyPI (Recommended)

pip install mcp-config-sync

From Source

git clone https://github.com/jon-the-dev/mcp_config_sync.git
cd mcp_config_sync
pip install -e .

Quick Start

Command Line Usage

After installation, you can use the mcp-config-sync command:

# Preview changes for all registered MCP applications (default behavior)
mcp-config-sync

# Actually sync all registered MCP applications
mcp-config-sync --sync

# List all available MCP applications
mcp-config-sync --list-apps

# Preview changes for specific applications only
mcp-config-sync --apps amazonq cline

# Actually sync specific applications only
mcp-config-sync --apps amazonq cline --sync

# List all discovered MCP servers
mcp-config-sync --list-all

# Preview removal of a specific server from all configurations
mcp-config-sync --remove server-name

# Actually remove a specific server from all configurations
mcp-config-sync --remove server-name --sync

# Skip creating backup files during sync
mcp-config-sync --sync --no-backup

# Enable verbose logging
mcp-config-sync --verbose

Python API Usage

from mcp_config_sync import MCPServerSync

# Initialize the synchronizer for all apps
syncer = MCPServerSync()

# Or initialize for specific apps
syncer = MCPServerSync(apps=["amazonq", "cline"])

# Or use custom config files
syncer = MCPServerSync(config_files=["/path/to/config1.json", "/path/to/config2.json"])

# Discover existing configuration files
syncer.discover_config_files()

# Combine MCP servers from all files
syncer.combine_mcp_servers()

# Get all servers
servers = syncer.list_all_servers()
print(f"Found {len(servers)} MCP servers")

# Sync configurations across all files
results = syncer.replace_all_configs()

Working with Apps

from mcp_config_sync import get_all_apps, get_app_names, get_app

# Get all available apps
apps = get_all_apps()
print(f"Available apps: {list(apps.keys())}")

# Get app names only
app_names = get_app_names()
print(f"App names: {app_names}")

# Get specific app info
app = get_app("amazonq")
if app:
    print(f"App: {app.display_name}")
    print(f"Config: {app.config_path}")

Supported Applications

MCP Config Sync supports the following MCP-compatible applications:

App Name	Display Name	Description	Config Path
amazonq	Amazon Q	Amazon Q AI assistant configuration	~/.aws/amazonq/mcp.json
cline	Cline (VS Code)	Cline VS Code extension MCP settings	~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
claude-desktop	Claude Desktop	Anthropic Claude Desktop application	~/Library/Application Support/Claude/claude_desktop_config.json

Adding New Applications

To add support for a new MCP application, you can:

1. Submit a Pull Request: Add the new app to mcp_config_sync/apps.py
2. Use Custom Config Files: Use the --config-files option for one-off usage

Example PR to add a new app:

# In mcp_config_sync/apps.py
"new-app": MCPApp(
    name="new-app",
    display_name="New MCP App",
    config_path="~/path/to/new-app/config.json",
    description="Description of the new MCP application",
    homepage="https://example.com",
),

You can specify custom paths using the --config-files option:

mcp-config-sync --config-files /path/to/config1.json /path/to/config2.json

Configuration File Format

MCP configuration files should contain a mcpServers object:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key"
      }
    }
  }
}

Examples

Basic Synchronization

# Preview changes for all registered MCP applications (default)
mcp-config-sync

# Actually sync all registered MCP applications
mcp-config-sync --sync

This will:

1. Discover all existing MCP configuration files for registered apps
2. Extract and combine unique MCP servers
3. Show a preview of what changes would be made (default behavior)
4. With --sync: Create backups of existing files and write the unified configuration to all files

Sync Specific Applications

# Preview changes for only Amazon Q and Cline
mcp-config-sync --apps amazonq cline

# Actually sync only Amazon Q and Cline
mcp-config-sync --apps amazonq cline --sync

List Available Applications

mcp-config-sync --list-apps

Output:

============================================================
AVAILABLE MCP APPLICATIONS
============================================================

Found 3 registered MCP applications:
----------------------------------------

📱 App: amazonq
   Display Name: Amazon Q
   Description: Amazon Q AI assistant configuration
   Config Path: ~/.aws/amazonq/mcp.json
   Status: ✓ CONFIG EXISTS
   Homepage: https://aws.amazon.com/q/

📱 App: cline
   Display Name: Cline (VS Code)
   Description: Cline VS Code extension MCP settings
   Config Path: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   Status: ✓ CONFIG EXISTS
   Homepage: https://github.com/saoudrizwan/claude-dev

📱 App: claude-desktop
   Display Name: Claude Desktop
   Description: Anthropic Claude Desktop application
   Config Path: ~/Library/Application Support/Claude/claude_desktop_config.json
   Status: ✓ CONFIG EXISTS
   Homepage: https://claude.ai/

============================================================
Total: 3 applications (3 with existing configs)
============================================================

List All Servers

mcp-config-sync --list-all

Output:

============================================================
ALL MCP SERVERS
============================================================

Found 3 MCP servers:
----------------------------------------

🔧 Server: filesystem
   Command: npx
   Args: -y @modelcontextprotocol/server-filesystem /Users/jon/Documents

🔧 Server: brave-search
   Command: npx
   Args: -y @modelcontextprotocol/server-brave-search
   Environment Variables: BRAVE_API_KEY

🔧 Server: postgres
   Command: npx
   Args: -y @modelcontextprotocol/server-postgres
   Environment Variables: POSTGRES_CONNECTION_STRING

Remove a Server

# Preview removal of a specific server from all configurations
mcp-config-sync --remove old-server-name

# Actually remove a specific server from all configurations
mcp-config-sync --remove old-server-name --sync

Preview Changes

# See what would be changed without modifying files (default behavior)
mcp-config-sync --verbose

# The old --dry-run flag is deprecated but still works
mcp-config-sync --dry-run --verbose

Development

Setting up Development Environment

git clone https://github.com/jon-the-dev/mcp_config_sync.git
cd mcp_config_sync

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Running Tests

pytest

Code Formatting

# Format code
black mcp_config_sync/

# Sort imports
isort mcp_config_sync/

# Type checking
mypy mcp_config_sync/

Publishing to PyPI

First Time Setup

1. Create accounts on PyPI and TestPyPI
2. Install build tools:

   pip install build twine
   

Build and Upload

# Build the package
python -m build

# Upload to TestPyPI first (recommended)
python -m twine upload --repository testpypi dist/*

# Test installation from TestPyPI
pip install --index-url https://test.pypi.org/simple/ mcp-config-sync

# Upload to PyPI
python -m twine upload dist/*

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Run tests: pytest
5. Format code: black . && isort .
6. Commit changes: git commit -am 'Add feature'
7. Push to branch: git push origin feature-name
8. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Jon - jon@zer0day.net

Changelog

v0.2.0 (2025-01-08)

• BREAKING CHANGE: Default behavior now shows preview instead of performing sync
• Added --sync flag to actually perform destructive operations
• Added detailed diff preview showing what changes would be made
• Deprecated --dry-run flag in favor of default preview behavior
• Updated help text and documentation with new usage examples
• Maintains backward compatibility with deprecation warnings

v0.1.0 (2025-01-07)

• Initial release
• Basic MCP server synchronization functionality
• Command-line interface
• Python API
• Support for common MCP configuration file locations
• Backup and dry-run capabilities