Claude Code MCP Setup Guide for Windows

The Complete Guide to Setting Up MCP Servers on Windows (The Hard-Won Way)

A comprehensive guide documenting the actual process of getting MCP (Model Context Protocol) servers working with Claude Code on Windows, including all the pitfalls, dead-ends, and solutions discovered through real troubleshooting.

---

🎯 What This Guide Covers

This repository documents the complete journey of setting up MCP servers on Windows, including:

• ✅ What worked (the actual solution)
• ❌ What didn't work (and why)
• 🐛 Common errors and how to fix them
• 🪟 Windows-specific gotchas
• 📚 Working examples you can copy/paste

Target Audience: Future AIs helping users set up MCP, and humans who want to understand MCP configuration.

---

🚀 Quick Start (TL;DR)

The Solution That Actually Works on Windows:

1. Create .mcp.json in your project root (not .claude.json, not settings.json)
2. Use cmd /c wrapper for npx commands (Windows requirement)
3. Restart Claude Code from that project directory
4. Approve servers when prompted

Working Example:

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

Key Points:

• ✅ Use "command": "cmd" (NOT "npx")
• ✅ First arg is "/c"
• ✅ Use forward slashes in paths: "D:/1337" (NOT "D:\\1337")
• ✅ File location: Project root .mcp.json (NOT .claude/.mcp.json)

---

📖 Table of Contents

1. What Are MCP Servers?
2. Setup Guide - Step-by-step instructions
3. Windows-Specific Issues - Platform gotchas
4. Troubleshooting - Common problems & solutions
5. Examples - Working configurations
6. What We Learned - Key takeaways

---

🤔 What Are MCP Servers?

MCP (Model Context Protocol) is Anthropic's standard for connecting Claude to external tools and data sources.

Without MCP:

• 🟡 Claude can only read files you explicitly mention
• 🟡 No project-wide intelligence
• 🟡 Can't access GitHub, databases, or external services
• 🟡 Knowledge cutoff limitations

With MCP:

• ✅ Claude autonomously explores your entire project
• ✅ Analyzes codebases intelligently
• ✅ Creates GitHub PRs, queries databases
• ✅ Real-time web search
• ✅ Browser automation

Example Use Cases:

• "Find all TODO comments across all projects" → Filesystem MCP
• "Create a GitHub PR for this fix" → GitHub MCP
• "What's the latest Electron security patch?" → Brave Search MCP
• "Take a screenshot of my app" → Puppeteer MCP

---

🎬 The Journey (What We Actually Did)

Attempt 1: --mcp-config Flag ❌

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

Result: Didn't work. Claude Code started but MCP servers never loaded.

Why it failed: The --mcp-config flag doesn't work reliably on Windows (as of v2.0.37).

---

Attempt 2: Edit .claude/.claude.json ❌

Added mcpServers object to D:\1337\.claude\.claude.json:

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

Result: Didn't work. Servers never loaded.

Why it failed: Claude Code doesn't read mcpServers from .claude.json anymore (changed in recent versions).

---

Attempt 3: Add to settings.json ❌

Tried adding mcpServers to .claude/settings.local.json:

{
  "mcpServers": { ... }
}

Result: Schema validation error!

Error message:

Settings validation failed:
- : Unrecognized field: mcpServers

Why it failed: mcpServers is NOT a valid field in settings.json schema.

---

Attempt 4: .mcp.json with npx ⚠️

Created D:\1337\.mcp.json:

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

Result: Claude Code found the file! But gave warnings:

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

Progress: Claude Code detected the config, but couldn't start servers.

---

Attempt 5: .mcp.json with cmd /c ✅ SUCCESS!

Fixed the config:

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

Result: 🎉 WORKED!

Claude Code showed approval dialog:

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

❯ filesystem ✔
  sequential-thinking ✔
  puppeteer ✔

After pressing Enter:

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

MCP tools available: 15

Victory! 🚀

---

💡 What We Learned

Key Findings:

1. File Location Matters

   • ✅ .mcp.json in project root
   • ❌ .claude/.mcp.json
   • ❌ .claude.json
   • ❌ settings.json

2. Windows Requires cmd /c Wrapper

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

3. Path Format

   • ✅ Forward slashes: "D:/1337"
   • ⚠️ Backslashes need escaping: "D:\\1337" (but forward slashes are easier)

4. Version-Specific Behavior

   • As of Claude Code v2.0.37, MCP configuration has moved away from .claude.json
   • Older documentation may be outdated

5. Diagnostic Tools

   • /doctor command shows MCP diagnostics
   • /mcp command lists loaded servers
   • Both are essential for troubleshooting

---

📚 Documentation

• Setup Guide - Complete step-by-step setup instructions
• Windows-Specific Issues - Platform-specific gotchas and solutions
• Troubleshooting - Solutions to common problems
• Examples - Working configurations for popular MCP servers

---

🔧 Available MCP Servers

Server	Purpose	API Key Required?
filesystem	Project-wide file access	❌ No
sequential-thinking	Multi-step reasoning	❌ No
puppeteer	Browser automation	❌ No
github	Repository management	✅ Yes (PAT)
brave-search	Real-time web search	✅ Yes (API key)
postgresql	Database queries	✅ Yes (DB creds)
mongodb	MongoDB operations	✅ Yes (DB creds)
slack	Slack integration	✅ Yes (Bot token)

See Examples for configuration details.

---

🐛 Common Issues

Issue: "No MCP servers configured"

Solution: Check these in order:

1. Is .mcp.json in your project root? (Run ls -la to verify)
2. Did you use cmd /c wrapper? (Check with /doctor)
3. Did you restart Claude Code after creating the file?
4. Are you in the correct directory when starting Claude?

Issue: MCP servers start but don't work

Solution:

• Run /mcp to see loaded servers and available tools
• Try a simple test: "List files in this directory"
• Check if Node.js/npx is in PATH: node --version

See Troubleshooting Guide for more.

---

🤝 Contributing

Found a different solution? Hit another issue? Contributions welcome!

1. Fork this repo
2. Create a feature branch
3. Document your findings
4. Submit a PR

Especially valuable:

• Solutions for different Windows versions
• PowerShell-specific issues
• Alternative configurations that work

---

📄 License

MIT License - See LICENSE file for details.

---

🙏 Acknowledgments

This guide was created through actual troubleshooting with Claude (Sonnet 4.5) helping a user set up MCP servers on Windows. Every "what didn't work" section represents a real attempt and debugging session.

Why document the failures? Because knowing what doesn't work is often more valuable than just knowing what does. It saves time and prevents others from going down the same dead-ends.

---

📞 Support

• Official MCP Docs: https://docs.claude.com/en/docs/claude-code/mcp
• Claude Code Issues: https://github.com/anthropics/claude-code/issues
• MCP Servers Repository: https://github.com/modelcontextprotocol/servers

---

🔖 Quick Reference Card

# 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

---

Last Updated: November 14, 2025 Claude Code Version: 2.0.37 Platform: Windows 11

---

Made with ❤️ by humans and AI working together