docs: comprehensive documentation update for production deployment

- Updated README.md with clear setup instructions and recent updates - Simplified Claude Desktop setup guide with troubleshooting - Enhanced HTTP deployment guide for production use - Streamlined troubleshooting guide with quick fixes - Added mcp-http-client.js for Node.js 16 compatibility - Fixed stdio mode console output corruption Key improvements: - Clear distinction between local and remote deployment - Node.js 18+ requirement for mcp-remote clearly documented - USE_FIXED_HTTP=true prominently featured for v2.3.2 - Production deployment best practices - Multi-user service considerations 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-06-15 01:11:02 +02:00
parent 63ef011aec
commit 149b59a541
6 changed files with 1014 additions and 1117 deletions
--- a/docs/README_CLAUDE_SETUP.md
+++ b/docs/README_CLAUDE_SETUP.md
@@ -1,57 +1,26 @@
 # Claude Desktop Configuration for n8n-MCP

-## Setup Options
+This guide helps you connect n8n-MCP to Claude Desktop, giving Claude comprehensive knowledge about n8n's 450+ workflow automation nodes.

-You can set up n8n-MCP with Claude Desktop in three ways:
+## 🎯 Prerequisites

-### Option 1: Docker (Recommended) 🐳
+- Claude Desktop installed
+- For remote connections: Node.js 18+ on your local machine
+- For Docker: Docker Desktop or Docker Engine

-The easiest way to get started is using Docker:
+## 🛠️ Configuration Methods

-#### 1a. Docker with HTTP Mode (Remote Access)
-```json
-{
-  "mcpServers": {
-    "n8n-remote": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/mcp-remote@latest",
-        "connect",
-        "http://localhost:3000/mcp"
-      ],
-      "env": {
-        "MCP_AUTH_TOKEN": "your-auth-token-here"
-      }
-    }
-  }
-}
-```
+### Method 1: Docker (Simplest) 🐳

-**Setup steps:**
-1. Create a `.env` file:
-   ```bash
-   cat > .env << EOF
-   AUTH_TOKEN=$(openssl rand -base64 32)
-   USE_FIXED_HTTP=true
-   EOF
-   ```
-2. Start the server:
-   ```bash
-   docker compose up -d
-   ```
-3. Copy the AUTH_TOKEN to your Claude config
+No installation needed - runs directly from Docker:

-#### 1b. Docker with stdio Mode (Direct)
 ```json
 {
  "mcpServers": {
    "n8n-docker": {
      "command": "docker",
      "args": [
-        "run",
-        "--rm",
-        "-i",
+        "run", "--rm", "-i",
        "-e", "MCP_MODE=stdio",
        "-v", "n8n-mcp-data:/app/data",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
@@ -61,25 +30,26 @@ The easiest way to get started is using Docker:
 }
 ```

-### Option 2: Local Installation
+✨ **Benefits**: No setup required, always up-to-date, isolated environment.

-1. **Build the project first:**
+### Method 2: Local Installation
+
+1. **Install and build:**
   ```bash
-   cd /path/to/n8n-mcp
+   git clone https://github.com/czlonkowski/n8n-mcp.git
+   cd n8n-mcp
   npm install
   npm run build
   npm run rebuild
   ```

-2. **Add to Claude Desktop config:**
+2. **Configure Claude Desktop:**
   ```json
   {
     "mcpServers": {
       "n8n-documentation": {
         "command": "node",
-         "args": [
-           "/path/to/n8n-mcp/dist/mcp/index.js"
-         ],
+         "args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"],
         "env": {
           "NODE_ENV": "production"
         }
@@ -88,119 +58,117 @@ The easiest way to get started is using Docker:
   }
   ```

-### Option 3: NPM Global Install (Coming Soon)
+⚠️ **Important**: Use absolute paths, not relative paths.
+
+### Method 3: Remote Server Connection
+
+**Requirements**: Node.js 18+ installed locally

 ```json
 {
  "mcpServers": {
-    "n8n-documentation": {
+    "n8n-remote": {
      "command": "npx",
      "args": [
        "-y",
-        "n8n-mcp@latest"
-      ]
+        "mcp-remote",
+        "https://your-server.com/mcp",
+        "--header",
+        "Authorization: Bearer ${AUTH_TOKEN}"
+      ],
+      "env": {
+        "AUTH_TOKEN": "your-auth-token"
+      }
    }
  }
 }
 ```

-## Configuration File Locations
+📝 **Note**: Remote MCP is also natively supported in Claude Pro/Team/Enterprise via Settings > Integrations.
+
+## 📁 Configuration File Locations
+
+Find your `claude_desktop_config.json` file:

 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 - **Linux**: `~/.config/Claude/claude_desktop_config.json`

-After updating the config, **restart Claude Desktop** to load the new configuration.
+🔄 **Important**: After editing, restart Claude Desktop (Cmd/Ctrl+R or quit and reopen).

-## Available Tools
+## ✅ Verify Installation

-Once configured, you'll have access to these tools in Claude:
+After restarting Claude Desktop:

- **`list_nodes`** - List and filter n8n nodes
-  ```
-  list_nodes({ package: "n8n-nodes-base", limit: 10 })
+1. Look for "n8n-docker" or "n8n-documentation" in the MCP servers list
+2. Try asking Claude: "What n8n nodes are available for working with Slack?"
+3. Or use a tool directly: "Use the list_nodes tool to show me trigger nodes"
+
+## 🔧 Available Tools
+
+Once connected, you can ask Claude to:
+
+- **List nodes**: "Show me all n8n nodes for working with databases"
+- **Get node details**: "How do I use the HTTP Request node?"
+- **Search documentation**: "Find n8n nodes that support OAuth"
+- **Find AI tools**: "What AI-capable nodes are available?"
+- **View statistics**: "Show me n8n-MCP database statistics"
+
+Claude will automatically use the appropriate tools:
+- `list_nodes` - Filter and list nodes
+- `get_node_info` - Get detailed node information
+- `search_nodes` - Full-text search
+- `list_ai_tools` - Find AI-capable nodes
+- `get_node_documentation` - Get official docs
+- `get_database_statistics` - View coverage metrics
+
+## 🔍 Troubleshooting
+
+### Server Not Appearing in Claude
+
+1. **Check JSON syntax**: 
+   ```bash
+   # Validate your config file
+   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .
+   ```
+
+2. **Verify paths are absolute** (not relative)
+
+3. **Restart Claude Desktop completely** (quit and reopen)
+
+### Remote Connection Issues
+
+**"TransformStream is not defined" error:**
+- Cause: Node.js version < 18
+- Fix: Update Node.js to v18 or newer
+  ```bash
+  node --version  # Should be v18.0.0 or higher
  ```

- **`get_node_info`** - Get detailed information about a specific node
-  ```
-  get_node_info({ nodeType: "httpRequest" })
-  ```
-
- **`search_nodes`** - Search across all node documentation
-  ```
-  search_nodes({ query: "webhook", limit: 20 })
-  ```
-
- **`list_ai_tools`** - List nodes that can be used as AI Agent tools
-  ```
-  list_ai_tools({})
-  ```
-
- **`get_node_documentation`** - Get full documentation for a node
-  ```
-  get_node_documentation({ nodeType: "slack" })
-  ```
-
- **`get_database_statistics`** - Get statistics about the node database
-  ```
-  get_database_statistics({})
-  ```
-
-## Troubleshooting
+**"Server disconnected" error:**
+- Check AUTH_TOKEN matches between server and client
+- Verify server is running: `curl https://your-server.com/health`
+- Check for VPN interference

 ### Docker Issues

-1. **Container fails to start:**
-   ```bash
-   # Check logs
-   docker compose logs -f
-   
-   # Check if port is in use
-   lsof -i :3000
-   ```
+**"Cannot find image" error:**
+```bash
+# Pull the latest image
+docker pull ghcr.io/czlonkowski/n8n-mcp:latest
+```

-2. **Authentication errors:**
-   - Ensure AUTH_TOKEN matches in .env and Claude config
-   - Token should be at least 32 characters
-   - Check quotes in JSON config
+**Permission denied:**
+```bash
+# Ensure Docker is running
+docker ps
+```

-3. **Database not found:**
-   - The container will auto-initialize on first run
-   - To rebuild: `docker compose exec n8n-mcp npm run rebuild`
+### Quick Fixes

-### Local Installation Issues
+- 🔄 **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

-1. **If the server doesn't appear in Claude:**
-   - Check that the path in `args` is absolute and correct
-   - Ensure you've run `npm run build` and `npm run rebuild`
-   - Verify Node.js version compatibility
-
-2. **If tools return errors:**
-   - Ensure the database exists: `data/nodes.db`
-   - Run `npm run validate` to check the database
-   - Rebuild if necessary: `npm run rebuild`
-
-3. **For development/testing:**
-   ```json
-   {
-     "mcpServers": {
-       "n8n-documentation": {
-         "command": "node",
-         "args": [
-           "/path/to/your/n8n-mcp/dist/mcp/index.js"
-         ],
-         "env": {
-           "NODE_ENV": "development",
-           "LOG_LEVEL": "debug"
-         }
-       }
-     }
-   }
-   ```
-
-### Common Solutions
-
- **Restart Claude Desktop** after config changes
- **Check file permissions** on Unix systems
- **Use absolute paths** in configuration
- **Verify JSON syntax** in claude_desktop_config.json
+For more help, see [Troubleshooting Guide](./TROUBLESHOOTING.md)