feat(security): add SSL/TLS custom cert support and optional SSL verification skip

- Enhance SSL/TLS configuration with support for custom CA or self-signed certificates via N8N_CERT_PATH.
- Introduce N8N_SKIP_SSL_VERIFICATION environment variable to optionally disable SSL cert verification (for development only).
- Add detailed SSL/TLS troubleshooting guide documentation with common errors, fixes, and best practices.
- Update n8n API client to use custom cert and conditionally disable SSL verification with proper warnings.
- Improve logging to warn about insecure SSL skip usage.

Author: gifflet

.env.example

@@ -215,4 +215,11 @@ ENABLE_MULTI_TENANT=false
 # Test Configuration
 N8N_TEST_CLEANUP_ENABLED=true         # Enable automatic cleanup of test workflows
 N8N_TEST_TAG=mcp-integration-test     # Tag applied to all test workflows
-N8N_TEST_NAME_PREFIX=[MCP-TEST]       # Name prefix for test workflows
+N8N_TEST_NAME_PREFIX=[MCP-TEST]       # Name prefix for test workflows
+
+# Custom SSL certificate for self-signed n8n instances
+# Path to the server's .crt file (absolute or relative)
+# Supports both CA certificates and self-signed server certificates
+# Example: N8N_CERT_PATH=/path/to/n8n-server.crt
+# Docker: Mount certificate and use container path (e.g., /app/certs/n8n.crt)
+# N8N_CERT_PATH=

README.md

@@ -474,6 +474,125 @@ Deploy n8n-MCP to Railway's cloud platform with zero configuration:
 
 **Restart Claude Desktop after updating configuration** - That's it! 🎉
 
+## 🔐 SSL/TLS Configuration
+
+### Using Custom CA Certificates (Recommended)
+
+If your n8n instance uses a custom or self-signed SSL certificate, configure the `N8N_CERT_PATH` environment variable to point to your certificate file (PEM format):
+
+- For self-signed certificates: provide the server's certificate itself
+- For custom CA: provide the CA certificate that signed the server's certificate
+
+This approach maintains full SSL verification while trusting your specific certificate.
+
+### Using with npx
+
+Add the certificate path to your Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "npx",
+      "args": ["n8n-mcp"],
+      "env": {
+        "MCP_MODE": "stdio",
+        "LOG_LEVEL": "error",
+        "DISABLE_CONSOLE_OUTPUT": "true",
+        "N8N_API_URL": "https://your-n8n-instance.com",
+        "N8N_API_KEY": "your-api-key",
+        "N8N_CERT_PATH": "/path/to/your/certificate.crt"
+      }
+    }
+  }
+}
+```
+
+### Using with Docker
+
+Mount your certificate file as a volume and set the environment variable:
+
+```bash
+docker run -i --rm --init \
+  -v /path/to/your/certificate.crt:/app/certs/n8n.crt:ro \
+  -e MCP_MODE=stdio \
+  -e LOG_LEVEL=error \
+  -e DISABLE_CONSOLE_OUTPUT=true \
+  -e N8N_API_URL=https://your-n8n-instance.com \
+  -e N8N_API_KEY=your-api-key \
+  -e N8N_CERT_PATH=/app/certs/n8n.crt \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+```
+
+For Claude Desktop configuration with Docker:
+
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm", "--init",
+        "-v", "/path/to/your/certificate.crt:/app/certs/n8n.crt:ro",
+        "-e", "MCP_MODE=stdio",
+        "-e", "LOG_LEVEL=error",
+        "-e", "DISABLE_CONSOLE_OUTPUT=true",
+        "-e", "N8N_API_URL=https://your-n8n-instance.com",
+        "-e", "N8N_API_KEY=your-api-key",
+        "-e", "N8N_CERT_PATH=/app/certs/n8n.crt",
+        "ghcr.io/czlonkowski/n8n-mcp:latest"
+      ]
+    }
+  }
+}
+```
+
+### Using with docker-compose
+
+See the commented certificate configuration in `docker-compose.yml` and `docker-compose.n8n.yml`. Uncomment the relevant sections and adjust the certificate path.
+
+### Troubleshooting Certificate Issues
+
+Common issues and quick fixes:
+- **UNABLE_TO_VERIFY_LEAF_SIGNATURE** → Missing root certificate in your bundle
+- **SELF_SIGNED_CERT_IN_CHAIN** → Configure certificate as trusted CA or skip verification
+- **ERR_TLS_CERT_ALTNAME_INVALID** → Domain name doesn't match certificate
+
+📚 **For detailed solutions, see our [SSL Troubleshooting Guide](./docs/SSL_TROUBLESHOOTING.md)** which covers:
+- Complete error messages and solutions
+- How to create proper certificate bundles
+- Diagnostic commands and debugging tips
+- Solutions for Let's Encrypt, self-signed, and corporate certificates
+
+### Disabling SSL Verification (Development Only)
+
+⚠️ **WARNING**: This option completely disables SSL certificate verification and should ONLY be used for local development or testing environments.
+
+If you're unable to provide a valid certificate and need to connect to a development server, you can disable SSL verification:
+
+```json
+{
+  "mcpServers": {
+    "n8n-mcp": {
+      "command": "npx",
+      "args": ["n8n-mcp"],
+      "env": {
+        "MCP_MODE": "stdio",
+        "N8N_API_URL": "https://your-n8n-instance.com",
+        "N8N_API_KEY": "your-api-key",
+        "N8N_SKIP_SSL_VERIFICATION": "true"
+      }
+    }
+  }
+}
+```
+
+**Important Security Notes**:
+- Never use `N8N_SKIP_SSL_VERIFICATION` in production environments
+- This disables protection against man-in-the-middle attacks
+- Always prefer providing the correct certificate via `N8N_CERT_PATH`
+- The server will log warnings when SSL verification is disabled
+
 ## 🔧 n8n Integration
 
 Want to use n8n-MCP with your n8n instance? Check out our comprehensive [n8n Deployment Guide](./docs/N8N_DEPLOYMENT.md) for:

docker-compose.n8n.yml

@@ -48,9 +48,18 @@ services:
       - MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN}
       - AUTH_TOKEN=${MCP_AUTH_TOKEN}
       - LOG_LEVEL=${LOG_LEVEL:-info}
+
+      # Optional: Self-signed certificate support
+      # Uncomment if your n8n instance uses a self-signed SSL certificate
+      # Note: Also uncomment the corresponding volume mount below
+      # - N8N_CERT_PATH=/app/certs/n8n.crt
     volumes:
       - ./data:/app/data:ro
       - mcp_logs:/app/logs
+
+      # Optional: Mount certificate file for self-signed n8n instances
+      # Uncomment and adjust the path to your certificate file
+      # - /path/to/your/certificate.crt:/app/certs/n8n.crt:ro
     networks:
       - n8n-network
     depends_on:

docker-compose.yml

@@ -34,10 +34,19 @@ services:
       # N8N_API_KEY: ${N8N_API_KEY}
       # N8N_API_TIMEOUT: ${N8N_API_TIMEOUT:-30000}
       # N8N_API_MAX_RETRIES: ${N8N_API_MAX_RETRIES:-3}
+
+      # Optional: Self-signed certificate support
+      # Uncomment if your n8n instance uses a self-signed SSL certificate
+      # N8N_CERT_PATH: /app/certs/n8n.crt
 
     # Volumes for persistence
     volumes:
       - n8n-mcp-data:/app/data
+
+      # Optional: Mount certificate file for self-signed n8n instances
+      # Uncomment and adjust the path to your certificate file
+      # Example: ./certs/n8n.crt:/app/certs/n8n.crt:ro
+      # - /path/to/your/certificate.crt:/app/certs/n8n.crt:ro
 
     # Port mapping
     ports:

docs/DOCKER_README.md

@@ -68,6 +68,7 @@ docker run -d \
 | `AUTH_RATE_LIMIT_WINDOW` | Rate limit window in ms (v2.16.3+) | `900000` (15 min) | No |
 | `AUTH_RATE_LIMIT_MAX` | Max auth attempts per window (v2.16.3+) | `20` | No |
 | `WEBHOOK_SECURITY_MODE` | SSRF protection: `strict`/`moderate`/`permissive` (v2.16.3+) | `strict` | No |
+| `N8N_CERT_PATH` | Path to SSL certificate for self-signed n8n instances | - | No |
 
 *Either `AUTH_TOKEN` or `AUTH_TOKEN_FILE` must be set for HTTP mode. If both are set, `AUTH_TOKEN` takes precedence.
 
@@ -286,6 +287,7 @@ docker ps --format "table {{.Names}}\t{{.Status}}"
 docker inspect n8n-mcp | jq '.[0].State.Health'
 ```
 
+<<<<<<< HEAD
 ## 🔒 Security Features (v2.16.3+)
 
 ### Rate Limiting
@@ -378,6 +380,76 @@ your-domain.com {
 - No unnecessary packages installed
 - Regular security updates via GitHub Actions
 
+## 🔐 SSL Certificate Configuration
+
+### Self-Signed Certificates
+
+If your n8n instance uses a self-signed SSL certificate, you need to mount the certificate file and configure the `N8N_CERT_PATH` environment variable:
+
+#### Basic Docker Run
+
+```bash
+# Run with mounted certificate
+docker run -d \
+  --name n8n-mcp \
+  -e MCP_MODE=http \
+  -e AUTH_TOKEN=your-secure-token \
+  -e N8N_API_URL=https://your-n8n-instance.com \
+  -e N8N_API_KEY=your-api-key \
+  -e N8N_CERT_PATH=/app/certs/n8n.crt \
+  -v /path/to/your/certificate.crt:/app/certs/n8n.crt:ro \
+  -p 3000:3000 \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+```
+
+#### Docker Compose Configuration
+
+Add certificate configuration to your `docker-compose.yml`:
+
+```yaml
+services:
+  n8n-mcp:
+    image: ghcr.io/czlonkowski/n8n-mcp:latest
+    environment:
+      MCP_MODE: http
+      AUTH_TOKEN: ${AUTH_TOKEN}
+      N8N_API_URL: https://your-n8n-instance.com
+      N8N_API_KEY: ${N8N_API_KEY}
+      N8N_CERT_PATH: /app/certs/n8n.crt
+    volumes:
+      - n8n-mcp-data:/app/data
+      - /path/to/your/certificate.crt:/app/certs/n8n.crt:ro
+    ports:
+      - "3000:3000"
+```
+
+#### Certificate Troubleshooting
+
+**Common Issues:**
+
+1. **Certificate not found error:**
+   ```bash
+   # Verify the certificate is properly mounted
+   docker exec n8n-mcp ls -la /app/certs/
+   ```
+
+2. **Permission denied:**
+   ```bash
+   # Ensure certificate is readable
+   chmod 644 /path/to/your/certificate.crt
+   ```
+
+3. **Invalid certificate format:**
+   - Certificate must be in PEM format (.crt or .pem)
+   - Check with: `openssl x509 -in certificate.crt -text -noout`
+
+4. **Still can't connect:**
+   ```bash
+   # Test certificate directly
+   openssl s_client -connect your-n8n-instance.com:443 \
+     -CAfile /path/to/your/certificate.crt -showcerts
+   ```
+
 ## 📊 Resource Management
 
 ### Memory Limits

docs/HTTP_DEPLOYMENT.md

@@ -137,6 +137,69 @@ Skip HTTP entirely and use stdio mode directly:
 
 💡 **Save your AUTH_TOKEN** - clients will need it to connect!
 
+### Self-Signed Certificates
+
+If your n8n instance uses a self-signed SSL certificate, you need to configure the `N8N_CERT_PATH` environment variable:
+
+#### Docker with Certificate
+
+```bash
+# 1. Create environment file with certificate path
+cat > .env << EOF
+AUTH_TOKEN=$(openssl rand -base64 32)
+USE_FIXED_HTTP=true
+MCP_MODE=http
+PORT=3000
+N8N_CERT_PATH=/app/certs/n8n.crt
+N8N_API_URL=https://your-n8n-instance.com
+N8N_API_KEY=your-api-key-here
+EOF
+
+# 2. Deploy with Docker and mount certificate
+docker run -d \
+  --name n8n-mcp \
+  --restart unless-stopped \
+  --env-file .env \
+  -v /path/to/your/certificate.crt:/app/certs/n8n.crt:ro \
+  -p 3000:3000 \
+  ghcr.io/czlonkowski/n8n-mcp:latest
+```
+
+#### Docker Compose with Certificate
+
+Add the following to your `docker-compose.yml`:
+
+```yaml
+services:
+  n8n-mcp:
+    image: ghcr.io/czlonkowski/n8n-mcp:latest
+    environment:
+      # ... other environment variables ...
+      N8N_CERT_PATH: /app/certs/n8n.crt
+    volumes:
+      - n8n-mcp-data:/app/data
+      - /path/to/your/certificate.crt:/app/certs/n8n.crt:ro
+```
+
+#### Local Development with Certificate
+
+```bash
+# Set the certificate path
+export N8N_CERT_PATH=/path/to/your/certificate.crt
+export N8N_API_URL=https://your-n8n-instance.com
+export N8N_API_KEY=your-api-key
+
+# Start the server
+npm run start:http
+```
+
+#### Certificate Troubleshooting
+
+- **Format**: Certificate must be in PEM format (.crt or .pem file)
+- **Permissions**: Ensure the certificate file is readable by the process
+- **Path**: Use absolute paths to avoid resolution issues
+- **Testing**: You can test the certificate with `openssl s_client -connect your-n8n-instance.com:443 -showcerts`
+
 ## ⚙️ Configuration
 
 ### Required Environment Variables