From b769ff24ee3c40781f81d7907fceeb6104e79e20 Mon Sep 17 00:00:00 2001
From: czlonkowski <56956555+czlonkowski@users.noreply.github.com>
Date: Mon, 16 Jun 2025 23:55:31 +0200
Subject: [PATCH] docs: restructure README for local installation first, warn
 about Docker issues
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Based on debugging MCP initialization timeout issues:

1. Changed Quick Start to prioritize local installation (working)
2. Moved Docker to Option 2 with experimental warning
3. Added detailed explanation of Docker timeout issue:
   - Server receives initialize request but doesn't respond
   - Claude times out after 60 seconds
   - Container outputs "Shutting down..." breaking JSON-RPC

4. Removed non-existent npx package reference
5. Consolidated configuration file locations
6. Removed HTTP server section from Quick Start (keep it simple)

The Docker issue appears to be related to MCP protocol handling in the
container environment. Local installation works reliably, so that's now
the recommended approach until Docker issues are resolved.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md | 68 ++++++++++++++++++++++++-------------------------------
 1 file changed, 29 insertions(+), 39 deletions(-)

diff --git a/README.md b/README.md
index 12f9bc8..d702bb2 100644
--- a/README.md
+++ b/README.md
@@ -31,67 +31,57 @@ When Claude, Anthropic's AI assistant, tested n8n-MCP, the results were transfor
 
 [Read the full interview →](docs/CLAUDE_INTERVIEW.md)
 
-## 🚀 Quick Start with Docker
+## 🚀 Quick Start
 
 Get n8n-MCP running in 5 minutes:
 
-**Prerequisites:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed on your system
+### Option 1: Local Installation (Recommended)
 
-### For Claude Desktop
+**Prerequisites:** [Node.js](https://nodejs.org/) installed on your system
 
-1. First, pull the Docker image:
 ```bash
-docker pull ghcr.io/czlonkowski/n8n-mcp:latest
+# 1. Clone and setup
+git clone https://github.com/czlonkowski/n8n-mcp.git
+cd n8n-mcp
+npm install
+npm run build
+npm run rebuild
+
+# 2. Test it works
+npm start
 ```
 
-2. Add this to your Claude Desktop config:
+Add to Claude Desktop config:
 ```json
 {
   "mcpServers": {
     "n8n-mcp": {
-      "command": "docker",
-      "args": [
-        "run",
-        "--rm",
-        "-i",
-        "--name", "claude-n8n-mcp",
-        "-e", "MCP_MODE=stdio",
-        "-e", "LOG_LEVEL=error",
-        "-e", "DISABLE_CONSOLE_OUTPUT=true",
-        "ghcr.io/czlonkowski/n8n-mcp:latest"
-      ]
+      "command": "node",
+      "args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"]
     }
   }
 }
 ```
 
-3. **Configuration file locations:**
-   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-   - **Linux**: `~/.config/Claude/claude_desktop_config.json`
+### Option 2: Docker (Experimental)
 
-4. **Restart Claude Desktop** - That's it! 🎉
-
-### For HTTP Server (Teams)
-
-If you want to run n8n-MCP as a shared service:
+⚠️ **Known Issue**: Docker support has a timeout issue with MCP initialization. The server doesn't respond to Claude's initialize request within 60 seconds, causing connection failures. Use local installation until this is resolved.
 
+For brave souls who want to help debug:
 ```bash
-# 1. Create .env file
-echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
-
-# 2. Run with Docker Compose
-docker run -d \
-  --name n8n-mcp-server \
-  --restart unless-stopped \
-  -e MCP_MODE=http \
-  -e USE_FIXED_HTTP=true \
-  -e AUTH_TOKEN=$AUTH_TOKEN \
-  -p 3000:3000 \
-  ghcr.io/czlonkowski/n8n-mcp:latest
+docker pull ghcr.io/czlonkowski/n8n-mcp:latest
 ```
 
-See [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md) for team setup.
+See [Issue #X](https://github.com/czlonkowski/n8n-mcp/issues) for updates.
+
+### Configuration File Locations
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+**Remember to restart Claude Desktop after updating configuration!** 🎉
+
 
 ## Features