fix: resolve Claude Desktop stdio communication issues and update documentation

- Fixed console output interference with stdio JSON-RPC protocol:
  - Modified logger to suppress ALL output in stdio mode
  - Added DISABLE_CONSOLE_OUTPUT environment variable support
  - Updated error handlers to respect stdio mode

- Updated Claude Desktop configuration documentation:
  - Added required environment variables for clean stdio communication
  - Promoted local installation as recommended method
  - Fixed remote connection instructions (removed broken mcp-remote)
  - Added troubleshooting section for common issues
  - Updated both README.md and docs/README_CLAUDE_SETUP.md

- Environment variables now required for stdio mode:
  - MCP_MODE=stdio
  - LOG_LEVEL=error
  - DISABLE_CONSOLE_OUTPUT=true
  - NODE_ENV=production

This ensures clean JSON-RPC communication without console output corruption.

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

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -75,23 +75,27 @@ npm run start:http # HTTP mode for remote access
 
 ## 🔧 Claude Desktop Configuration
 
-### For Local Installation (stdio mode)
+### For Local Installation (stdio mode) - Recommended
 
-**macOS/Linux:**
 ```json
 {
   "mcpServers": {
-    "n8n-documentation": {
+    "n8n-mcp": {
       "command": "node",
       "args": ["/path/to/n8n-mcp/dist/mcp/index.js"],
       "env": {
-        "NODE_ENV": "production"
+        "NODE_ENV": "production",
+        "LOG_LEVEL": "error",
+        "MCP_MODE": "stdio",
+        "DISABLE_CONSOLE_OUTPUT": "true"
       }
     }
   }
 }
 ```
 
+⚠️ **Important**: The environment variables above are required for proper stdio communication.
+
 ### For Docker (stdio mode)
 
 ```json
@@ -102,6 +106,8 @@ npm run start:http # HTTP mode for remote access
       "args": [
         "run", "--rm", "-i",
         "-e", "MCP_MODE=stdio",
+        "-e", "LOG_LEVEL=error",
+        "-e", "DISABLE_CONSOLE_OUTPUT=true",
         "-v", "n8n-mcp-data:/app/data",
         "ghcr.io/czlonkowski/n8n-mcp:latest"
       ]
@@ -112,22 +118,19 @@ npm run start:http # HTTP mode for remote access
 
 ### For Remote Server (HTTP mode)
 
-**Important**: Requires Node.js 18+ on your local machine.
+For production deployments with HTTP mode, use the custom HTTP client:
 
 ```json
 {
   "mcpServers": {
     "n8n-remote": {
-      "command": "npx",
+      "command": "node",
       "args": [
-        "-y",
+        "/path/to/n8n-mcp/scripts/mcp-http-client.js",
-        "mcp-remote",
+        "http://your-server.com:3000/mcp"
-        "https://your-server.com/mcp",
-        "--header",
-        "Authorization: Bearer ${AUTH_TOKEN}"
       ],
       "env": {
-        "AUTH_TOKEN": "your-auth-token"
+        "MCP_AUTH_TOKEN": "your-auth-token"
       }
     }
   }

docs/README_CLAUDE_SETUP.md

@@ -1,38 +1,16 @@
 # Claude Desktop Configuration for n8n-MCP
 
-This guide helps you connect n8n-MCP to Claude Desktop, giving Claude comprehensive knowledge about n8n's 450+ workflow automation nodes.
+This guide helps you connect n8n-MCP to Claude Desktop, giving Claude comprehensive knowledge about n8n's 525+ workflow automation nodes.
 
 ## 🎯 Prerequisites
 
 - Claude Desktop installed
-- For remote connections: Node.js 18+ on your local machine
+- For local installation: Node.js (any version)
 - For Docker: Docker Desktop or Docker Engine
 
 ## 🛠️ Configuration Methods
 
-### Method 1: Docker (Simplest) 🐳
+### Method 1: Local Installation (Recommended) 💻
-
-No installation needed - runs directly from Docker:
-
-```json
-{
-  "mcpServers": {
-    "n8n-docker": {
-      "command": "docker",
-      "args": [
-        "run", "--rm", "-i",
-        "-e", "MCP_MODE=stdio",
-        "-v", "n8n-mcp-data:/app/data",
-        "ghcr.io/czlonkowski/n8n-mcp:latest"
-      ]
-    }
-  }
-}
-```
-
-✨ **Benefits**: No setup required, always up-to-date, isolated environment.
-
-### Method 2: Local Installation
 
 1. **Install and build:**
    ```bash
@@ -47,44 +25,75 @@ No installation needed - runs directly from Docker:
    ```json
    {
      "mcpServers": {
-       "n8n-documentation": {
+       "n8n-mcp": {
          "command": "node",
          "args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"],
          "env": {
-           "NODE_ENV": "production"
+           "NODE_ENV": "production",
+           "LOG_LEVEL": "error",
+           "MCP_MODE": "stdio",
+           "DISABLE_CONSOLE_OUTPUT": "true"
          }
        }
      }
    }
    ```
 
-⚠️ **Important**: Use absolute paths, not relative paths.
+⚠️ **Important**: 
+- Use absolute paths, not relative paths
+- The environment variables shown above are critical for proper stdio communication
 
-### Method 3: Remote Server Connection
+### Method 2: Docker 🐳
 
-**Requirements**: Node.js 18+ installed locally
+No installation needed - runs directly from Docker:
 
 ```json
 {
   "mcpServers": {
-    "n8n-remote": {
+    "n8n-docker": {
-      "command": "npx",
+      "command": "docker",
       "args": [
-        "-y",
+        "run", "--rm", "-i",
-        "mcp-remote",
+        "-e", "MCP_MODE=stdio",
-        "https://your-server.com/mcp",
+        "-e", "LOG_LEVEL=error",
-        "--header",
+        "-e", "DISABLE_CONSOLE_OUTPUT=true",
-        "Authorization: Bearer ${AUTH_TOKEN}"
+        "-v", "n8n-mcp-data:/app/data",
+        "ghcr.io/czlonkowski/n8n-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+✨ **Benefits**: No setup required, always up-to-date, isolated environment.
+
+### Method 3: Remote Server Connection (Advanced)
+
+⚠️ **Note**: Remote connections are complex and may have compatibility issues. Consider using local installation instead.
+
+For production deployments with multiple users:
+
+1. **Deploy server with HTTP mode** (see [HTTP Deployment Guide](./HTTP_DEPLOYMENT.md))
+
+2. **Connect using custom HTTP client:**
+   ```json
+   {
+     "mcpServers": {
+       "n8n-remote": {
+         "command": "node",
+         "args": [
+           "/path/to/n8n-mcp/scripts/mcp-http-client.js",
+           "http://your-server.com:3000/mcp"
          ],
          "env": {
-        "AUTH_TOKEN": "your-auth-token"
+           "MCP_AUTH_TOKEN": "your-auth-token"
          }
        }
      }
    }
    ```
 
-📝 **Note**: Remote MCP is also natively supported in Claude Pro/Team/Enterprise via Settings > Integrations.
+📝 **Note**: Native remote MCP support is available in Claude Pro/Team/Enterprise via Settings > Integrations.
 
 ## 📁 Configuration File Locations
 
@@ -164,11 +173,30 @@ docker pull ghcr.io/czlonkowski/n8n-mcp:latest
 docker ps
 ```
 
+### Common Issues
+
+**"Expected ',' or ']' after array element" errors in logs:**
+- Cause: Console output interfering with stdio communication
+- Fix: Ensure all required environment variables are set:
+  - `MCP_MODE=stdio`
+  - `LOG_LEVEL=error`
+  - `DISABLE_CONSOLE_OUTPUT=true`
+
+**"NODE_MODULE_VERSION mismatch" warnings:**
+- Not a problem! The server automatically falls back to a pure JavaScript implementation
+- The warnings are suppressed with proper environment variables
+
+**Server appears but tools don't work:**
+- Check that you've built the project: `npm run build`
+- Verify the database exists: `npm run rebuild`
+- Restart Claude Desktop completely (quit and reopen)
+
 ### Quick Fixes
 
 - 🔄 **Always restart Claude** after config changes
 - 📋 **Copy example configs exactly** (watch for typos)
 - 📂 **Use absolute paths** (/Users/... not ~/...)
 - 🔍 **Check logs**: View > Developer > Logs in Claude Desktop
+- 🛑 **Set all environment variables** shown in the examples
 
 For more help, see [Troubleshooting Guide](./TROUBLESHOOTING.md)

src/mcp/index.ts

@@ -5,21 +5,25 @@ import { logger } from '../utils/logger';
 
 // Add error details to stderr for Claude Desktop debugging
 process.on('uncaughtException', (error) => {
+  if (process.env.MCP_MODE !== 'stdio') {
     console.error('Uncaught Exception:', error);
+  }
   logger.error('Uncaught Exception:', error);
   process.exit(1);
 });
 
 process.on('unhandledRejection', (reason, promise) => {
+  if (process.env.MCP_MODE !== 'stdio') {
     console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+  }
   logger.error('Unhandled Rejection:', reason);
   process.exit(1);
 });
 
 async function main() {
-  try {
   const mode = process.env.MCP_MODE || 'stdio';
   
+  try {
     // Only show debug messages in HTTP mode to avoid corrupting stdio communication
     if (mode === 'http') {
       console.error(`Starting n8n Documentation MCP Server in ${mode} mode...`);
@@ -55,6 +59,8 @@ async function main() {
       await server.run();
     }
   } catch (error) {
+    // In stdio mode, we cannot output to console at all
+    if (mode !== 'stdio') {
       console.error('Failed to start MCP server:', error);
       logger.error('Failed to start MCP server', error);
       
@@ -70,6 +76,7 @@ async function main() {
         console.error('2. Run: npm rebuild better-sqlite3');
         console.error('3. If that doesn\'t work, try: rm -rf node_modules && npm install');
       }
+    }
     
     process.exit(1);
   }

src/utils/logger.ts

@@ -54,6 +54,12 @@ export class Logger {
     if (level <= this.config.level) {
       const formattedMessage = this.formatMessage(levelName, message);
       
+      // In stdio mode, suppress ALL console output to avoid corrupting JSON-RPC
+      if (process.env.MCP_MODE === 'stdio' || process.env.DISABLE_CONSOLE_OUTPUT === 'true') {
+        // Silently drop all logs in stdio mode
+        return;
+      }
+      
       // In HTTP mode during request handling, suppress console output
       // The ConsoleManager will handle this, but we add a safety check
       if (process.env.MCP_MODE === 'http' && process.env.MCP_REQUEST_ACTIVE === 'true') {