Claude MCP Windows Guide

Windows版Claude代码MCP安装指南

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

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

  

______________________________________________________________________

🎯 本指南涵盖的内容

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

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

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

______________________________________________________________________

🚀 快速入门（TL；DR）

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

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

工作示例：

{
  "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)

______________________________________________________________________

📖 目录

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

______________________________________________________________________

🤔 什么是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

胜利！ 🚀

______________________________________________________________________

💡 我们的收获

主要发现：

1. 文件位置很重要

- ✅ .mcp.json 在项目根中 - ❌ .claude/.mcp.json - ❌ .claude.json - ❌ settings.json

1. Windows需要 cmd /c 包装器

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

1. 路径格式

- ✅ 正斜杠： "D:/1337" - ⚠️ 反斜杠需要转义： "D:\\1337" （但正斜杠更容易）

1. 版本特定行为

- 从Claude Code v2.0.37开始，MCP配置已经从 .claude.json - 旧文档可能已过时

1. 诊断工具

- /doctor 命令显示MCP诊断 - /mcp 命令列出已加载的服务器 - 两者对于故障排除都是必不可少的

______________________________________________________________________

📚 文档

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

______________________________________________________________________

🔧 可用的MCP服务器

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

______________________________________________________________________

🐛 常见问题

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

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

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

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

解决方案：

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

看 故障排除指南 更多。

______________________________________________________________________

🤝 贡献

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

1. 分叉此回购
2. 创建要素分支
3. 记录你的发现
4. 提交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

______________________________________________________________________

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