内容
<p align="center">
<img src="assets/hero.png" alt="mcp-config-cookbook — 复制粘贴 MCP 服务器配置，适用于 Claude Code、Cursor、Windsurf 和 VS Code，附带一个生成器，可为每个客户端生成确切的 JSON" width="840">
</p>
# MCP 配置大全 — MCP 服务器配置适用于 Claude Code、Cursor、Windsurf 和 VS Code
> 相同的 MCP 服务器在每个客户端都需要 **略微不同的 JSON** — 不同的顶级键、不同的文件位置、不同的秘密处理方式，以及一个 Windows `npx` 易错点，会导致一半的设置失败。这是复制粘贴参考资料，加上一个小型生成器 (`mcpgen`)，可为你正在使用的客户端生成 **确切** 的区块。
模型上下文协议现在无处不在，但配置格式 *几乎* 标准 — 而小差异正是导致你花费 20 分钟的“为什么无法连接”的问题所在。本仓库收集了可用的配置，放在一个地方。
## 解释差异的表格
| 客户端 | 顶级键 | 配置文件 | `${VAR}` 扩展 |
|---|---|---|---|
| **Claude Code** | `mcpServers` | `./.mcp.json`（项目） · `~/.claude.json`（用户） | ✅ `${VAR}` 和 `${VAR:-default}` |
| **Cursor** | `mcpServers` | `./.cursor/mcp.json` · `~/.cursor/mcp.json` | — |
| **Windsurf** | `mcpServers` | `~/.codeium/windsurf/mcp_config.json` | — |
| **VS Code** | **`servers`** ⚠️ | `./.vscode/mcp.json` | ✅ + `inputs` 用于提示的秘密 |
> ⚠️ **VS Code 是陷阱：** 键是 **`servers`**，而不是 `mcpServers`。在 `.vscode/mcp.json` 中粘贴 `mcpServers` 区块，它会静默失效。
## 生成器 — 获取确切的区块
```bash
npx mcp-config-cookbook --help # 或：npx mcpgen --help 安装后
```
```bash
# 标准输入服务器（常见情况）
npx mcpgen --client claude-code --name github \
--command npx --args "-y @modelcontextprotocol/server-github" \
--env GITHUB_TOKEN=ghp_xxx
# 远程（HTTP）服务器
npx mcpgen --client cursor --name linear --url https://mcp.linear.app/sse
# Windows：在 `cmd /c` 中包装 npx（参见下面的易错点）
npx mcpgen --client claude-code --name fs \
--command npx --args "-y @modelcontextprotocol/server-filesystem ." --windows
```
它会打印正确的键 (`mcpServers` 与 `servers`)、正确的形状（stdio 与 `{type:"http",url}`），并告诉你将内容粘贴到哪个文件中。
## 复制粘贴：每个客户端的 `github` 服务器
**Claude Code** — `./.mcp.json`
```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
}
}
}
```
**Cursor** — `./.cursor/mcp.json` · **Windsurf** — `~/.codeium/windsurf/mcp_config.json`（形状相同）
```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "ghp_xxx" }
}
}
}
```
**VS Code** — `./.vscode/mcp.json`（注意 `servers` + `inputs`）
```json
{
"inputs": [
{ "id": "github_token", "type": "promptString", "description": "GitHub 令牌", "password": true }
],
"servers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_TOKEN": "${input:github_token}" }
}
}
}
```
**远程（HTTP/SSE）服务器** — Claude Code / Cursor / Windsurf
```json
{
"mcpServers": {
"linear": { "type": "http", "url": "https://mcp.linear.app/sse" }
}
}
```
## Windows 易错点（没人记录的部分）
- **`npx`/`npm` 需要 `cmd /c` 包装器。** 在 Windows 上，直接启动 `npx` 通常会因 `ENOENT` 而失败。使用 `"command": "cmd"`、`"args": ["/c", "npx", "-y", "<server>"]`。生成器使用 `--windows` 参数执行此操作。
- **路径使用反斜杠，需要在 JSON 中转义** (`C:\\Users\\you\\project`) — 或者直接使用正斜杠。
- **配置文件位置** 解析 `~` 为 `%USERPROFILE%`（例如 `C:\Users\you\.cursor\mcp.json`，`C:\Users\you\.codeium\windsurf\mcp_config.json`）。
## 秘密
- **不要在提交的项目文件中硬编码令牌。** 使用环境变量扩展（Claude Code / VS Code 中的 `${GITHUB_TOKEN}`）、VS Code `inputs` 或操作系统的密钥链。
- 想确保您没有在配置文件中留下密钥吗？请使用 [`claude-guard`](https://github.com/novalidesignl-ship-it/claude-guard) 扫描。
## 范围与诚实
- 目前涵盖 **Claude Code、Cursor、Windsurf 和 VS Code**。欢迎为 Codex、Zed、JetBrains 等其他客户端提交拉取请求。
- 客户端配置格式 **可能会变化** — 如有疑问，请查看客户端自己的文档。本仓库有日期和版本，您可以了解其当前状态。
- `clients.json` 是可机器读取的真实来源（将其导入您自己的工具中）。
## 许可证
[MIT](./LICENSE) © novalidesignl-ship-it
---
*独立的开源参考资料。 不隶属于 Anthropic、Cursor、Codeium/Windsurf 或 Microsoft。*
