Claude Desktop Integration¶

This guide explains how to integrate the n8n MCP Workflow Builder with Claude Desktop, enabling you to manage n8n workflows through natural language conversations.

Prerequisites¶

Before integrating with Claude Desktop, ensure you have:

Claude Desktop installed (version 0.7.0 or later)
n8n MCP Workflow Builder installed via NPM or manual build
n8n instance running and accessible
n8n API key generated
Configuration completed (Configuration Guide)

Not Installed Yet?

Download Claude Desktop: https://claude.ai/download
Install MCP server: See Installation Guide

Understanding Claude Desktop MCP Configuration¶

Claude Desktop connects to MCP servers through a configuration file that specifies:

Server Name - Identifier for your MCP server
Command - How to start the MCP server process
Arguments - Command-line arguments for the server
Environment Variables - Configuration for the server
Permissions - Tools that can run without user approval

Locating the Configuration File¶

The Claude Desktop configuration file location varies by operating system:

macOSWindowsLinux

Path:

~/Library/Application Support/Claude/claude_desktop_config.json

Check if file exists:

ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json

Create parent directory if needed:

mkdir -p ~/Library/Application\ Support/Claude

Path:

%APPDATA%\Claude\claude_desktop_config.json

Check if file exists (PowerShell):

Test-Path "$env:APPDATA\Claude\claude_desktop_config.json"

Check if file exists (Command Prompt):

dir "%APPDATA%\Claude\claude_desktop_config.json"

Create parent directory if needed (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:APPDATA\Claude"

Path:

~/.config/Claude/claude_desktop_config.json

Check if file exists:

ls -la ~/.config/Claude/claude_desktop_config.json

Create parent directory if needed:

mkdir -p ~/.config/Claude

Backup Existing Configuration

If the file already exists, create a backup before editing:

# macOS/Linux
cp ~/Library/Application\ Support/Claude/claude_desktop_config.json \
   ~/Library/Application\ Support/Claude/claude_desktop_config.json.backup

# Windows (PowerShell)
Copy-Item "$env:APPDATA\Claude\claude_desktop_config.json" `
          "$env:APPDATA\Claude\claude_desktop_config.json.backup"

Configuration Methods¶

Choose the method that matches your installation:

Method 1: NPX (Recommended)¶

Best for users who installed via npm without global installation.

Configuration:

macOS/LinuxWindows

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": [
        "@kernel.salacoste/n8n-workflow-builder"
      ],
      "env": {
        "N8N_HOST": "https://your-instance.app.n8n.cloud",
        "N8N_API_KEY": "your_api_key_here",
        "MCP_PORT": "58921"
      },
      "alwaysAllow": [
        "list_workflows",
        "get_workflow",
        "list_executions",
        "get_execution"
      ]
    }
  }
}

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": [
        "@kernel.salacoste/n8n-workflow-builder"
      ],
      "env": {
        "N8N_HOST": "https://your-instance.app.n8n.cloud",
        "N8N_API_KEY": "your_api_key_here",
        "MCP_PORT": "58921"
      },
      "alwaysAllow": [
        "list_workflows",
        "get_workflow",
        "list_executions",
        "get_execution"
      ]
    }
  }
}

Pros: - ✅ Always uses latest published version - ✅ No path configuration needed - ✅ Works across all platforms

Cons: - ⚠️ Slower first start (downloads package) - ⚠️ Requires internet connection

Method 2: Local Build¶

Best for developers or users who built from source.

Configuration:

macOSWindowsLinux

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "node",
      "args": [
        "/Users/username/projects/mcp-n8n-workflow-builder/build/index.js"
      ],
      "env": {
        "N8N_HOST": "https://your-instance.app.n8n.cloud",
        "N8N_API_KEY": "your_api_key_here",
        "MCP_PORT": "58921"
      }
    }
  }
}

Find your absolute path:

cd /path/to/mcp-n8n-workflow-builder
echo "$(pwd)/build/index.js"

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "node",
      "args": [
        "C:\\Users\\username\\projects\\mcp-n8n-workflow-builder\\build\\index.js"
      ],
      "env": {
        "N8N_HOST": "https://your-instance.app.n8n.cloud",
        "N8N_API_KEY": "your_api_key_here",
        "MCP_PORT": "58921"
      }
    }
  }
}

Find your absolute path (PowerShell):

cd C:\path\to\mcp-n8n-workflow-builder
$pwd = Get-Location
Write-Output "$pwd\build\index.js"

Important: Use double backslashes (\\) in JSON!

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "node",
      "args": [
        "/home/username/projects/mcp-n8n-workflow-builder/build/index.js"
      ],
      "env": {
        "N8N_HOST": "https://your-instance.app.n8n.cloud",
        "N8N_API_KEY": "your_api_key_here",
        "MCP_PORT": "58921"
      }
    }
  }
}

Find your absolute path:

cd /path/to/mcp-n8n-workflow-builder
echo "$(pwd)/build/index.js"

Pros: - ✅ Fast startup (no download) - ✅ Use custom modifications - ✅ Offline operation

Cons: - ⚠️ Manual updates required - ⚠️ Must rebuild after changes

Use Absolute Paths Only

Never use relative paths like ./build/index.js or ~/projects/...

Claude Desktop requires absolute paths starting from root: - ✅ Correct: /Users/john/projects/mcp-n8n-workflow-builder/build/index.js - ❌ Wrong: ~/projects/mcp-n8n-workflow-builder/build/index.js - ❌ Wrong: ./build/index.js

Method 3: Global NPM Installation¶

Best for users who installed globally with npm install -g.

Configuration:

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "n8n-workflow-builder",
      "env": {
        "N8N_HOST": "https://your-instance.app.n8n.cloud",
        "N8N_API_KEY": "your_api_key_here",
        "MCP_PORT": "58921"
      },
      "alwaysAllow": [
        "list_workflows",
        "get_workflow"
      ]
    }
  }
}

Verify global installation:

which n8n-workflow-builder
# Should output: /usr/local/bin/n8n-workflow-builder (or similar)

Pros: - ✅ Simplest configuration - ✅ Fast startup - ✅ No path needed

Cons: - ⚠️ Requires global install permissions - ⚠️ May conflict with other versions

Configuration Reference¶

Environment Variables¶

Variable	Required	Description	Example
`N8N_HOST`	✅ Yes	n8n base URL (without `/api/v1`)	`https://n8n.example.com`
`N8N_API_KEY`	✅ Yes	n8n API key	`n8n_api_abc123...`
`MCP_PORT`	⬜ No	MCP server port (default: 3456)	`58921`
`DEBUG`	⬜ No	Enable debug logging	`true` or `false`

Port Selection

Use non-standard ports like 58921 to avoid conflicts with default MCP port 3456.

Always Allow Tools¶

The alwaysAllow array specifies tools that can run without asking for permission:

Read-Only Tools (Safe):

"alwaysAllow": [
  "list_workflows",
  "get_workflow",
  "list_executions",
  "get_execution",
  "get_tags"
]

Write Tools (Require Caution):

"alwaysAllow": [
  "create_workflow",
  "update_workflow",
  "delete_workflow",
  "activate_workflow",
  "deactivate_workflow"
]

Security Consideration

Only add write tools to alwaysAllow if you trust the AI to make changes without confirmation.

Recommended for most users: Only allow read-only tools.

Multi-Instance Configuration¶

If using .config.json with multiple n8n environments, Claude Desktop will use the default environment:

Option 1: Use .config.json file

Create .config.json in your project directory and reference it:

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@kernel.salacoste/n8n-workflow-builder"],
      "cwd": "/path/to/project/with/config.json"
    }
  }
}

Option 2: Override environment in Claude Desktop

{
  "mcpServers": {
    "n8n-production": {
      "command": "npx",
      "args": ["@kernel.salacoste/n8n-workflow-builder"],
      "env": {
        "N8N_HOST": "https://prod.n8n.example.com",
        "N8N_API_KEY": "prod_key"
      }
    },
    "n8n-staging": {
      "command": "npx",
      "args": ["@kernel.salacoste/n8n-workflow-builder"],
      "env": {
        "N8N_HOST": "https://staging.n8n.example.com",
        "N8N_API_KEY": "staging_key"
      }
    }
  }
}

This creates two separate MCP servers - one for production, one for staging.

Applying Configuration¶

Step 1: Edit Configuration File¶

macOS/LinuxWindows

# Open in default text editor
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Or use nano
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Or use VS Code
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Open in Notepad
notepad "$env:APPDATA\Claude\claude_desktop_config.json"

# Or use VS Code
code "$env:APPDATA\Claude\claude_desktop_config.json"

Step 2: Paste Configuration¶

Copy your chosen configuration method and paste it into the file.

If file is empty or new: Paste the complete JSON structure.

If file already has other MCP servers: Add your server to the existing mcpServers object:

{
  "mcpServers": {
    "existing-server": {
      "command": "...",
      ...
    },
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@kernel.salacoste/n8n-workflow-builder"],
      ...
    }
  }
}

Step 3: Save and Validate¶

Save the file (Ctrl+S or Cmd+S)

Validate JSON syntax:

# macOS/Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

# Windows (PowerShell)
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | ConvertFrom-Json

If you see errors, check for: - Missing commas between properties - Missing quotes around strings - Unclosed brackets or braces

Verification and Testing¶

Step 1: Restart Claude Desktop¶

Complete restart required:

Quit Claude Desktop completely (not just close window)
macOS: Cmd+Q
Windows: File → Exit
Linux: File → Quit
Wait 5 seconds
Relaunch Claude Desktop

Step 2: Verify MCP Server Connection¶

Open a new conversation in Claude and send:

What MCP tools do you have available?

Expected Response:

Claude should list the n8n MCP Workflow Builder tools:

I have access to the following n8n workflow management tools:

Workflow Management:
- list_workflows - List all workflows
- create_workflow - Create new workflows
- get_workflow - Get workflow details
- update_workflow - Update existing workflows
- delete_workflow - Remove workflows
- activate_workflow - Enable workflows
- deactivate_workflow - Disable workflows
- execute_workflow - Run workflows manually

Execution Management:
- list_executions - List workflow executions
- get_execution - Get execution details
- delete_execution - Remove execution records
- retry_execution - Retry failed executions

Tag Management:
- create_tag - Create workflow tags
- get_tags - List all tags
- update_tag - Update tag names
- delete_tag - Remove tags

Would you like me to help with any of these operations?

Step 3: Test Basic Functionality¶

Try a simple read-only command:

List my n8n workflows

Expected Response:

Claude should invoke the list_workflows tool and display your workflows:

Here are your n8n workflows:

1. **Email Notification System** (ID: 1)
   - Status: Active
   - Created: 2025-12-15
   - Nodes: 5

2. **Data Sync Pipeline** (ID: 2)
   - Status: Inactive
   - Created: 2025-12-20
   - Nodes: 8

You have 2 workflows total.

Troubleshooting¶

Issue 1: MCP Server Not Found¶

Symptom:

Claude responds: "I don't have access to n8n workflow tools"

Solutions:

Verify configuration file location:

# Check file exists
ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json

Check JSON syntax:

python3 -m json.tool < ~/Library/Application\ Support/Claude/claude_desktop_config.json

Verify npx or node is in PATH:

which npx    # Should show path
which node   # Should show path

Restart Claude Desktop completely (Quit + Relaunch)

Issue 2: Connection Failed¶

Symptom:

Claude shows error: "Failed to connect to MCP server"

Solutions:

Test MCP server manually:

npx @kernel.salacoste/n8n-workflow-builder
# Should start without errors

Check n8n is accessible:
```
curl https://your-n8n-instance.com
```
Verify API key is correct:
Check for whitespace in configuration
Regenerate API key in n8n if needed
Check logs:
macOS: ~/Library/Logs/Claude/
Windows: %APPDATA%\Claude\Logs\

Issue 3: Permission Denied¶

Symptom:

Error: "EACCES: permission denied"

Solutions:

Check file permissions:

ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Should be readable

Fix permissions:

chmod 644 ~/Library/Application\ Support/Claude/claude_desktop_config.json

For local build, check build directory:

ls -la /path/to/mcp-n8n-workflow-builder/build/index.js

Issue 4: Wrong Tools Appear¶

Symptom:

Different MCP tools appear (not n8n tools)

Solutions:

Check server name in config:
Must be unique across all MCP servers
Try renaming to n8n-mcp or n8n-prod
Verify command matches your installation method
Remove old configurations if you changed installation methods

Using MCP Tools in Claude¶

Discovering Tools¶

Ask Claude about available tools:

What n8n tools can you use?
What can you do with my workflows?
Show me the available workflow commands

Invoking Tools¶

Use natural language commands:

List Operations:

List my workflows
Show all workflow executions
Get all tags

Get Operations:

Get details for workflow ID 5
Show me execution 123

Create Operations:

Create a new workflow called "Daily Backup"
Add a tag called "production"

Update Operations:

Activate workflow 3
Rename tag "test" to "staging"

Delete Operations:

Delete workflow 7
Remove tag "obsolete"

Best Practices¶

Start with read operations to understand your current state
Be specific with IDs and names
Ask for confirmation before destructive operations

Use multi-instance by specifying environment:

List workflows from production
Create workflow in staging instance

Next Steps¶

After successful integration:

First Workflow Tutorial - Create your first workflow with Claude
Verification & Testing - Comprehensive testing guide
Workflow Examples - Explore workflow patterns

Additional Resources¶

MCP Tools Reference - Complete tool documentation
Multi-Instance Guide - Advanced multi-environment setup
Troubleshooting Guide - Common issues and solutions
Claude Desktop MCP Documentation - Official MCP docs

Integration Complete!

You're now ready to manage n8n workflows through natural language conversations with Claude AI! 🎉