mdlmarkham/HL_n8n

n8n with n8n-MCP Integration

This setup provides n8n with integrated MCP (Model Context Protocol) support for AI assistants like Claude.

Services

• PostgreSQL: Database backend for n8n
• n8n: Workflow automation platform
• n8n-mcp: MCP server providing AI assistants with n8n integration capabilities

Quick Start

Option 1: Komodo Deployment (Recommended for Homelab)

For detailed Komodo deployment instructions, see .

Quick Steps:

1. Push this repo to your Git provider
2. Create a new Stack in Komodo pointing to your repository
3. Set environment variables in Komodo (use .env.example as reference)
4. Deploy and follow post-deployment configuration steps

Option 2: Direct Docker Compose

1. Environment Setup

First, configure your environment variables in .env:

# Update these values in .env file:
POSTGRES_USER=your_postgres_admin_user
POSTGRES_PASSWORD=your_secure_postgres_password
POSTGRES_DB=your_database_name
POSTGRES_NON_ROOT_USER=your_n8n_user
POSTGRES_NON_ROOT_PASSWORD=your_n8n_user_password
N8N_API_KEY=your_n8n_api_key_here

2. Generate n8n API Key

1. Start the services: docker compose up -d
2. Access n8n at http://localhost:5678
3. Complete the initial setup
4. Go to Settings → API Keys
5. Create a new API key
6. Update the N8N_API_KEY in your .env file

3. Start All Services

docker compose up -d

4. Verify n8n-MCP Integration

Check the health endpoint:

curl http://localhost:3000/health

Service URLs

• n8n: http://localhost:5678
• n8n-MCP: http://localhost:3000
• n8n-MCP Health Check: http://localhost:3000/health

n8n-MCP Features

The n8n-MCP integration provides AI assistants with:

Documentation Tools (Always Available)

• get_node_info: Get detailed information about any n8n node
• search_nodes: Search for nodes by functionality
• validate_node_operation: Validate node configurations
• get_workflow_examples: Find example workflows

Workflow Management Tools (Requires N8N_API_KEY)

• create_workflow: Create new n8n workflows
• update_workflow: Modify existing workflows
• execute_workflow: Run workflows
• get_workflow: Retrieve workflow details
• list_workflows: Browse all workflows
• delete_workflow: Remove workflows
• And 10+ additional management tools

Claude Desktop Integration

To use with Claude Desktop, add this configuration to your Claude config file:

Basic Configuration (Documentation Only)

{
  "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"
      ]
    }
  }
}

Full Configuration (Documentation + Workflow Management)

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true", 
        "-e", "N8N_API_URL=http://host.docker.internal:5678",
        "-e", "N8N_API_KEY=YOUR_N8N_API_KEY_HERE",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

HTTP Mode Configuration (Alternative)

{
  "mcpServers": {
    "n8n-remote": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/mcp-remote@latest",
        "connect", 
        "http://localhost:3000/mcp"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "YfmS1qI0wwxe+tN2JLObmxACjOG0NrZRVbV2aMzpt/g="
      }
    }
  }
}

Management Commands

# Start services
docker compose up -d

# View logs
docker compose logs -f

# Stop services  
docker compose stop

# Update services
docker compose pull
docker compose up -d

# Remove everything (including volumes)
docker compose down -v

Troubleshooting

n8n-MCP Health Check Fails

1. Check if the service is running: docker compose ps
2. Check logs: docker compose logs n8n-mcp
3. Verify the AUTH_TOKEN is correctly set

Cannot Connect to n8n API

1. Ensure n8n is accessible at http://localhost:5678
2. Verify your N8N_API_KEY is correct
3. Check n8n API key permissions in n8n settings

Database Connection Issues

1. Check PostgreSQL logs: docker compose logs postgres
2. Verify database credentials in .env file
3. Ensure the init-data.sh script executed successfully

Security Notes

• The generated N8N_MCP_AUTH_TOKEN is used to secure the MCP HTTP endpoint
• Keep your N8N_API_KEY secure and rotate it regularly
• The n8n-mcp service is configured with health checks and proper resource limits
• Database credentials should be changed from defaults in production

Data Persistence

• Database data: db_storage volume
• n8n data: n8n_storage volume
• n8n-MCP data: n8n_mcp_storage volume

All volumes are automatically managed by Docker Compose.