使用 chezmoi 的 Codex、Claude、Cursor 和 Copilot 的单一 MCP 配置

Source: Dev.to

当你在多台机器上使用多个编码代理时，MCP 配置漂移是不可避免的——除非你将 一个文件设为真相来源。
以下指南展示了一个实用、可复现的设置，适用于：

• Codex
• Claude Code
• Cursor
• GitHub Copilot（包括 VS Code 和 Copilot‑coding‑agent 场景）

核心思路

1. 在你的 chezmoi 源状态中保留一个规范的 MCP 清单。
2. 从该清单生成每个工具的原生配置格式。
3. 让 chezmoi 管理符号链接 / 模板以及机器特定的值。

所有四个工具都使用相同的概念字段来建模 MCP 服务器：

不同之处在于 文件位置 和 模式结构。
与其手动编辑四种格式，你只需维护 一个标准化模型，然后将其投射到每个目标文件中。

工具特定存储细节

标准 MCP 清单

创建一个描述所有服务器的单个 YAML 文件。例如：

# dot_config/mcp/servers.yaml
servers:
  github:
    transport: http
    url: "https://api.githubcopilot.com/mcp/"
    headers:
      Authorization: "Bearer ${GITHUB_TOKEN}"

  filesystem:
    transport: stdio
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/lukas"]
    env:
      NODE_NO_WARNINGS: "1"

提示： 将机密（${GITHUB_TOKEN}）存储在加密/私有文件中（参见下文 安全性）。

目录结构（chezmoi 源状态）

~/.local/share/chezmoi/
├─ .chezmoitemplates/
│   └─ mcp/
│       ├─ codex-config.toml.tmpl
│       ├─ claude-mcp.json.tmpl
│       ├─ cursor-mcp.json.tmpl
│       ├─ vscode-mcp.json.tmpl
│       └─ copilot-mcp-config.json.tmpl
├─ dot_config/
│   └─ mcp/
│       └─ servers.yaml          ← canonical model (committed)
├─ dot_codex/
│   └─ config.toml.tmpl
├─ dot_claude/
│   └─ mcp_servers.json.tmpl
├─ dot_cursor/
│   └─ mcp.json.tmpl
├─ dot_vscode/
│   └─ mcp.json.tmpl
└─ dot_copilot/
    └─ mcp-config.json.tmpl

• .chezmoitemplates 目录下的文件是可复用的代码片段。
• 以 .tmpl 为后缀（或位于 .chezmoitemplates 中）的文件会被识别为模板。
• 如 .chezmoi.os、.chezmoi.hostname 等机器信息可在模板中使用。

示例模板逻辑

{{- /* Render internal server only on work laptop */ -}}
{{- if eq .chezmoi.hostname "work-laptop" -}}
{
  "name": "internal",
  "type": "http",
  "url": "https://internal.example.com/mcp/",
  "headers": {
    "Authorization": "Bearer ${INTERNAL_TOKEN}"
  }
}
{{- end -}}

您还可以根据 .chezmoi.os、.chezmoi.hostname 或任何自定义事实，来变更文件系统根目录、公司专用服务器等。

Source‑State Attributes (chezmoi)

Recommended split

• Committed – servers.yaml（拓扑结构，非机密数据）
• Encrypted / private – 每台机器的机密（令牌，密码）

将环境变量引用（${GITHUB_TOKEN}）渲染到最终的工具配置中。

转换规则（一次性，在模板中）

应用配置

# From your chezmoi repo root
chezmoi apply

chezmoi 将会：

• 使用规范的 servers.yaml（以及任何加密/私有文件）渲染每个模板。
• 将生成的文件放置在相应的位置：

~/.codex/config.toml               ← MCP block
~/.claude.json   or   .mcp.json    ← projection
~/.cursor/mcp.json
.vscode/mcp.json
~/.copilot/mcp-config.json

切勿直接编辑生成的目标文件 —— 始终修改源模型或模板，然后重新运行 chezmoi apply。

Security & Reproducibility

• 严格的可复现性 – 从模板生成 所有 配置文件；仅对源文件进行编辑。
• 机密处理 – 将令牌保存在 encrypted_ 文件或外部密钥管理器中；在模板中通过环境变量引用它们。
• 版本控制 – 只提交规范模型（servers.yaml）和模板文件。

快速参考链接

• chezmoi – templating guide，machine facts，source‑state attributes
• OpenAI Codex MCP – advanced config docs
• Anthropic Claude Code MCP – settings overview
• Cursor MCP – official docs page confirming first‑class MCP support
• VS Code MCP – workspace (.vscode/mcp.json) and user config
• GitHub Copilot MCP – coding‑agent configuration

TL;DR

1. 单一的规范 YAML 模型（servers.yaml）。
2. 针对每个工具原生格式的模板。
3. chezmoi 负责渲染、符号链接以及机器特定的覆盖（私有/加密）。

结果：在 Codex、Claude、Cursor 和 Copilot 之间实现一致、无漂移的 MCP 配置，而不会被锁定到任何单一供应商的模式。