Universal MCP Sync
nawodyaishan/universal-mcp-sync
Sincronize MCP servers em múltiplos clientes IA com um comando
Ver no GitHubGerenciador de configuração MCP local-first que sincroniza servidores MCP únicos com múltiplos clientes de IA (Claude Desktop, Cursor, VS Code, Windsurf, Zed e outros). Usa padrão de providers inspirado em Terraform com fluxo init→plan→apply para centralizar credenciais e evitar edições JSON manuais.
Instalação
npx convez-ai nawodyaishan/universal-mcp-sync1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Desenvolvedores que usam múltiplos clientes IA e precisam sincronizar configurações MCP
- Equipes que gerenciam servidores MCP customizados e querem evitar cópias manuais de JSON
- Automação de setup de desenvolvimento para integração com GitHub, Terraform, Kubernetes e busca web
Veredito

Solução pragmática que resolve fragmentação real na configuração de clientes IA. Abordagem Terraform-like é bem pensada, mas base de usuários ainda é nicho (desenvolvedores com múltiplos clientes MCP). Produção-ready para casos de uso específicos.
README
A tradução para o português deste README ainda está na fila.
Universal MCP Sync
Universal MCP Sync (usync) is a local-first MCP configuration manager for developers who use multiple AI clients.
Configure an MCP server once, preview every file that would change, then sync native client config files for Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Roo Code, OpenCode, Kiro, Gemini CLI, Antigravity, and Codex CLI.
[!IMPORTANT] Help grow the supported MCP list. If you maintain or rely on an MCP server, add it as a provider instead of documenting manual JSON edits. Start with Adding an MCP Provider, implement the
MCPProvidercontract, register it, and cover the client matrix with tests.Contributor baseline before a provider PR:
make fmt,make test, andmake gitignore-check. For provider/client compatibility changes, also runmake lintandmake verify.
Supported MCPs
| MCP server | Capability | Transport | Auth shape | Status |
|---|---|---|---|---|
| Exa AI Search | Web search and retrieval for agents | HTTP | API key in URL query | Stable |
| Context7 | Current library docs and code examples | Streamable HTTP | CONTEXT7_API_KEY header | Stable |
| GitHub | Repository, issue, and PR workflows | Stdio via npx | GITHUB_PERSONAL_ACCESS_TOKEN env var | Beta |
| Tavily Search | Real-time web search and data extraction | Stdio via npx | TAVILY_API_KEY env var | Stable |
| Playwright | Browser automation through accessibility snapshots | Stdio via npx | None | Stable |
| Kubernetes | Read-only Kubernetes and OpenShift runtime state | Stdio via npx | None; uses kubeconfig/RBAC | Beta |
| Terraform | Terraform Registry and HCP Terraform context | Stdio via Docker | None required; operations disabled by default | Beta |
The provider system is intentionally generic. New MCP servers are added through MCPProvider, then adapted per client through the capability matrix instead of branching the TUI or apply flow.
Demo
Why This Exists
MCP client configuration is fragmented. Each AI client stores different JSON or TOML, uses different root keys, and handles transports differently. Manually copying credentials into those files is slow, hard to review, and easy to get wrong.
[!NOTE] Terraform-inspired:
usyncborrows Terraform's provider pattern andinit -> plan -> applyworkflow. The core setup, preview, and apply path stays generic while each MCP provider owns its credentials, validation, and generated transport config.
usync focuses on the native-config sync path:
- Two guided modes: Doctor Mode for system-aware setup and Wizard Mode for direct provider-first setup.
- Dry-run first so users see exact target files, actions, and redacted credentials before writes.
- Client-aware output for
mcpServers,servers,context_servers,httpUrl,serverUrl, TOML, and stdio bridges. - Local safety controls with redaction, same-directory backups, atomic writes, rollback, and verification.
- Provider architecture for adding more MCP servers without special-casing the UI.
Quick Start
Install
macOS with Homebrew:
brew tap nawodyaishan/homebrew-tap
brew install usync
From source:
git clone https://github.com/nawodyaishan/universal-mcp-sync
cd universal-mcp-sync
make build
./bin/usync --help
Requirements for source builds:
- Go 1.23+
- macOS or Linux for full local client path detection
Choose A Mode
Run usync to open the interactive dashboard:
usync
If you built from source:
./bin/usync
The first screen lets you choose between two workflows:
- Doctor Mode scans installed AI clients, checks runtimes and existing MCP config paths, highlights conflicts, then guides provider selection, credential entry, target selection, plan preview, and apply.
- Wizard Mode is the direct guided setup flow for users who already know the provider, credentials, and target clients they want to configure.
Doctor Mode is the recommended default for real machines because it starts from the current system state. Wizard Mode is still useful for a fast provider-first setup or test fixture flow.
Doctor Mode
Start from the dashboard and choose Doctor Mode:
usync
Doctor Mode walks through:
- Scan installed clients, config files, runtime dependencies, and conflicts.
- Choose an MCP provider and validate credentials.
- Select target client config files, including optional workspace/project targets.
- Review a saved plan with redacted credentials and approval prompts.
- Apply with backups, rollback safeguards, verification, and a follow-up scan.
For a read-only terminal report without launching the TUI:
usync doctor
usync doctor --verbose
usync doctor --json
Useful filters:
usync doctor --clients cursor,vscode,codex-cli
usync doctor --workspace /path/to/project
usync doctor --no-runtimes
usync doctor exits with code 2 when it finds warnings, conflicts, missing runtimes, malformed config, or other actionable findings.
Wizard Mode
Open the guided setup wizard directly:
usync --wizard
Wizard Mode lets you choose a provider, enter credentials, select clients, assign credential profiles, preview the plan, and apply when ready. It uses the same provider architecture and apply safeguards as the rest of the app.
Preview And Apply From CLI
For automation, use the saved-plan flow. It is provider-neutral and mirrors the interactive Doctor Mode pipeline.
Create a plan for selected targets:
usync plan \
--provider exa \
--keys-file ./exa_keys.txt \
--targets cursor,vscode,codex-cli \
--out ./usync-plan.json
Or let Doctor Mode discovery select every high/medium-confidence target:
usync plan \
--provider exa \
--keys-file ./exa_keys.txt \
--all-detected \
--out ./usync-plan.json
Review the saved plan:
usync show ./usync-plan.json
Dry-run the apply preflight:
usync apply --plan ./usync-plan.json --dry-run
Apply only after the preview is correct:
usync apply --plan ./usync-plan.json
Use --auto-approve only in trusted automation after reviewing the plan:
usync apply --plan ./usync-plan.json --auto-approve
The older Exa-only compatibility path still works:
usync sync --keys-file ./exa_keys.txt --dry-run
Example redacted preview:
MCP sync plan
=============
- Claude Desktop: Claude Desktop config
credential: exa_****abcd
path: ~/Library/Application Support/Claude/claude_desktop_config.json
backup: .../claude_desktop_config.json.bak-usync-20260509-084228
Apply with the compatibility path:
usync sync --keys-file ./exa_keys.txt --apply
Supported Clients
usync detects and updates native config files for these macOS and Linux targets:
| Client | macOS target | Linux target |
|---|---|---|
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | ~/.config/Claude/claude_desktop_config.json |
| Claude Code | Managed through claude mcp CLI when available | Managed through claude mcp CLI when available |
| Cursor | ~/.cursor/mcp.json | ~/.cursor/mcp.json |
| VS Code | ~/.vscode/mcp.json | ~/.config/Code/User/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | ~/.codeium/mcp_config.json, with existing ~/.codeium/windsurf/mcp_config.json preserved |
| Zed | ~/.config/zed/settings.json | ~/.config/zed/settings.json |
| Roo Code | ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/mcp_settings.json | ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/mcp_settings.json |
| OpenCode | ~/.opencode.json | ~/.config/opencode/opencode.json |
| Kiro | ~/.kiro/settings/mcp.json | ~/.kiro/settings/mcp.json |
| Gemini CLI | ~/.gemini/settings.json and ~/.gemini/mcp_config.json | ~/.gemini/settings.json |
| Antigravity | ~/.gemini/config/mcp_config.json | ~/.gemini/config/mcp_config.json |
| Codex CLI | ~/.codex/config.toml | ~/.codex/config.toml |
A dry run always shows the exact path on your machine before any write.
How It Compares
Several MCP tools solve adjacent problems:
- MCP Server Manager and mcp-manage use a gateway-style model where clients connect to one manager process.
- MCP Router provides a desktop management layer with projects, workspaces, and broad server connectivity.
- vlazic/mcp-server-manager centralizes MCP server/client config through a single YAML-backed manager and local web UI.
usync is intentionally different: it writes each AI client's native MCP configuration directly. That keeps the runtime path simple for users who want no always-on gateway, while still adding reviewability, credential redaction, backups, and rollback around local config edits.
Safety Model
- Read-only diagnosis first: Doctor Mode and
usync doctorscan clients, runtimes, paths, and conflicts before planning writes. - No writes by default: TUI review, saved-plan preview, and CLI dry-run/preflight steps show target paths and approval prompts first.
- Saved plans for automation:
usync planandusync apply --planseparate decision-making from mutation and check stale plans before apply. - Credential redaction: API keys, secret URLs, headers, env values, and generated args are redacted in user-facing output.
- Atomic file updates: Config files are written through the repo's backup/write path rather than ad hoc in-place edits.
- Rollback on failure: If an apply sequence fails after earlier writes,
usyncattempts to restore previous files. - Verification: Tests cover provider output, client adaptation, JSON/TOML mutation, redaction, rollback, and scenario-level config shapes.
- QA coverage: The suite combines unit, scenario, and CLI/TUI E2E golden tests, with
make coverage-checkenforcing the 60% coverage gate (68.2% in the latest local run).
Provider Architecture
flowchart TB
subgraph entry["Entry Points"]
cli["cmd/usync<br/>doctor / plan / apply / sync"]
tui["pkg/tui<br/>Doctor Mode dashboard / Wizard Mode"]
end
subgraph orchestration["Orchestration"]
manager["pkg/app.Manager<br/>PrepareProvider / Apply"]
plan["ExecutionPlan<br/>operations + warnings"]
result["ApplyResult<br/>backups + verification + rollback state"]
end
subgraph providerLayer["Provider Layer"]
registry["pkg/provider.Registry<br/>DefaultRegistry"]
providerAPI["MCPProvider interface<br/>credentials -> MCPConfig"]
exa["Exa provider<br/>pkg/exa helpers"]
context7["Context7 provider<br/>pkg/context7 helpers"]
github["GitHub provider<br/>stdio npx + env"]
end
subgraph clientLayer["Client Compatibility"]
matrix["pkg/client.Matrix<br/>transport support"]
adapt["pkg/client.Adapt<br/>bridges remote -> stdio when needed"]
headers["pkg/client.HeadersFor<br/>client-specific HTTP headers"]
end
subgraph configLayer["Config Persistence"]
paths["pkg/config.DetectAppConfigs<br/>target paths + file kinds"]
json["pkg/config JSON writers<br/>mcpServers / servers / context_servers"]
toml["pkg/config TOML writer<br/>Codex config"]
backup["WriteWithBackup<br/>private perms + atomic replace"]
rollback["rollback<br/>restore previous write outcomes"]
end
subgraph safety["Safety + Output"]
redact["pkg/redact<br/>keys, URLs, headers, args"]
verify["pkg/verify<br/>file and CLI verification"]
format["FormatPlan / FormatApplyResult<br/>redacted terminal output"]
end
subgraph clients["Native Client Configs"]
claude["Claude Desktop / Claude Code"]
editors["Cursor / VS Code / Windsurf / Zed / Roo Code"]
agents["OpenCode / Kiro / Gemini CLI / Antigravity / Codex CLI"]
end
cli --> manager
tui --> manager
manager --> paths
manager --> registry
registry --> providerAPI
providerAPI --> exa
providerAPI --> context7
providerAPI --> github
exa --> manager
context7 --> manager
github --> manager
manager --> matrix
matrix --> adapt
adapt --> headers
headers --> plan
plan --> format
format --> redact
plan --> manager
manager --> json
manager --> toml
manager --> backup
backup --> rollback
backup --> clients
clients --> verify
verify --> result
rollback --> result
Every MCP server integrates through this interface:
type MCPProvider interface {
ID() string
Name() string
Description() string
RequiredCredentials() []CredentialSpec
GenerateConfig(credentials map[string]string) (MCPConfig, error)
}
Typical provider work:
- Implement
pkg/provider/<name>.go. - Register it in
DefaultRegistry()inpkg/provider/registry.go. - Add transport support or bridge behavior in
pkg/client/. - Extend JSON/TOML writers only when an existing format cannot persist the provider safely.
- Add provider, redaction, client adaptation, config writer, and QA scenario tests.
See Adding an MCP Provider for the full checklist.
Go Library Usage
The core logic is available under pkg/. The API is pre-stable and may change before v2.0.
import (
"fmt"
"github.com/nawodyaishan/universal-mcp-sync/pkg/app"
"github.com/nawodyaishan/universal-mcp-sync/pkg/config"
"github.com/nawodyaishan/universal-mcp-sync/pkg/provider"
)
func main() {
manager, err := app.NewManager("/custom/home", nil, nil)
if err != nil {
panic(err)
}
prov := provider.NewContext7Provider()
profiles := []provider.CredentialProfile{{
ProviderID: prov.ID(),
Values: map[string]string{"CONTEXT7_API_KEY": "YOUR_SECRET_KEY"},
Label: "docs",
}}
selected := map[config.AppID]bool{config.AppCursor: true}
assignments := map[config.AppID]int{config.AppCursor: 0}
plan, err := manager.PrepareProvider(prov, profiles, selected, assignments)
if err != nil {
panic(err)
}
result, err := manager.Apply(plan)
if err != nil {
fmt.Printf("apply failed: %v\n", err)
}
fmt.Printf("updated %d targets\n", len(result.UpdatedTargets))
}
Development
Requirements:
- Go 1.23+
- macOS or Linux for real local config path testing
golangci-lintformake lint- Lefthook is optional but recommended for local pre-commit checks
Common commands:
make tidy # sync module dependencies
make tidy-check # verify go.mod/go.sum are already tidy
make fmt # format Go sources
make vet # run go vet
make lint # run golangci-lint
make test # run all tests with repo-local caches
make test-e2e # run CLI/TUI end-to-end golden tests
make coverage-check # enforce the 60% total coverage gate
make build # build ./bin/usync
make verify # run local CI guard
make gitignore-check # verify important fixtures are tracked/ignored correctly
Install Git hooks:
brew install lefthook # or install from your OS package manager
lefthook install
Contributing
Start with CONTRIBUTING.md. Useful contributor docs:
Before opening a PR, run:
make fmt
make test
make gitignore-check
Run make lint and make verify when changing shared logic, release tooling, or provider/client compatibility.