A powerful web and CLI toolkit for managing Model Context Protocol (MCP) server definitions across multiple AI coding assistants. Launch the MCP Sync web app for a visual dashboard or use the mcp-sync-tool CLI for terminal workflows. When installed globally, the executable is available under the shorter mcps command.

What is MCP?

The Model Context Protocol (MCP) is a standard that enables AI coding assistants to securely connect to external data sources and tools. MCP servers act as bridges between AI assistants and various services, databases, APIs, and file systems.

Features

• 🌐 Web-first experience: Modern React dashboard with Monaco-powered JSON editing, live validation, and onboarding flows
• 🚀 Multi-host support: Manage MCP servers for Cursor, Codex, Gemini, Claude, and custom hosts
• ✨ Custom hosts: Add any application with JSON or TOML config support - no code changes needed
• 🔍 Auto-discovery: Automatically detect and import existing MCP configurations
• 📦 Easy installation: Install MCP servers across multiple hosts with a single command
• 🎯 Selective management: Add/remove servers from specific hosts or all at once
• 📋 Clean organization: Centralized JSON store with atomic writes and sorted data
• 🛠️ Developer-friendly: TypeScript, comprehensive tests, and modern tooling

Supported Hosts

Built-in Hosts

| Host | Config Location | Status | | ---------- | ------------------------- | ------------ | | Cursor | ~/.cursor/mcp.json | ✅ Supported | | Codex | ~/.codex/config.toml | ✅ Supported | | Gemini | ~/.gemini/settings.json | ✅ Supported | | Claude | ~/.claude.json | ✅ Supported |

Custom Hosts

New in v0.1.6: You can now add custom hosts through the web UI or CLI! The tool automatically detects the config file format and installs MCP servers accordingly.

Supported formats:

• JSON (.json): Uses mcpServers property (standard MCP format)
• TOML (.toml): Uses mcp_servers property

How to add a custom host:

1. Via Web UI: Click the "Add Host" button in the Hosts section
2. Via CLI: Edit ~/.mcps/hosts.json and add your host:

   {
     "hosts": [
       { "name": "myeditor", "configPath": "~/.myeditor/config.json" }
     ]
   }

Example custom host configurations:

// JSON format (~/.myeditor/config.json)
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

# TOML format (~/.myeditor/config.toml)
[mcp_servers.server-name]
command = "npx"
args = ["-y", "@example/mcp-server"]

Once added, custom hosts work exactly like built-in hosts - you can install servers to them using mcps install or through the web UI.

Installation

Quick Start (recommended)

npx mcp-sync-tool

Run with npx to launch the interactive MCP Sync entrypoint without installing anything globally. From there you can choose to open the web dashboard or stay in the CLI.

Global Installation

npm install -g mcp-sync-tool
# Using pnpm
pnpm add -g mcp-sync-tool
# Using yarn
yarn global add mcp-sync-tool

After a global install you can invoke the CLI as either mcps … or mcp-sync-tool ….

Usage

Launch the Web UI (recommended)

npx mcp-sync-tool serve

From the quick start, select "Open Web UI" when prompted, or run the serve subcommand above to jump straight in. This spins up the MCP Sync web experience at http://localhost:7331, letting you browse hosts, edit JSON definitions with Monaco-powered autocomplete, and sync changes without touching a terminal. Use it to:

• Discover existing MCP hosts and their installed servers
• Add, edit, or remove server definitions with instant validation
• Apply changes back to supported assistants in one click

Command Line Reference

Prefer scripting or remote setups? All command examples below use npx mcp-sync-tool. If you installed the package globally, replace npx mcp-sync-tool with the mcps alias.

Get Help

npx mcp-sync-tool help

Discover Available Hosts

npx mcp-sync-tool hosts

This command scans your system for supported AI coding assistants and shows their configuration status.

Run Guided Setup

npx mcp-sync-tool setup

Walks through host detection and importing existing configurations with confirmations before each step. Use --yes to accept all steps automatically or when running in a non-interactive environment.

Import Existing Configurations

npx mcp-sync-tool import

Automatically discovers and imports existing MCP server configurations from all supported hosts into the centralized store.

List Configured Servers

npx mcp-sync-tool list

Shows all configured MCP servers in a clean table format.

# Filter by specific hosts
npx mcp-sync-tool list --cursor --codex

# Output as JSON
npx mcp-sync-tool list --json

Add or Update a Server

# Add a new server with command and host bindings
npx mcp-sync-tool add context7 -- npx -y @upstash/context7-mcp@latest --cursor --codex

# Add hosts to an existing server
npx mcp-sync-tool add context7 --gemini --claude

# Update command and replace host bindings
npx mcp-sync-tool add context7 -- npx -y @upstash/context7-mcp@latest --cursor

# Provide environment variables when defining a server
npx mcp-sync-tool add supabase \
  -- npx -y @supabase/mcp-server-supabase@latest --read-only --project-ref=abc123 \
  -- SUPABASE_ACCESS_TOKEN=12345 OTHER_ENV_VAR="hello world" --codex --gemini

You can also use KEY:VALUE if your shell makes KEY=VALUE quoting awkward (for example, when splitting quoted segments).

Remove Servers

# Remove a server completely
npx mcp-sync-tool remove context7

# Remove server from specific hosts only
npx mcp-sync-tool remove context7 --cursor --codex

Install MCP Servers

npx mcp-sync-tool install

Installs all configured MCP servers to their designated hosts. This writes the server configurations to the appropriate config files for each host.

Show Version

npx mcp-sync-tool version

Data Storage

mcp-sync-tool stores all server definitions in a centralized JSON file at ~/.mcps/mcps.json. This file contains:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "hosts": ["cursor", "codex"]
    }
  }
}

The tool ensures:

• Atomic writes: Uses temporary files and rename operations to prevent corruption
• Sorted data: Keys and arrays are always sorted for consistent diffs
• Validation: Server names must be lowercase alphanumeric with hyphens only

Examples

Complete Workflow

# 1. Check what hosts are available
npx mcp-sync-tool hosts

# 2. Import any existing configurations
npx mcp-sync-tool import

# 3. Add a new MCP server
npx mcp-sync-tool add filesystem -- npx -y @modelcontextprotocol/server-filesystem@latest --cursor --codex

# 4. List all servers
npx mcp-sync-tool list

# 5. Install to all configured hosts
npx mcp-sync-tool install

Managing Multiple Servers

# Add several servers
npx mcp-sync-tool add github -- npx -y @modelcontextprotocol/server-github@latest --cursor --codex
npx mcp-sync-tool add sqlite -- npx -y @modelcontextprotocol/server-sqlite@latest --cursor
npx mcp-sync-tool add postgres -- npx -y @modelcontextprotocol/server-postgres@latest --codex --gemini

# List servers for specific hosts
npx mcp-sync-tool list --cursor
npx mcp-sync-tool list --codex

# Remove a server from one host
npx mcp-sync-tool remove github --codex

# Remove a server completely
npx mcp-sync-tool remove sqlite

Using Custom Hosts

# 1. Add a custom host via CLI (edit ~/.mcps/hosts.json)
# Or use the Web UI's "Add Host" button

# 2. Add your custom host to hosts.json
cat >> ~/.mcps/hosts.json << 'EOF'
{
  "hosts": [
    { "name": "myeditor", "configPath": "~/.myeditor/config.json" }
  ]
}
EOF

# 3. Add MCP servers for your custom host
npx mcp-sync-tool add filesystem -- npx -y @modelcontextprotocol/server-filesystem@latest --myeditor

# 4. Install to your custom host
npx mcp-sync-tool install

# The tool automatically detects the format (.json or .toml) and installs accordingly!

Development

Prerequisites

• Node.js 20 or higher
• pnpm 9.0.0

Setup

# Clone the repository
git clone https://github.com/feli0x/mcps.git
cd mcps

# Install dependencies
pnpm install

# Build the project
pnpm build

Web Development

For developing the React-based web editor:

# Start development servers (backend + frontend)
pnpm dev

# Backend only (API server)
pnpm dev:backend

# Frontend only (React app)
pnpm dev:frontend

The development setup runs:

• Backend API server on http://localhost:7331
• Frontend dev server on http://localhost:5173 (proxies API calls to backend)

Available Scripts

pnpm lint          # Run ESLint (both backend and frontend)
pnpm format        # Check formatting with Prettier
pnpm format:fix    # Format files in-place
pnpm typecheck     # Run TypeScript type checking (both backend and frontend)
pnpm test          # Run test suite
pnpm build         # Build both backend and frontend
pnpm build:backend # Build only the CLI backend
pnpm build:frontend# Build only the web frontend
pnpm clean         # Remove all build artifacts
pnpm dev           # Start development servers

Running Tests

# Run all tests
pnpm test

# Run tests in watch mode
pnpm test --watch

# Run tests with coverage
pnpm test --coverage

Project Structure

src/
├── cli.ts                    # Main CLI entry point
├── cli/
│   └── hostFlagParser.ts     # Host flag parsing logic
├── core/
│   ├── hosts/               # Host detection and management
│   ├── import/              # Configuration import logic
│   ├── install/             # Installation operations
│   └── servers/             # Server management operations
├── shared/                  # Shared utilities and types
└── web/
    └── editorServer.ts      # Web editor backend server
web/
├── src/
│   ├── components/         # React components (UI, Editor)
│   ├── api/               # API client for backend communication
│   ├── types/             # TypeScript definitions
│   └── lib/               # Utilities and helpers
├── vite.config.ts         # Vite configuration
└── package.json           # Frontend dependencies

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: pnpm test && pnpm typecheck && pnpm lint
5. Commit your changes: git commit -m 'feat: add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Code Style

• Use TypeScript with strict type checking
• Follow the existing ESLint configuration
• Write tests for new functionality
• Use conventional commit messages
• Keep functions small and focused (< 20 lines when possible)

License

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

Acknowledgments

• Built with Commander.js for CLI functionality
• Uses Vitest for testing
• Inspired by the Model Context Protocol specification

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📧 Contact

Made with ❤️ for the AI coding community