# Claude Mcp Windows Guide

> Complete guide for setting up MCP servers with Claude Code on Windows. Documents actual troubleshooting journey, solutions to common issues, and working configurations.

- **Type:** MCP server
- **Install:** `agentstack add mcp-bunprinceton-claude-mcp-windows-guide`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BunPrinceton](https://agentstack.voostack.com/s/bunprinceton)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [BunPrinceton](https://github.com/BunPrinceton)
- **Source:** https://github.com/BunPrinceton/claude-mcp-windows-guide

## Install

```sh
agentstack add mcp-bunprinceton-claude-mcp-windows-guide
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.

[](https://opensource.org/licenses/MIT)
[](https://www.microsoft.com/windows)
[](https://claude.ai/code)

---

## 🎯 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:**

```json
{
  "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?](#what-are-mcp-servers)
2. [Setup Guide](docs/SETUP-GUIDE.md) - Step-by-step instructions
3. [Windows-Specific Issues](docs/WINDOWS-SPECIFIC.md) - Platform gotchas
4. [Troubleshooting](docs/TROUBLESHOOTING.md) - Common problems & solutions
5. [Examples](docs/EXAMPLES.md) - Working configurations
6. [What We Learned](#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 ❌
```bash
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`:
```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`:
```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`:
```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:
```json
{
  "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**
   ```json
   "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](docs/SETUP-GUIDE.md)** - Complete step-by-step setup instructions
- **[Windows-Specific Issues](docs/WINDOWS-SPECIFIC.md)** - Platform-specific gotchas and solutions
- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Solutions to common problems
- **[Examples](docs/EXAMPLES.md)** - 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](docs/EXAMPLES.md) 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](docs/TROUBLESHOOTING.md) 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](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

```bash
# 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**

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BunPrinceton](https://github.com/BunPrinceton)
- **Source:** [BunPrinceton/claude-mcp-windows-guide](https://github.com/BunPrinceton/claude-mcp-windows-guide)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bunprinceton-claude-mcp-windows-guide
- Seller: https://agentstack.voostack.com/s/bunprinceton
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.