Claude Desktop Setup

This guide walks you through connecting Claude Desktop to your n8n MCP Bridge instance.

Prerequisites

Before you begin:

• ✅ Claude Desktop installed (download here)
• ✅ n8n MCP Bridge running (see Installation Guide)
• ✅ MCP API key created (see Create API Key)

Configuration Steps

Step 1: Locate Configuration File

Claude Desktop stores its configuration in different locations by operating system.

macOS:

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

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Step 2: Get Your MCP Configuration

From the n8n MCP Bridge dashboard:

1. Go to http://localhost:3000/dashboard
2. Click the API Keys tab
3. Find your API key
4. Click Show Config or Copy Configuration

You'll get something like:

{
  "mcpServers": {
    "n8n": {
      "url": "http://localhost:3001/mcp?apiKey=mcp_clph1234abcd5678"
    }
  }
}

Step 3: Edit Claude Config

Open the Claude Desktop configuration file:

macOS/Linux:

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

Windows: Use Notepad or your preferred text editor.

If the file doesn't exist, create it with this content:

{
  "mcpServers": {
    "n8n": {
      "url": "http://localhost:3001/mcp?apiKey=mcp_YOUR_API_KEY_HERE"
    }
  }
}

Replace mcp_YOUR_API_KEY_HERE with your actual API key.

Step 4: Restart Claude Desktop

1. Quit Claude Desktop completely

   • macOS: Cmd+Q or Claude → Quit
   • Windows: File → Exit
   • Linux: File → Quit

2. Start Claude Desktop again

3. The MCP server should load automatically

Verification

Check MCP Server Status

In Claude Desktop:

1. Look for an indicator showing MCP servers are loaded
2. Go to Settings → Developer or Settings → Extensions
3. You should see "n8n" listed as a connected MCP server

Test with a Query

Ask Claude to test the connection:

Can you ping my n8n instance?

Expected response:

I'll test your n8n connection using the ping_n8n tool...

✓ Connection successful!
Your n8n instance is responding and the API key is valid.

Configuration Options

Basic Configuration

Minimal setup:

{
  "mcpServers": {
    "n8n": {
      "url": "http://localhost:3001/mcp?apiKey=mcp_your_key"
    }
  }
}

Custom Server Name

Use a descriptive name:

{
  "mcpServers": {
    "my-production-n8n": {
      "url": "http://localhost:3001/mcp?apiKey=mcp_prod_key"
    }
  }
}

Multiple MCP Servers

Connect to multiple n8n instances:

{
  "mcpServers": {
    "n8n-production": {
      "url": "http://localhost:3001/mcp?apiKey=mcp_prod_key"
    },
    "n8n-development": {
      "url": "http://localhost:3002/mcp?apiKey=mcp_dev_key"
    }
  }
}

Remote Server

Connect to a remote n8n MCP Bridge:

{
  "mcpServers": {
    "n8n-remote": {
      "url": "https://mcp.example.com/mcp?apiKey=mcp_your_key"
    }
  }
}

Important: Use HTTPS for remote connections!

Troubleshooting

MCP Server Not Loading

Symptom: Claude doesn't show the MCP server as connected

Solutions:

1. Check JSON syntax:

   # Use a JSON validator
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python -m json.tool

2. Verify file location:

   • Make sure file is in the correct directory
   • Check file name is exactly claude_desktop_config.json

3. Check permissions:

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

4. View Claude logs:

   • macOS: ~/Library/Logs/Claude/
   • Windows: %APPDATA%\Claude\logs\
   • Look for MCP-related errors

Connection Failed

Symptom: MCP server loads but connection fails

Solutions:

1. Verify MCP server is running:

   curl http://localhost:3001/health

   Should return: {"status":"ok"}

2. Test API key:

   • Go to dashboard → API Keys
   • Click "Test Connection"
   • Should show "Connected ✓"

3. Check URL format:

   {
     "url": "http://localhost:3001/mcp?apiKey=mcp_your_key"
   }

   • Must start with http:// or https://
   • Must end with ?apiKey=mcp_...
   • No trailing slashes

4. Firewall settings:

   • Allow Claude to connect to localhost:3001
   • Check macOS firewall settings
   • Check Windows firewall settings

Invalid API Key

Symptom: "Invalid API key" or "Authentication failed"

Solutions:

1. Verify API key:

   • Copy key directly from dashboard
   • Ensure no extra spaces or line breaks
   • Check it starts with mcp_

2. Test in dashboard:

   • Dashboard → API Keys
   • Find your key
   • Click "Test Connection"

3. Regenerate if needed:

   • Delete old API key
   • Create new API key
   • Update Claude config with new key
   • Restart Claude

Tools Not Working

Symptom: Can't use MCP tools or they fail

Solutions:

1. Check tool availability:

   What MCP tools do you have available?

2. Verify n8n connection:

   Can you ping my n8n instance?

3. Check n8n instance:

   • Ensure n8n is running
   • Verify n8n API key is valid
   • Test n8n URL in browser

Advanced Configuration

Environment-Specific Configs

Development:

{
  "mcpServers": {
    "n8n-dev": {
      "url": "http://localhost:3001/mcp?apiKey=mcp_dev_key",
      "name": "Development n8n"
    }
  }
}

Production:

{
  "mcpServers": {
    "n8n-prod": {
      "url": "https://mcp.example.com/mcp?apiKey=mcp_prod_key",
      "name": "Production n8n"
    }
  }
}

Debugging

Enable debug mode:

{
  "mcpServers": {
    "n8n": {
      "url": "http://localhost:3001/mcp?apiKey=mcp_your_key",
      "debug": true
    }
  }
}

This may log additional information in Claude's console.

Security Best Practices

Protect Your Config File

macOS/Linux:

# Set restrictive permissions
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Verify
ls -l ~/Library/Application\ Support/Claude/claude_desktop_config.json

Expected: -rw------- (only you can read/write)

API Key Safety

• ❌ Don't commit config to git
• ❌ Don't share config files
• ❌ Don't post config in screenshots
• ✅ Use environment variables (if supported)
• ✅ Rotate keys regularly
• ✅ Use separate keys per device

Network Security

For remote connections:

• ✅ Always use HTTPS
• ✅ Verify SSL certificates
• ✅ Use VPN for internal servers
• ✅ Monitor API key usage
• ❌ Never use HTTP for production

Example Queries

Once connected, try these queries:

Test Connection

Can you ping my n8n instance?

Get Help

What can you do with my n8n workflows?

Execute Workflow (when available)

Execute my "send-welcome-email" workflow with customerId: "cust_123"

Next Steps

• Set up VS Code Extension →
• Configure Cursor IDE →
• Learn About Memory System →
• View Available Tools →

Updating Configuration

To update your configuration:

1. Edit the config file
2. Save changes
3. Restart Claude Desktop
4. Verify connection

No need to recreate API keys unless you want to rotate them.

Backup Configuration

Save a backup of your config:

macOS/Linux:

cp ~/Library/Application\ Support/Claude/claude_desktop_config.json \
   ~/claude_config_backup.json

Windows:

copy %APPDATA%\Claude\claude_desktop_config.json C:\backup\claude_config.json

Remember to keep backups secure (they contain API keys)!

Getting Help

Still having issues?

• Read Troubleshooting Guide →
• Check GitHub Issues
• View API Reference →