A cross-platform demonstration of n8n workflow automation integrated with Model Context Protocol (MCP) using Docker containerization.

This repository contains a complete, production-ready demonstration of integrating n8n (workflow automation platform) with MCP (Model Context Protocol). The entire stack runs in Docker containers, ensuring consistent behavior across Windows and macOS environments.

• ✅ Cross-platform compatibility - Identical behavior on Windows and Mac
• ✅ Containerized deployment - Zero dependency installation required
• ✅ Pre-configured workflow - Ready-to-use n8n-MCP integration example
• ✅ Simulated MCP server - Demonstrates protocol integration patterns
• ✅ Production-ready architecture - Following infrastructure best practices
• ✅ Comprehensive documentation - Setup, troubleshooting, and architecture guides

┌─────────────────────────────────────────────────────────────┐
│                     Docker Network                          │
│                                                             │
│  ┌──────────────┐                    ┌──────────────────┐   │
│  │              │                    │                  │   │
│  │   n8n        │◄──────HTTP────────►│   MCP Server     │   │
│  │   (Port 5678)│                    │   (Port 8080)    │   │
│  │              │                    │                  │   │
│  └──────┬───────┘                    └──────────────────┘   │
│         │                                                   │
│         │                                                   │
└─────────┼───────────────────────────────────────────────────┘
          │
          │ Webhook
          ▼
    External Client
   (curl, Postman, etc.)

1. n8n Container: Workflow automation engine with pre-loaded MCP integration workflow
2. MCP Server Container: FastAPI-based simulation of Model Context Protocol endpoints
3. Docker Network: Private network enabling secure inter-container communication
4. Persistent Volume: Stores n8n data, workflows, and configuration

• Docker Desktop 20.10+ (Windows | Mac)
• Git for cloning the repository
• 8GB RAM minimum (16GB recommended)
• Ports available: 5678 (n8n), 8080 (MCP server)

1. Clone the repository

   git clone https://github.com/yourusername/n8n-mcp-demo.git
   cd n8n-mcp-demo

2. Configure environment

   cp .env.example .env
   # Edit .env to customize credentials (optional)

3. Start the stack

   docker-compose up -d

4. Verify services

   docker-compose ps
   # Both containers should show "Up" status

5. Access n8n and create owner account

   • Open browser to http://localhost:5678
   • On first run, create an owner account with:
     • Email: [email protected]
     • First/Last name: Your Name
     • Password: (choose a secure password)
   • Login with your created credentials

1. Import the workflow

   • In n8n UI, click "Workflows" in left sidebar
   • Click "+" or "Add Workflow"
   • Click "⋮" (three dots) menu → "Import from file"
   • Select workflows/mcp-integration-demo.json from the project directory
   • The workflow will open in the editor

2. Activate the workflow

   • Click "Activate" toggle in top right (should turn green/blue)
   • Workflow is now ready to receive webhook requests

3. Test via Webhook

   curl -X POST http://localhost:5678/webhook/mcp-demo \
     -H "Content-Type: application/json" \
     -d '{
       "query": "What is the current context?",
       "user_id": "demo-user"
     }'

4. Expected Response

   {
     "success": true,
     "context": [
       {
         "source": "knowledge_base",
         "content": "This is simulated context from MCP",
         "relevance": 0.95
       }
     ],
     "action_result": {
       "success": true,
       "message": "Action process_context executed successfully"
     },
     "timestamp": "2025-10-23T..."
   }

The demo workflow demonstrates:

1. Webhook Trigger - Receives HTTP POST requests
2. MCP Context Request - Fetches context from MCP server
3. Context Validation - Checks if valid context was returned
4. Action Execution - Processes context via MCP
5. Response Formatting - Returns structured JSON response

The MCP server is a simple FastAPI application embedded in the docker-compose.yml. To customize:

1. Edit the Python code in docker-compose.yml under mcp-server service
2. Restart the containers: docker-compose restart mcp-server

Supported endpoints:

• GET /health - Health check
• POST /api/context - Retrieve context for a query
• POST /api/execute - Execute an action with parameters

Containers won't start

# Check port conflicts
docker-compose down
lsof -i :5678  # Mac
netstat -an | findstr 5678  # Windows

# Remove conflicting containers
docker-compose down -v
docker-compose up -d

n8n shows "unauthorized"

• Verify credentials in .env file
• Restart containers after changing .env:

  docker-compose restart

MCP server connection fails

# Check MCP server logs
docker logs mcp-server-demo

# Test MCP server directly
curl http://localhost:8080/health

Workflow won't activate

• Ensure both containers are running
• Check n8n logs: docker logs n8n-mcp-demo
• Verify MCP_SERVER_URL uses container name (mcp-server), not localhost

Windows (WSL2)

• Ensure WSL2 is enabled and Docker Desktop uses WSL2 backend
• File paths in docker-compose use Unix-style slashes
• Run commands in PowerShell or WSL2 terminal

macOS

• Docker Desktop must be running before docker-compose up
• For M1/M2 Macs, containers use ARM64 architecture (fully supported)

• n8n container: ~200MB RAM, <5% CPU (idle)
• MCP server: ~100MB RAM, <2% CPU (idle)
• Total disk: ~500MB (including Docker images)

For production use:

1. Replace simulated MCP server with actual MCP implementation
2. Add reverse proxy (Nginx/Traefik) for HTTPS
3. Configure external database (PostgreSQL) for n8n
4. Implement proper secret management (HashiCorp Vault, AWS Secrets Manager)
5. Add monitoring (Prometheus + Grafana)

n8n-mcp-demo/
├── .github/
│   └── workflows/         # CI/CD pipelines (optional)
├── config/                # n8n configuration files
├── docs/
│   ├── ARCHITECTURE.md    # Detailed architecture documentation
│   ├── PRESENTATION.md    # Technical presentation slides
│   └── TROUBLESHOOTING.md # Extended troubleshooting guide
├── workflows/
│   └── mcp-integration-demo.json  # Pre-configured workflow
├── .env.example          # Environment template
├── .gitignore            # Git ignore rules
├── docker-compose.yml    # Docker orchestration config
├── LICENSE               # MIT License
└── README.md            # This file

• ⚠️ Change default credentials before production deployment
• ⚠️ Use HTTPS in production (not HTTP)
• ⚠️ Rotate API keys regularly
• ⚠️ Network isolation - MCP server not exposed to public internet
• ⚠️ Volume permissions - Ensure proper file ownership in Docker volumes

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see LICENSE file for details.

• n8n - Workflow automation platform
• FastAPI - MCP server framework
• Docker - Containerization platform

• Documentation: See /docs folder
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Built with ❤️ for Platform Engineers