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
______________________________________________________________________
由以下材料制成❤️ 人类和人工智能协同工作