WINDOWS_SETUP.mdā¢4.91 kB
# Connecting Claude Desktop (Windows) to MCP Server (WSL)
This guide explains how to connect Claude Desktop running on your Windows host machine to the MCP server running in WSL.
## Method 1: Direct WSL Command (Recommended)
This is the simplest approach - Claude Desktop can directly execute commands in WSL.
### Steps:
1. **Locate Claude Desktop Config on Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```
- Press `Win + R`, type `%APPDATA%\Claude`, press Enter
- If the folder doesn't exist, create it
- If `claude_desktop_config.json` doesn't exist, create it
2. **Copy the WSL Configuration:**
Copy the contents from: `/home/dhevb/workspaces/spec3-mcp-server/claude_desktop_config_windows.json`
```json
{
"mcpServers": {
"spec3-mcp-server": {
"command": "wsl",
"args": [
"-d", "Ubuntu",
"--cd", "/home/dhevb/workspaces/spec3-mcp-server",
"bash", "-c",
"source venv/bin/activate && python src/spec3_mcp_server/main.py"
]
}
}
}
```
3. **Restart Claude Desktop**
4. **Test the Connection:**
- Start a new conversation
- Look for the tools icon
- Try: "Use the hello_world tool"
### Troubleshooting Method 1:
- **WSL Distribution Name**: If your WSL distribution isn't named "Ubuntu", change `-d Ubuntu` to your distribution name
- **Check WSL**: Run `wsl -l -v` in Windows Command Prompt to see your distributions
- **Path Issues**: Ensure the path `/home/dhevb/workspaces/spec3-mcp-server` is correct
---
## Method 2: HTTP Network Connection (Alternative)
If Method 1 doesn't work, use this network-based approach.
### Steps:
1. **Start the HTTP Server in WSL:**
```bash
cd /home/dhevb/workspaces/spec3-mcp-server
source venv/bin/activate
python src/spec3_mcp_server/http_server.py
```
The server will start on `http://0.0.0.0:8000` and show:
```
INFO: Uvicorn running on http://0.0.0.0:8000
```
2. **Get Your WSL IP Address:**
```bash
ip addr show eth0 | grep "inet " | awk '{print $2}' | cut -d/ -f1
```
Current WSL IP: `172.28.242.198` (this may change after WSL restart)
3. **Test HTTP Connection from Windows:**
Open Command Prompt on Windows and test:
```cmd
curl http://172.28.242.198:8000/health
```
Should return: `{"status":"healthy","service":"spec3-mcp-server"}`
4. **Configure Claude Desktop for HTTP:**
Use this configuration in `%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"spec3-mcp-server-http": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-everything",
"http://172.28.242.198:8000"
]
}
}
}
```
5. **Restart Claude Desktop**
### Troubleshooting Method 2:
- **IP Address Changes**: WSL IP can change after restart. Re-run the IP command and update the config
- **Firewall**: Windows Firewall might block the connection. Allow port 8000 if needed
- **WSL Networking**: Ensure WSL2 is being used (not WSL1) for proper networking
---
## Testing Your Connection
Once configured, test in Claude Desktop:
1. **Check Tools Icon**: Look for a tools/hammer icon in the chat interface
2. **Test Commands**:
- "Use the hello_world tool"
- "Echo this message: Hello from Windows!"
- "Get server information"
- "List all available tools"
## Expected Output
When working correctly, you should see responses like:
- **hello_world**: "Hello from Spec3 MCP Server! š"
- **echo_message**: "Echo: Hello from Windows! (processed by Spec3 MCP Server)"
- **get_server_info**: Detailed server information
- **list_available_tools**: List of 4 available tools
## Common Issues
### "No tools available" or tools icon missing:
- Check Claude Desktop logs (if available)
- Verify the MCP server is running in WSL
- Ensure the configuration file syntax is correct (valid JSON)
- Try restarting Claude Desktop
### WSL command not found:
- Ensure WSL is installed and configured on Windows
- Try running `wsl --version` in Command Prompt
- Use Method 2 (HTTP) as alternative
### Network connection refused:
- Check if the HTTP server is running: `curl http://localhost:8000/health` in WSL
- Verify the WSL IP address hasn't changed
- Check Windows Firewall settings
## Which Method to Use?
- **Method 1 (WSL Command)**: Simpler, more reliable, recommended for development
- **Method 2 (HTTP)**: More complex but works if WSL command integration has issues
Try Method 1 first, fall back to Method 2 if needed.
## Next Steps
Once you have the local connection working:
1. Test all the tools to understand MCP protocol behavior
2. Add more sophisticated tools to your server
3. Consider remote deployment options (Lambda, EC2, etc.)
4. Explore advanced MCP features like resources and prompts