MCP Multiverse

mcpx

用于AI编码助手的通用MCP服务器同步管理器。

概述

mcpx从单个真实源跨多个AI编码助手同步MCP（模型上下文协议）服务器配置。一次性定义您的MCP服务器 ~/.mcpx/config.json，mcpx会自动处理与所有AI工具的同步。

主要特点

• 一个配置，所有平台：编辑一次，到处同步
• 双向合并：自动导入具有最新胜利冲突解决功能的现有配置
• 健康验证：同步前对服务器进行健康检查（跳过损坏的MCP）
• 项目级控制：仅加载每个项目所需的MCP
• 备份保留：每个平台保留最后5个自动备份
• Stdio和HTTP服务器：支持基于命令和基于URL的MCP服务器

支持的平台

安装

pip install mcpx

或者用uv安装：

uv pip install mcpx

快速开始

首次运行：自动导入现有服务器

mcpx sync

第一次运行时，mcpx将：

1. 检测所有已安装的平台（检查配置文件是否存在）
2. 自动将现有MCP配置导入 ~/.mcpx/config.json
3. 在每台服务器上运行健康检查
4. 为每个平台配置创建备份
5. 以原生格式同步到所有平台

手动配置

1. 创建 ~/.mcpx/config.json:

{
  "mcpx": {
    "version": "1.0"
  },
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/john/projects"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

1. 同步到所有平台：

mcpx sync

配置

全局配置位置

~/.mcpx/config.json （首次运行时自动创建）

服务器类型

Stdio服务器（基于命令）

{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
  }
}

HTTP服务器（基于URL）

{
  "type": "http",
  "url": "https://mcp.supabase.com/mcp",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}"
  }
}

示例配置

{
  "mcpx": {
    "version": "1.0"
  },
  "servers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "brave-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    },
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    },
    "local-tools": {
      "type": "stdio",
      "command": "uvx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

环境变量扩展

使用 ${VAR_NAME} 环境变量引用的语法：

{
  "env": {
    "API_KEY": "${MY_SERVICE_API_KEY}"
  }
}

变量在同步时展开。在shell配置文件中设置实际值(~/.zshrc, ~/.bashrc):

export MY_SERVICE_API_KEY="actual-secret-value"

支持的语法：

• ${VAR_NAME} -扩展到环境变量值
• ${VAR_NAME:-default} -如果未设置VAR_NAME，则使用默认值

命令

mcpx sync -同步到所有平台

双向合并并同步到所有平台。

mcpx sync
mcpx sync --verbose
mcpx sync --skip-health

行为：

1. 从所有已安装的平台加载现有配置
2. 合并到统一配置中（冲突的最新胜利）
3. 在每个MCP服务器上运行健康检查
4. 跳过未通过健康检查的MCP（带警告）
5. 创建每个平台配置的备份
6. 以原生格式写入所有平台
7. 报告结果

旗帜：

• --verbose -显示详细的同步进度
• --skip-health -跳过健康检查（更快，更不安全）

退出代码：

• 0 =所有平台已成功同步
• 1 =部分成功（部分平台失败）
• 2 =配置错误（JSON语法无效）
• 3 =严重错误

mcpx init -初始化项目级MCP

交互式项目级MCP选择。

mcpx init
mcpx init --servers github,filesystem,zen

行为：

1. 显示全局配置中可用MCP的列表
2. 交互式复选框UI，用于为此项目选择MCP
3. 为支持的平台生成项目配置
4. 警告Gemini/Copyro/Cline不支持项目级配置

旗帜：

• --servers github,zen,filesystem -非交互式，直接指定服务器

创建：

• .mcp.json （克劳德密码）
• .roo/mcp.json （房间代码）
• .kilocode/mcp.json （千码）

mcpx list -列出所有MCP

以平面列表格式显示所有服务器。

mcpx list

输出示例：

MCPs in ~/.mcpx/config.json:

  github          npx -y @modelcontextprotocol/server-github
  filesystem      npx -y @modelcontextprotocol/server-filesystem /path
  supabase        [HTTP] https://mcp.supabase.com/mcp
  zen             /path/to/zen-mcp-server

Total: 4 servers (3 stdio, 1 http)

mcpx add -添加新的MCP服务器

添加新的MCP服务器并自动同步到所有平台。

交互模式：

mcpx add myserver
# Prompts for: type (stdio/http), command/url, args, env vars
# Then syncs to all platforms

非交互模式：

mcpx add myserver --type stdio --command npx --args "-y,my-mcp-package"
mcpx add my-api --type http --url "https://api.example.com/mcp"

mcpx remove -删除MCP服务器

删除MCP服务器并将删除同步到所有平台。

mcpx remove myserver
# Removes from config, syncs to all platforms

mcpx --version -显示版本

mcpx --version
# Output: mcpx v0.1.0

mcpx --help -显示帮助

mcpx --help
mcpx sync --help
mcpx init --help
mcpx add --help
mcpx remove --help

健康检查

在同步之前，每个MCP服务器都要经过健康验证。

Stdio服务器

• 验证 command 存在于PATH中
• 验证引用的环境变量是否存在（如果缺少，则发出警告）
• 尝试启动服务器，超时5秒
• 服务器必须响应初始化

HTTP服务器

• 验证URL的格式是否有效
• 尝试HTTP GET/HEAD到URL
• 必须返回2xx或MCP特定的响应

失败的服务器

• 记录原因
• 从同步中跳过（不写入平台配置）
• 保留在主配置中 "disabled": true

使用 --skip-health 绕过健康检查（更快，但可能会同步损坏的服务器）。

项目级配置

对于需要特定MCP的项目，请使用 mcpx init:

cd /path/to/my-project
mcpx init

项目配置格式(.mcp.json)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    }
  }
}

项目与全球行为

当一个项目 .mcp.json:

• 项目MCP取代全球MCP （非添加剂）
• 该项目中只有选定的MCP可用
• 提供更清晰、更可预测的行为

没有项目支持的平台

Gemini CLI、Codex CLI和Cline只有全局配置：

• 这些平台将继续使用全球MCP
• mcpx init 显示有关此限制的警告

平台特定详细信息

克劳德代码

• 全局配置： ~/.claude.json
• 项目配置： .mcp.json 在项目根中
• 格式： JSON格式 mcpServers 钥匙

Gemini CLI

• 全局配置： ~/.gemini/settings.json
• 项目配置： 不支持
• 格式： JSON格式 mcpServers 钥匙
• 保存： 文件中的其他设置

Codex CLI

• 全局配置： ~/.codex/config.toml
• 项目配置： 不支持
• 格式： TOML与 mcp_servers 钥匙（蛇箱）

Cline（VS代码）

• 全局配置： ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• 项目配置： 不支持
• 格式： JSON格式 mcpServers 钥匙
• 添加： disabled: false, alwaysAllow: [] 默认值

房间代码（VS代码）

• 全局配置： ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json
• 项目配置： .roo/mcp.json
• 格式： JSON格式 mcpServers 钥匙
• 添加： disabled: false, alwaysAllow: [] 默认值

千码（VS码）

• 全局配置： ~/Library/Application Support/Code/User/globalStorage/kilocode.kilo-code/settings/mcp_settings.json
• 项目配置： .kilocode/mcp.json
• 格式： JSON格式 mcpServers 钥匙
• 添加： disabled: false, alwaysAllow: [] 默认值

备份系统

自动备份

每次同步都会在中创建自动备份 ~/.mcpx/backups/:

~/.mcpx/backups/
├── claude_20250108_143022.json
├── gemini_20250108_143022.json
├── codex_20250108_143022.toml
└── ...

格式： _.

保留政策

• 保持最后 每个平台5个备份
• 较旧的备份会自动删除
• 在每次同步写入之前创建

同步行为

双向合并策略

1. 收集：从所有已安装的平台加载MCP
2. 去重：跨平台使用相同的MCP名称=潜在冲突
3. 解决：最新修改时间戳获胜
4. 合并：将所有唯一的MCP合并到主配置中
5. 分发：将主配置写入每个平台的格式

错误处理

• 平台故障：继续同步其他平台，最后报告失败
• 配置解析错误：以代码2退出，显示错误行/列
• 未找到平台：警告，仅同步到可用平台

故障排除

“找不到命令”错误

问题： PATH中不存在服务器命令。

解决方案：

1. 安装所需的工具（例如。， npm install -g npx)
2. 在配置中使用完整路径进行命令
3. 跑 mcpx sync --verbose 查看健康检查详细信息

“找不到配置文件”

问题： ~/.mcpx/config.json 不存在。

解决方案： 跑 mcpx sync -它将从现有平台自动生成配置。

写入配置时“权限被拒绝”

问题： 对平台配置目录没有写访问权限。

解决方案：

1. 检查目录权限： ls -la ~/.claude.json
2. 修复权限： chmod u+w ~/.claude.json

健康检查失败

问题： 服务器未通过健康检查，因此被跳过。

解决方案：

1. 跑 mcpx sync --verbose 查看详细错误
2. 修复服务器配置或环境
3. 使用 mcpx sync --skip-health 强制同步（不推荐）

环境变量未扩展

问题： ${VAR} 没有用实际值代替。

解决方案：

1. 确保在shell中设置变量： echo $MY_VAR
2. 使用正确的语法： ${VAR_NAME} （不是 $VAR_NAME)
3. 导出变量： export MY_VAR=value

示例工作流

初始设置

# First run - imports existing configs from all platforms
mcpx sync
# Output: Found 18 MCPs across 4 platforms. Created ~/.mcpx/config.json

# View what was imported
mcpx list

添加新的MCP

# Interactive
mcpx add weather
# Prompts for type, command/url, args, env
# Auto-syncs to all platforms

# Non-interactive
mcpx add github --type stdio --command npx --args "-y,@modelcontextprotocol/server-github"

卸下MCP

mcpx remove old-server
# Removes from config and all platforms

项目设置

cd my-project
mcpx init
# Interactive: Select MCPs for this project
# Creates .mcp.json with selected MCPs

手动配置编辑

# Edit master config
nano ~/.mcpx/config.json

# Push changes to all platforms
mcpx sync

发展

从源头运行

git clone https://github.com/yourusername/mcp-multiverse.git
cd mcp-multiverse
uv pip install -e .
mcpx --help

运行测试

uv run pytest

类型检查

uv run mypy src/mcpx --strict

代码检查

uv run ruff check src tests

贡献

欢迎投稿！拜托：

1. 克隆该仓库
2. 创建要素分支
3. 进行更改
4. 运行测试和梳理
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

更新日志

v0.1.0（2026-01-08）

• 初始版本
• 支持6个AI编码平台（Claude、Gemini、Codex、Cline、Roo、Kilo）
• 具有环境变量扩展的JSON配置格式
• 支持Stdio和HTTP服务器
• 与最新胜利冲突解决方案双向同步
• 所有服务器类型的运行状况检查
• 每个平台保留5个备份的备份系统
• 项目级MCP配置（Claude、Roo、Kilo）
• 交互式 mcpx init 用于项目设置
• mcpx add 和 mcpx remove 命令
• 全面的验证和错误报告