ContextQMD
Back to N8n Mcp

Claude Desktop Configuration for n8n-MCP

docs/README_CLAUDE_SETUP.md

2.50.47.0 KB
Original Source

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, including 263 AI-capable tools.

šŸŽÆ Prerequisites

  • Claude Desktop installed
  • For local installation: Node.js (any version)
  • For Docker: Docker installed (see installation instructions in main README)

šŸ› ļø Configuration Methods

Method 1: Local Installation (Recommended) šŸ’»

  1. Install and build:

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

  2. Configure Claude Desktop:

    json
    {
  "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:

json
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "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:

    json
    {
  "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 (v2.5.1)

Essential Tool - Start Here!

  • tools_documentation - Get documentation for any MCP tool (ALWAYS use this first!)

Core Tools

  • list_nodes - List all n8n nodes with filtering options
  • get_node_info - Get comprehensive information (now includes aiToolCapabilities)
  • get_node_essentials - Get only 10-20 essential properties (95% smaller!)
  • search_nodes - Full-text search across all node documentation
  • search_node_properties - Find specific properties within nodes
  • get_node_documentation - Get parsed documentation from n8n-docs
  • get_database_statistics - View database metrics and coverage

AI Tools (Enhanced in v2.5.1)

  • list_ai_tools - List AI-capable nodes (ANY node can be used as AI tool!)
  • get_node_as_tool_info - Get guidance on using any node as an AI tool

Task & Template Tools

  • get_node_for_task - Pre-configured node settings for common tasks
  • list_tasks - Discover available task templates
  • list_node_templates - Find workflow templates using specific nodes
  • get_template - Get complete workflow JSON for import
  • search_templates - Search templates by keywords
  • get_templates_for_task - Get curated templates for common tasks

Validation Tools (Professional Grade)

  • validate_node_operation - Smart validation with operation awareness
  • validate_node_minimal - Quick validation for just required fields
  • validate_workflow - Complete workflow validation (validates AI tool connections)
  • validate_workflow_connections - Check workflow structure
  • validate_workflow_expressions - Validate n8n expressions including $fromAI()
  • get_property_dependencies - Analyze property visibility conditions

Example Questions to Ask Claude:

  • "Show me all n8n nodes for working with databases"
  • "How do I use the HTTP Request node?"
  • "Get the essentials for Slack node" (uses get_node_essentials)
  • "How can I use Google Sheets as an AI tool?"
  • "Validate my workflow before deployment"
  • "Find templates for webhook automation"

šŸ” 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

"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:

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

Permission denied:

bash
# 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