n8n-mcp/DOCKER_README.md

Docker Deployment Guide for n8n-MCP

This guide provides comprehensive instructions for deploying n8n-MCP using Docker.

Table of Contents

• Quick Start
• Configuration
• Deployment Options
• Development Setup
• Production Deployment
• Troubleshooting

Quick Start

Using Pre-built Images

The fastest way to get started is using our pre-built Docker images from GitHub Container Registry:

# 1. Create a .env file with your authentication token
echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env

# 2. Start the container
docker compose up -d

# 3. Check it's running
docker compose ps
docker compose logs

Building Locally

To build the image yourself:

# Build the image
docker build -t n8n-mcp:local .

# Run with docker compose (update image in docker-compose.yml first)
docker compose up -d

Configuration

Environment Variables

Create a .env file in the project root:

# Required for HTTP mode
AUTH_TOKEN=your-secure-token-here

# Server configuration
PORT=3000
NODE_ENV=production
LOG_LEVEL=info

# MCP mode (stdio or http)
MCP_MODE=http

# Database
NODE_DB_PATH=/app/data/nodes.db
REBUILD_ON_START=false

Docker Compose Options

The project includes several Docker Compose configurations:

• docker-compose.yml - Production HTTP server
• docker-compose.override.yml.example - Development overrides template
• docker-compose.nginx.yml - HTTPS with nginx (Phase 2)

Deployment Options

Option 1: HTTP Server Mode

Best for remote access and integration with Claude Desktop via mcp-remote:

# Start the server
docker compose up -d

# Test the health endpoint
curl http://localhost:3000/health

# Test with authentication
curl -H "Authorization: Bearer $AUTH_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
     http://localhost:3000/mcp

Configure Claude Desktop:

{
  "mcpServers": {
    "n8n-remote": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/mcp-remote@latest",
        "connect",
        "http://localhost:3000/mcp"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "your-auth-token-here"
      }
    }
  }
}

Option 2: stdio Mode (Direct)

For local-only usage without network exposure:

{
  "mcpServers": {
    "n8n-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "MCP_MODE=stdio",
        "-v", "n8n-mcp-data:/app/data",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

Option 3: HTTPS with nginx (Coming Soon)

For production deployments with SSL/TLS:

# Use the nginx-enhanced compose file
docker compose -f docker-compose.nginx.yml up -d

Development Setup

Local Development with Docker

1. Copy the override template:

cp docker-compose.override.yml.example docker-compose.override.yml

2. Customize for your needs:

# docker-compose.override.yml
version: '3.8'

services:
  n8n-mcp:
    build: .  # Build locally instead of using pre-built
    environment:
      NODE_ENV: development
      LOG_LEVEL: debug
      REBUILD_ON_START: "true"
    volumes:
      # Mount source for development
      - ./src:/app/src:ro
      - ./scripts:/app/scripts:ro
      - ./dist:/app/dist:rw

3. Start in development mode:

docker compose up --build

Testing Docker Builds

Run the test script to validate your Docker setup:

./scripts/test-docker.sh

This script will:

• Build the Docker image
• Test stdio mode functionality
• Test HTTP mode with authentication
• Verify volume persistence
• Check health endpoints

Production Deployment

Security Considerations

1. Authentication: Always set a strong AUTH_TOKEN:

   openssl rand -base64 32
   

2. Network Security: Consider using a reverse proxy (nginx, Traefik) for:

   • SSL/TLS termination
   • Rate limiting
   • Access control

3. Resource Limits: The compose file includes memory limits:

   deploy:
     resources:
       limits:
         memory: 512M
       reservations:
         memory: 256M
   

Deployment Checklist

• Generate secure AUTH_TOKEN
• Configure environment variables
• Set up volume backups for /app/data
• Configure monitoring/logging
• Set up SSL/TLS (if exposing publicly)
• Test health endpoints
• Verify Claude Desktop connectivity

Multi-Architecture Support

The images support both amd64 and arm64 architectures:

# The correct architecture is automatically selected
docker pull ghcr.io/czlonkowski/n8n-mcp:latest

Troubleshooting

Common Issues

Container fails to start

# Check logs
docker compose logs -f

# Verify environment variables
docker compose config

# Check file permissions
docker compose exec n8n-mcp ls -la /app/data

Database initialization fails

# Manually initialize
docker compose exec n8n-mcp node dist/scripts/rebuild.js

# Check database file
docker compose exec n8n-mcp ls -la /app/data/nodes.db

Authentication errors

# Verify token is set
echo $AUTH_TOKEN

# Test with curl
curl -v -H "Authorization: Bearer $AUTH_TOKEN" http://localhost:3000/health

Debug Mode

Enable debug logging:

LOG_LEVEL=debug docker compose up

Volume Management

# List volumes
docker volume ls | grep n8n-mcp

# Inspect volume
docker volume inspect n8n-mcp-data

# Remove volume (WARNING: deletes data)
docker compose down -v

Advanced Configuration

Custom Certificates (Phase 2)

For the nginx-enhanced version:

volumes:
  - ./certs/server.crt:/app/certs/server.crt:ro
  - ./certs/server.key:/app/certs/server.key:ro

Database Persistence

The SQLite database is stored in a named volume for persistence:

volumes:
  n8n-mcp-data:
    driver: local

To backup:

docker run --rm -v n8n-mcp-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/n8n-mcp-backup.tar.gz -C /data .

Next Steps

• Check GitHub Releases for updates
• Report issues at GitHub Issues
• Join discussions in GitHub Discussions

License

This project uses the Sustainable Use License. See LICENSE for details.