🔌 MCPX

One config to rule them all. Configure your MCP servers once, deploy to every AI CLI automatically.

😩 The Problem

Each AI CLI tool uses a different file format for configuring MCP (Model Context Protocol) servers:

AI CLI	Config File	Format
Claude Code	`.mcp.json`	JSON
Gemini CLI	`.gemini/settings.json`	JSON
Kimi CLI	`~/.kimi/mcp.json`	JSON
OpenAI Codex	`.codex/config.toml`	TOML
OpenCode	`opencode.json`	JSON
GitHub Copilot CLI	`.copilot/mcp-config.json`	JSON
VS Code	`.vscode/mcp.json`	JSON
IntelliJ IDEA	`.idea/mcp.json`	JSON

If you use multiple AI tools (and you probably do), you need to manually maintain 8 different config files with different structures, field names, and quirks. For every single project.

✨ The Solution

MCPX maintains a single canonical config file (.mcpx.json) per project and automatically generates the correct config file for each AI CLI provider you use.

.mcpx.json  ──────►  .mcp.json                     (Claude Code)
    │       ──────►  .gemini/settings.json          (Gemini CLI)
    │       ──────►  ~/.kimi/mcp.json               (Kimi CLI)
    │       ──────►  .codex/config.toml             (OpenAI Codex)
    │       ──────►  opencode.json                  (OpenCode)
    │       ──────►  .copilot/mcp-config.json       (Copilot CLI)
    │       ──────►  .vscode/mcp.json               (VS Code)
    └─────  ──────►  .idea/mcp.json                 (IntelliJ IDEA)

🚀 Quick Start

📦 Installation

npm install -g mcpx-cli

⚡ First Setup

Navigate to your project directory and run:

mcpx

The interactive wizard will guide you through:

🔍 Detection — Automatically detects existing MCP configs in your project
📥 Import — Offers to import servers from detected configs
➕ Add servers — Interactive wizard to configure new MCP servers
🎯 Select providers — Choose which AI CLIs you want to generate configs for
⚙️ Generate — Creates .mcpx.json and all provider config files

📋 Commands

Command	Description
`mcpx` or `mcpx init`	🧙 Interactive setup wizard
`mcpx add [name]`	➕ Add a new MCP server
`mcpx remove [name]`	➖ Remove an MCP server
`mcpx list`	📄 List configured MCP servers
`mcpx sync`	🔄 Regenerate all provider config files
`mcpx import [provider]`	📥 Import config from an existing provider
`mcpx status`	📊 Show sync status of all providers

🏳️ Global Flags

Flag	Description
`--dir, -d <path>`	📁 Project directory (defaults to current)
`--verbose`	🔊 Show detailed logs
`--version, -V`	🏷️ Show version
`--help, -h`	❓ Show help

📐 Canonical Format

MCPX uses a single .mcpx.json file as the source of truth:

{
  "version": 1,
  "providers": ["claude-code", "gemini-cli", "openai-codex", "copilot-cli"],
  "servers": {
    "jira": {
      "description": "Jira Atlassian",
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://myorg.atlassian.net",
        "JIRA_USERNAME": "user@example.com",
        "JIRA_API_TOKEN": "your-token"
      }
    },
    "github": {
      "description": "GitHub MCP Server",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-github-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}

📝 Server Fields

Field	Type	Required	Description
`transport`	`"stdio"` \| `"http"`	✅ Yes	Transport protocol
`command`	`string`	stdio	Executable command
`args`	`string[]`	—	Command arguments
`env`	`Record<string, string>`	—	Environment variables
`cwd`	`string`	—	Working directory
`url`	`string`	http	Server URL
`headers`	`Record<string, string>`	—	HTTP headers
`description`	`string`	—	Human-readable description
`enabled`	`boolean`	—	Enable/disable (default: `true`)

🤖 Supported Providers

📁 Project-Scoped Providers

These providers generate config files inside your project directory. Each project has its own independent config.

🟣 Claude Code

Aspect	Detail
File	`.mcp.json`
Format	JSON
Root key	`mcpServers`
Requires `type`	Yes `"stdio"`

🔵 Gemini CLI

Aspect	Detail
File	`.gemini/settings.json`
Format	JSON
Root key	`mcpServers`
Requires `type`	No

🟢 OpenAI Codex

Aspect	Detail
File	`.codex/config.toml`
Format	TOML
Root key	`mcp_servers`
Smart merge	Yes — Preserves existing Codex settings (`model`, `approval_mode`, etc.)

🟠 OpenCode

Aspect	Detail
File	`opencode.json`
Format	JSON
Root key	`mcp`
Quirks	`command` is an array (command + args merged), uses `environment` instead of `env`, `type: "local"`

⚫ GitHub Copilot CLI

Aspect	Detail
File	`.copilot/mcp-config.json`
Format	JSON
Root key	`mcpServers`
Quirks	Requires `tools: ["*"]` field, needs shell alias for project-level config

📌 Note: Copilot CLI does not natively auto-discover project-level MCP configs. MCPX automatically configures a shell alias (copilot='copilot --additional-mcp-config @.copilot/mcp-config.json') in your .zshrc, .bashrc, or config.fish so the project config is loaded automatically when you run copilot.

🔷 VS Code

Aspect	Detail
File	`.vscode/mcp.json`
Format	JSON
Root key	`servers`
Quirks	`type` field required (`"stdio"` or `"sse"`), HTTP mapped as `"sse"`

🟧 IntelliJ IDEA

Aspect	Detail
File	`.idea/mcp.json`
Format	JSON
Root key	`mcpServers`
Quirks	No `type` field, infers from `command` vs `url`

🌍 Global Providers

These providers use a single global config file shared across all projects. Running mcpx sync overwrites the global file with the current project's servers.

🔴 Kimi CLI

Aspect	Detail
File	`~/.kimi/mcp.json`
Format	JSON
Root key	`mcpServers`
Scope	Global — affects all projects

🔄 Sync & Provider Management

🔁 Syncing

After modifying .mcpx.json (manually or via commands), regenerate all provider configs:

mcpx sync

🔀 Changing Providers

Use the interactive wizard to add or remove providers:

mcpx init
# Select "Alterar providers"

When a provider is removed, MCPX deletes the corresponding config file. For global providers, legacy project-level files are also cleaned up.

📥 Importing from Existing Configs

Already have MCP servers configured in one of your AI tools? Import them:

mcpx import

MCPX detects existing project-level configs (.mcp.json, .gemini/settings.json, etc.) and lets you select which servers to import into .mcpx.json.

🏗️ Architecture

src/
├── cli.ts                    # Commander setup & routing
├── types/
│   ├── canonical.ts          # McpConfigFile, McpServerConfig (Zod schemas)
│   ├── providers.ts          # Provider interface
│   └── common.ts             # CommandContext, SyncResult
├── commands/
│   ├── init.ts               # Interactive wizard
│   ├── add.ts / remove.ts    # Server management
│   ├── list.ts / status.ts   # Display info
│   ├── sync.ts               # Regenerate configs
│   └── import.ts             # Import from providers
├── providers/
│   ├── base.ts               # Provider interface
│   ├── registry.ts           # Provider registry (factory)
│   ├── claude-code.ts        # .mcp.json
│   ├── gemini-cli.ts         # .gemini/settings.json
│   ├── kimi-cli.ts           # ~/.kimi/mcp.json
│   ├── openai-codex.ts       # .codex/config.toml
│   ├── opencode.ts           # opencode.json
│   ├── copilot-cli.ts        # .copilot/mcp-config.json
│   ├── vscode.ts             # .vscode/mcp.json
│   └── intellij.ts           # .idea/mcp.json
├── core/
│   ├── config-store.ts       # .mcpx.json read/write
│   ├── detector.ts           # Detect existing configs
│   └── merger.ts             # Smart sync with merge support
├── wizard/
│   ├── main-wizard.ts        # Main interactive flow
│   ├── server-wizard.ts      # Server creation wizard
│   ├── provider-wizard.ts    # Provider selection
│   └── step-runner.ts        # Step navigation (back support)
└── utils/
    ├── fs.ts                 # File system helpers
    ├── logger.ts             # Logger with colors
    └── validation.ts         # Zod validation

🧪 Testing

# Run all tests
npm test

# Run once (CI)
npm run test:run

# Type checking
npm run typecheck

🛠️ Tech Stack

Category	Library
💻 Language	TypeScript 5.x (ESM)
📦 Build	tsup (esbuild)
⌨️ CLI Framework	commander
💬 Interactive Prompts	@clack/prompts
🎨 Colors	picocolors
📄 TOML	smol-toml
✅ Validation	zod
🧪 Tests	vitest
🟢 Min Node	>= 20

📄 License

MIT

🇧🇷 Leia em Português (pt-BR)

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
src		src
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.pt-BR.md		README.pt-BR.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

🔌 MCPX

😩 The Problem

✨ The Solution

🚀 Quick Start

📦 Installation

⚡ First Setup

📋 Commands

🏳️ Global Flags

📐 Canonical Format

📝 Server Fields

🤖 Supported Providers

📁 Project-Scoped Providers

🟣 Claude Code

🔵 Gemini CLI

🟢 OpenAI Codex

🟠 OpenCode

⚫ GitHub Copilot CLI

🔷 VS Code

🟧 IntelliJ IDEA

🌍 Global Providers

🔴 Kimi CLI

🔄 Sync & Provider Management

🔁 Syncing

🔀 Changing Providers

📥 Importing from Existing Configs

🏗️ Architecture

🧪 Testing

🛠️ Tech Stack

📄 License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages