使用说明

Windows版Claude代码MCP安装指南

在Windows上设置MCP服务器的完整指南（来之不易的方法）

一份全面的指南，记录了让MCP（模型上下文协议）服务器在Windows上使用Claude Code的实际过程，包括通过实际故障排除发现的所有陷阱、死胡同和解决方案。

🎯 本指南涵盖的内容

此存储库记录了 完整的旅程 在Windows上设置MCP服务器，包括：

✅ 什么有效（实际解决方案）
❌ 什么不起作用（以及为什么）
🐛 常见错误及其修复方法
🪟 Windows特有的陷阱
📚 您可以复制/粘贴的工作示例

目标受众： 未来的人工智能将帮助用户设置MCP，以及想要了解MCP配置的人。

🚀 快速入门（TL；DR）

在Windows上实际有效的解决方案：

创建 .mcp.json 在项目根目录中 （不是 .claude.json，不 settings.json)
使用 cmd /c 包装器 对于npx命令（Windows要求）
重新启动Claude代码 从该项目目录
批准服务器 当系统提示时

工作示例：

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "D:/1337"]
    }
  }
}

要点：

✅ 使用 "command": "cmd" （不是 "npx")
✅ 第一个参数是 "/c"
✅ 在路径中使用正斜杠： "D:/1337" （不是 "D:\\1337")
✅ 文件位置：项目根目录 .mcp.json （不是 .claude/.mcp.json)

📖 目录

什么是MCP服务器？
安装指南 -分步说明
Windows特定问题 -平台故障
故障排除 -常见问题及解决方法
例子 -工作配置
我们的收获 -关键要点

🤔 什么是MCP服务器？

MCP（模型上下文协议） 是Anthropic将Claude连接到外部工具和数据源的标准。

没有MCP：

🟡 Claude只能读取您明确提及的文件
🟡 没有项目范围的情报
🟡 无法访问GitHub、数据库或外部服务
🟡 知识截断限制

使用MCP：

✅ Claude自主探索你的整个项目
✅ 智能分析代码库
✅ 创建GitHub PR，查询数据库
✅ 实时网络搜索
✅ 浏览器自动化

示例用例：

“查找所有项目中的所有TODO注释”→ 文件系统MCP
“为此修复创建GitHub PR”→ GitHub MCP
“最新的电子安全补丁是什么？”→ 勇敢搜索MCP
“截取我的应用程序的屏幕截图”→ 木偶MCP

🎬 旅程（我们实际上做了什么）

尝试1： `--mcp-config` 旗帜❌

claude --mcp-config D:\1337\.claude\quick-start-mcp.json

结果： 不起作用。Claude Code启动，但MCP服务器从未加载。

失败的原因： 这 --mcp-config 标志在Windows上无法可靠工作（从v2.0.37开始）。

尝试2：编辑 `.claude/.claude.json` ❌

添加 mcpServers 反对 D:\1337\.claude\.claude.json:

{
  "projects": {
    "D:\\1337": {
      "mcpServers": {
        "filesystem": { ... }
      }
    }
  }
}

结果： 不起作用。服务器从未加载。

失败的原因： 克劳德代码不可读 mcpServers 从 .claude.json 更多（在最近的版本中有所更改）。

尝试3：添加到 `settings.json` ❌

尝试添加 mcpServers 到 .claude/settings.local.json:

{
  "mcpServers": { ... }
}

结果： 架构验证错误！

错误消息：

Settings validation failed:
- : Unrecognized field: mcpServers

失败的原因： mcpServers 不是中的有效字段 settings.json 模式。

尝试4： `.mcp.json` 与npx⚠️

创建 D:\1337\.mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:/1337"]
    }
  }
}

结果： 克劳德·科德找到了文件！但给出了警告：

[Warning] [filesystem] mcpServers.filesystem: Windows requires 'cmd /c' wrapper to execute npx

进展： Claude Code检测到配置，但无法启动服务器。

尝试5： `.mcp.json` 随着 `cmd /c` ✅ 成功！

已修复配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "D:/1337"]
    }
  }
}

结果： 🎉 工作！

Claude Code显示审批对话框：

3 new MCP servers found in .mcp.json
Select any you wish to enable.

❯ filesystem ✔
  sequential-thinking ✔
  puppeteer ✔

按下Enter键后：

Loading MCP servers...
✓ filesystem
✓ sequential-thinking
✓ puppeteer

MCP tools available: 15

胜利！ 🚀

💡 我们的收获

主要发现：

文件位置很重要
- ✅ .mcp.json 在项目根中
- ❌ .claude/.mcp.json
- ❌ .claude.json
- ❌ settings.json

Windows需要 cmd /c 包装器

"command": "cmd",
"args": ["/c", "npx", "-y", "..."]

路径格式
- ✅ 正斜杠： "D:/1337"
- ⚠️ 反斜杠需要转义： "D:\\1337" （但正斜杠更容易）
版本特定行为
- 从Claude Code v2.0.37开始，MCP配置已经从 .claude.json
- 旧文档可能已过时
诊断工具
- /doctor 命令显示MCP诊断
- /mcp 命令列出已加载的服务器
- 两者对于故障排除都是必不可少的

📚 文档

安装指南 -完成分步设置说明
Windows特定问题 -平台特定的陷阱和解决方案
故障排除 -常见问题的解决方案
例子 -常用MCP服务器的工作配置

🔧 可用的MCP服务器

是否需要服务器	用途	API密钥？
文件系统	项目范围内的文件访问	❌ 没有
顺序思维	多步推理	❌ 没有
操纵者	浏览器自动化	❌ 没有
GitHub	存储库管理	✅ 是（PAT）
勇敢的搜寻	实时网络搜索	✅ 是（API密钥）
PostgreSQL	数据库查询	✅ 是（DB信用）
MongoDB	MongoDB操作	✅ 是（DB信用）
松弛	松弛集成	✅ 是（Bot令牌）

看例子有关配置详细信息。

🐛 常见问题

问题：“未配置MCP服务器”

解决方案： 按顺序检查这些：

是 .mcp.json 在你的项目根中？（奔跑 ls -la 验证）
你用过吗 cmd /c 包装纸？（请与 /doctor)
创建文件后是否重新启动了Claude Code？
启动Claude时，您是否在正确的目录中？

问题：MCP服务器启动但不工作

解决方案：

跑 /mcp 查看已加载的服务器和可用工具
尝试一个简单的测试： "List files in this directory"
检查Node.js/npx是否在PATH中： node --version

看故障排除指南更多。

🤝 贡献

找到不同的解决方案了吗？遇到另一个问题？欢迎投稿！

分叉此回购
创建要素分支
记录你的发现
提交PR

特别有价值：

针对不同Windows版本的解决方案
PowerShell特定问题
有效的替代配置

📄 许可证

MIT许可证-请参阅许可证文件以获取详细信息。

🙏 致谢

本指南是通过Claude（Sonnet 4.5）帮助用户在Windows上设置MCP服务器的实际故障排除而创建的。每个“什么不起作用”部分都代表了一次真正的尝试和调试过程。

为什么要记录失败？ 因为知道什么不工作往往比仅仅知道做什么更有价值。它节省了时间，并防止其他人走上同样的死胡同。

📞 支持

MCP官方文件： https://docs.claude.com/en/docs/claude-code/mcp
Claude代码问题： https://github.com/anthropics/claude-code/issues
MCP服务器存储库： https://github.com/modelcontextprotocol/servers

🔖 快速参考卡

# Check if MCP is working
/mcp

# Run diagnostics
/doctor

# Test MCP servers
"List all files in the project"
"Find all TODO comments"
"What JavaScript files exist?"

# Restart to reload config
Ctrl+C → cd D:\1337 → claude

最后更新时间： 2025年11月14日 克劳德代码版本： 2.0.37 平台： Windows 11

由以下材料制成❤️ 人类和人工智能协同工作

使用说明

Windows版Claude代码MCP安装指南

🎯 本指南涵盖的内容

🚀 快速入门（TL；DR）

在Windows上实际有效的解决方案：

📖 目录

🤔 什么是MCP服务器？

没有MCP：

使用MCP：

🎬 旅程（我们实际上做了什么）

尝试1： --mcp-config 旗帜❌

尝试2：编辑 .claude/.claude.json ❌

尝试3：添加到 settings.json ❌

尝试4： .mcp.json 与npx⚠️

尝试5： .mcp.json 随着 cmd /c ✅ 成功！