n8n-mcp/docs/README_CLAUDE_SETUP.md

Claude Desktop Configuration for n8n-MCP

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 local installation: Node.js (any version)
• For Docker: Docker Desktop or Docker Engine

🛠️ Configuration Methods

Method 1: Local Installation (Recommended) 💻

1. Install and build:

   git clone https://github.com/czlonkowski/n8n-mcp.git
   cd n8n-mcp
   npm install
   npm run build
   npm run rebuild
   

2. Configure Claude Desktop:

   {
     "mcpServers": {
       "n8n-mcp": {
         "command": "node",
         "args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"],
         "env": {
           "NODE_ENV": "production",
           "LOG_LEVEL": "error",
           "MCP_MODE": "stdio",
           "DISABLE_CONSOLE_OUTPUT": "true"
         }
       }
     }
   }
   

⚠️ Important:

• Use absolute paths, not relative paths
• The environment variables shown above are critical for proper stdio communication

Method 2: Docker 🐳

No installation needed - runs directly from Docker:

{
  "mcpServers": {
    "n8n-docker": {
      "command": "docker",
      "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"
      ]
    }
  }
}

✨ 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)

2. Connect using custom HTTP client:

   {
     "mcpServers": {
       "n8n-remote": {
         "command": "node",
         "args": [
           "/path/to/n8n-mcp/scripts/mcp-http-client.js",
           "http://your-server.com:3000/mcp"
         ],
         "env": {
           "MCP_AUTH_TOKEN": "your-auth-token"
         }
       }
     }
   }
   

📝 Note: Native remote MCP support is available 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

🔄 Important: After editing, restart Claude Desktop (Cmd/Ctrl+R or quit and reopen).

✅ Verify Installation

After restarting Claude Desktop:

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:

   # 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

  node --version  # Should be v18.0.0 or higher
  

"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

"Cannot find image" error:

# Pull the latest image
docker pull ghcr.io/czlonkowski/n8n-mcp:latest

Permission denied:

# Ensure Docker is running
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