Add comprehensive WSL setup guide for Windows users (#136)

README.md

@@ -73,6 +73,7 @@ Because these AI models [clearly aren't when they get chatty →](docs/ai_banter
   - [Complete Advanced Guide](docs/advanced-usage.md) - Model configuration, thinking modes, workflows, tool parameters
 
 - **Setup & Support**
+  - [WSL Setup Guide](#21-wsl-windows-subsystem-for-linux-setup-guide) - Windows Subsystem for Linux configuration
   - [Troubleshooting Guide](docs/troubleshooting.md) - Common issues and debugging steps
   - [License](#license) - Apache 2.0
 
@@ -183,7 +184,82 @@ cd zen-mcp-server
 
 **After updates:** Always run `./run-server.sh` again after `git pull` to ensure everything stays current.
 
-### 3. Add Your API Keys
+
+### 2.1. WSL (Windows Subsystem for Linux) Setup Guide
+
+If you're running on Windows with WSL, follow these additional steps to ensure proper configuration:
+
+#### Prerequisites for WSL
+```bash
+# Update WSL and ensure you have a recent Ubuntu distribution
+sudo apt update && sudo apt upgrade -y
+
+# Install required system dependencies
+sudo apt install -y python3-venv python3-pip curl git
+
+# Install Node.js and npm (required for Claude Code CLI)
+curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
+sudo apt install -y nodejs
+
+# Install Claude Code CLI globally
+npm install -g @anthropic-ai/claude-code
+```
+
+#### WSL-Specific Installation Steps
+
+1. **Clone the repository in your WSL environment** (not in Windows filesystem):
+   ```bash
+   # Navigate to your home directory or preferred location in WSL
+   cd ~
+   
+   # Clone the repository
+   git clone https://github.com/BeehiveInnovations/zen-mcp-server.git
+   cd zen-mcp-server
+   ```
+
+2. **Run the setup script**:
+   ```bash
+   # Make the script executable and run it
+   chmod +x run-server.sh
+   ./run-server.sh
+   ```
+
+3. **Verify Claude Code can find the MCP server**:
+   ```bash
+   # List configured MCP servers
+   claude mcp list
+   
+   # You should see 'zen' listed in the output
+   # If not, the setup script will provide the correct configuration
+   ```
+
+#### Troubleshooting WSL Issues
+
+**Python Environment Issues:**
+```bash
+# If you encounter Python virtual environment issues
+sudo apt install -y python3.12-venv python3.12-dev
+
+# Ensure pip is up to date
+python3 -m pip install --upgrade pip
+```
+
+**Path Issues:**
+- Always use the full WSL path for MCP configuration (e.g., `/home/YourName/zen-mcp-server/`)
+- The setup script automatically detects WSL and configures the correct paths
+
+**Claude Code Connection Issues:**
+```bash
+# If Claude Code can't connect to the MCP server, check the configuration
+cat ~/.claude.json | grep -A 10 "zen"
+
+# The configuration should show the correct WSL path to the Python executable
+# Example: "/home/YourName/zen-mcp-server/.zen_venv/bin/python"
+```
+
+**Performance Tip:** For best performance, keep your zen-mcp-server directory in the WSL filesystem (e.g., `~/zen-mcp-server`) rather than in the Windows filesystem (`/mnt/c/...`).
+
+### 4. Add Your API Keys
 
 ```bash
 # Edit .env to add your API keys (if not already set in environment)
@@ -221,7 +297,7 @@ If you were already running a `claude` code session, please exit and start a new
 2. **Copy the configuration** shown by `./run-server.sh -c` into your `claude_desktop_config.json`
 3. **Restart Claude Desktop** for changes to take effect
 
-### 4. Start Using It!
+### 5. Start Using It!
 
 Just ask Claude naturally:
 - "Think deeper about this architecture design with zen" → Claude picks best model + `thinkdeep`