# 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:
- [x] **Claude Desktop installed** (version 0.7.0 or later)
- [x] **n8n MCP Workflow Builder** installed via [NPM](../installation/npm-installation.md) or [manual build](../installation/manual-installation.md)
- [x] **n8n instance** running and accessible
- [x] **n8n API key** generated
- [x] **Configuration** completed ([Configuration Guide](../installation/configuration.md))
!!! tip "Not Installed Yet?"
- Download Claude Desktop: [https://claude.ai/download](https://claude.ai/download)
- Install MCP server: See [Installation Guide](../installation/npm-installation.md)
---
## Understanding Claude Desktop MCP Configuration
Claude Desktop connects to MCP servers through a configuration file that specifies:
1. **Server Name** - Identifier for your MCP server
2. **Command** - How to start the MCP server process
3. **Arguments** - Command-line arguments for the server
4. **Environment Variables** - Configuration for the server
5. **Permissions** - Tools that can run without user approval
---
## Locating the Configuration File
The Claude Desktop configuration file location varies by operating system:
=== "macOS"
**Path:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
**Check if file exists:**
```bash
ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
**Create parent directory if needed:**
```bash
mkdir -p ~/Library/Application\ Support/Claude
```
=== "Windows"
**Path:**
```
%APPDATA%\Claude\claude_desktop_config.json
```
**Check if file exists (PowerShell):**
```powershell
Test-Path "$env:APPDATA\Claude\claude_desktop_config.json"
```
**Check if file exists (Command Prompt):**
```cmd
dir "%APPDATA%\Claude\claude_desktop_config.json"
```
**Create parent directory if needed (PowerShell):**
```powershell
New-Item -ItemType Directory -Force -Path "$env:APPDATA\Claude"
```
=== "Linux"
**Path:**
```
~/.config/Claude/claude_desktop_config.json
```
**Check if file exists:**
```bash
ls -la ~/.config/Claude/claude_desktop_config.json
```
**Create parent directory if needed:**
```bash
mkdir -p ~/.config/Claude
```
!!! warning "Backup Existing Configuration"
If the file already exists, create a backup before editing:
```bash
# 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/Linux"
```json
{
"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"
]
}
}
}
```
=== "Windows"
```json
{
"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:**
=== "macOS"
```json
{
"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:**
```bash
cd /path/to/mcp-n8n-workflow-builder
echo "$(pwd)/build/index.js"
```
=== "Windows"
```json
{
"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):**
```powershell
cd C:\path\to\mcp-n8n-workflow-builder
$pwd = Get-Location
Write-Output "$pwd\build\index.js"
```
**Important:** Use double backslashes (`\\`) in JSON!
=== "Linux"
```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:**
```bash
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
!!! danger "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:**
```json
{
"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:**
```bash
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` |
!!! tip "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):**
```json
"alwaysAllow": [
"list_workflows",
"get_workflow",
"list_executions",
"get_execution",
"get_tags"
]
```
**Write Tools (Require Caution):**
```json
"alwaysAllow": [
"create_workflow",
"update_workflow",
"delete_workflow",
"activate_workflow",
"deactivate_workflow"
]
```
!!! warning "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:
```json
{
"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**
```json
{
"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/Linux"
```bash
# 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
```
=== "Windows"
```powershell
# 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:
```json
{
"mcpServers": {
"existing-server": {
"command": "...",
...
},
"n8n-workflow-builder": {
"command": "npx",
"args": ["@kernel.salacoste/n8n-workflow-builder"],
...
}
}
}
```
### Step 3: Save and Validate
1. **Save the file** (Ctrl+S or Cmd+S)
2. **Validate JSON syntax:**
```bash
# 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:**
1. **Quit Claude Desktop** completely (not just close window)
- macOS: Cmd+Q
- Windows: File → Exit
- Linux: File → Quit
2. **Wait 5 seconds**
3. **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:**
1. **Verify configuration file location:**
```bash
# Check file exists
ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
2. **Check JSON syntax:**
```bash
python3 -m json.tool < ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
3. **Verify npx or node is in PATH:**
```bash
which npx # Should show path
which node # Should show path
```
4. **Restart Claude Desktop completely** (Quit + Relaunch)
---
### Issue 2: Connection Failed
**Symptom:**
Claude shows error: "Failed to connect to MCP server"
**Solutions:**
1. **Test MCP server manually:**
```bash
npx @kernel.salacoste/n8n-workflow-builder
# Should start without errors
```
2. **Check n8n is accessible:**
```bash
curl https://your-n8n-instance.com
```
3. **Verify API key is correct:**
- Check for whitespace in configuration
- Regenerate API key in n8n if needed
4. **Check logs:**
- macOS: `~/Library/Logs/Claude/`
- Windows: `%APPDATA%\Claude\Logs\`
---
### Issue 3: Permission Denied
**Symptom:**
Error: "EACCES: permission denied"
**Solutions:**
1. **Check file permissions:**
```bash
ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Should be readable
```
2. **Fix permissions:**
```bash
chmod 644 ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
3. **For local build, check build directory:**
```bash
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:**
1. **Check server name in config:**
- Must be unique across all MCP servers
- Try renaming to `n8n-mcp` or `n8n-prod`
2. **Verify command matches your installation method**
3. **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
1. **Start with read operations** to understand your current state
2. **Be specific** with IDs and names
3. **Ask for confirmation** before destructive operations
4. **Use multi-instance** by specifying environment:
```
List workflows from production
Create workflow in staging instance
```
---
## Next Steps
After successful integration:
1. **[First Workflow Tutorial](first-workflow.md)** - Create your first workflow with Claude
2. **[Verification & Testing](verification.md)** - Comprehensive testing guide
3. **[Workflow Examples](../../examples/basic/webhook-workflow.md)** - Explore workflow patterns
---
## Additional Resources
- [MCP Tools Reference](../../features/workflows-management.md) - Complete tool documentation
- [Multi-Instance Guide](../../multi-instance/configuration.md) - Advanced multi-environment setup
- [Troubleshooting Guide](../../troubleshooting/error-reference.md) - Common issues and solutions
- [Claude Desktop MCP Documentation](https://docs.anthropic.com/claude/docs/mcp) - Official MCP docs
---
!!! success "Integration Complete!"
You're now ready to manage n8n workflows through natural language conversations with Claude AI! 🎉
