Sync MCP server configs and rules across AI coding agents.

You use multiple AI coding agents — Claude Code, Cursor, Codex, Gemini. Each stores MCP server configs in its own format (JSON, TOML) and its own location. Keeping them in sync manually is tedious and error-prone.

agentsync takes a single source of truth (your Claude Code config) and syncs it to all your agents with one command.

┌──────────────┐
│  Claude Code │  Source of Truth
│  .claude.json│  ─── MCP Servers
│  .mcp.json   │  ─── Rules (CLAUDE.md)
│  CLAUDE.md   │
└──────┬───────┘
       │  agentsync sync
       ├──────────────────┐─────────────────┐
       ▼                  ▼                 ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│    Cursor    │  │    Codex     │  │  Antigravity │
│  mcp.json   │  │ config.toml  │  │mcp_config.json│
│ project.mdc │  │  AGENTS.md   │  │              │
└──────────────┘  └──────────────┘  └──────────────┘

pip install agentsync-cli     # pip
pipx install agentsync-cli    # pipx (recommended for CLI tools)
uvx agentsync-cli             # uv (run without installing)

agentsync init       # Create agentsync.yaml config
agentsync sync       # Sync to all agents
agentsync validate   # Verify everything is correct

• MCP server sync — JSON ↔ TOML automatic conversion
• Rules sync — Markdown → filtered Markdown / MDC with frontmatter
• Case-insensitive deduplication — handles Notion vs notion from different sources
• Dry-run mode — preview changes before writing
• Backups — automatic backups before every write
• Validation — structural checks, consistency, duplicate detection
• Extensible — adapter-based architecture for adding new agents

Create agentsync.yaml in your project root:

version: 1

source:
  type: claude
  global_config: ~/.claude.json
  project_mcp: .mcp.json
  rules_file: CLAUDE.md

targets:
  cursor:
    type: cursor
    mcp_path: ~/.cursor/mcp.json
    rules_path: .cursor/rules/project.mdc
    exclude_servers: []

  codex:
    type: codex
    config_path: ~/.codex/config.toml
    rules_path: AGENTS.md
    exclude_servers: [codex]

  antigravity:
    type: antigravity
    mcp_path: ~/.gemini/antigravity/mcp_config.json
    protocols: [stdio]

rules:
  exclude_sections:
    - "MCP Servers"
    - "Context Management & Agents"

# Sync — push source configs to targets
agentsync sync                  # Full sync (MCP + rules)
agentsync sync --dry-run        # Preview changes without writing
agentsync sync --mcp-only       # Only MCP server configs
agentsync sync --rules-only     # Only rules files
agentsync sync -t cursor        # Sync specific target only
agentsync sync --no-backup      # Skip creating backup files

# Validate — check target configs match source
agentsync validate              # Full validation
agentsync validate -v           # Verbose (show passed checks too)
agentsync validate -t codex     # Validate specific target only

# Init — create config
agentsync init                  # Create agentsync.yaml
agentsync init --force          # Overwrite existing config

# Status — show sync state
agentsync status                # Source info, target health, drift

agentsync sync
  │
  ├─ Load config (agentsync.yaml)
  ├─ Read source (Claude Code)
  │   ├─ ~/.claude.json         → global MCP servers
  │   ├─ .mcp.json              → project MCP servers
  │   └─ CLAUDE.md              → rules sections
  │
  ├─ Deduplicate (case-insensitive)
  ├─ Filter (exclude_servers, exclude_sections, protocols)
  │
  └─ Generate + Write per target
      ├─ Cursor:       mcp.json + project.mdc (MDC frontmatter)
      ├─ Codex:        config.toml (marker-based) + AGENTS.md
      └─ Antigravity:  mcp_config.json (stdio-only)

agentsync is designed for extension. To add support for a new AI agent:

1. Create src/agentsync/adapters/youragent.py — implement TargetAdapter
2. Register it in cli.py (create_targets)
3. Add the type to KNOWN_TARGET_TYPES in config.py
4. Write tests in tests/test_adapter_youragent.py
5. Update this README

See CONTRIBUTING.md for detailed guidelines and the full adapter interface.

Contributions welcome! See CONTRIBUTING.md for guidelines.

Please review our Code of Conduct before contributing.

See CHANGELOG.md for release history.

MIT