feat: add HTTP server mode for remote deployment with token auth
This commit is contained in:
czlonkowski
214
docs/HTTP_DEPLOYMENT.md
Normal file
214
docs/HTTP_DEPLOYMENT.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# HTTP Deployment Guide
|
||||
|
||||
This guide explains how to deploy n8n-MCP as a private HTTP server for remote access.
|
||||
|
||||
## Overview
|
||||
|
||||
The HTTP mode allows you to run n8n-MCP on a remote server and connect to it from Claude Desktop using the mcp-remote adapter. This is designed for single-user private deployments.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Node.js v16+ on the server
|
||||
- A server with a public IP or domain
|
||||
- HTTPS proxy (nginx/caddy) for secure connections
|
||||
- mcp-remote installed on the client
|
||||
|
||||
## Server Setup
|
||||
|
||||
### 1. Clone and Build
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/n8n-mcp.git
|
||||
cd n8n-mcp
|
||||
npm install
|
||||
npm run build
|
||||
npm run rebuild
|
||||
```
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edit `.env`:
|
||||
```env
|
||||
# HTTP mode configuration
|
||||
MCP_MODE=http
|
||||
PORT=3000
|
||||
HOST=0.0.0.0
|
||||
|
||||
# Generate secure token
|
||||
AUTH_TOKEN=your-secure-token-here
|
||||
|
||||
# Other settings
|
||||
NODE_DB_PATH=./data/nodes.db
|
||||
MCP_LOG_LEVEL=info
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
Generate a secure token:
|
||||
```bash
|
||||
openssl rand -base64 32
|
||||
```
|
||||
|
||||
### 3. Start the Server
|
||||
|
||||
```bash
|
||||
# Using the deployment script
|
||||
./scripts/deploy-http.sh
|
||||
|
||||
# Or manually
|
||||
MCP_MODE=http npm start
|
||||
```
|
||||
|
||||
The server will start on `http://0.0.0.0:3000`
|
||||
|
||||
### 4. Setup HTTPS Proxy (Recommended)
|
||||
|
||||
#### Using nginx:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name your-domain.com;
|
||||
|
||||
ssl_certificate /path/to/cert.pem;
|
||||
ssl_certificate_key /path/to/key.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:3000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection 'upgrade';
|
||||
proxy_set_header Host $host;
|
||||
proxy_cache_bypass $http_upgrade;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Using Caddy:
|
||||
|
||||
```caddyfile
|
||||
your-domain.com {
|
||||
reverse_proxy localhost:3000
|
||||
}
|
||||
```
|
||||
|
||||
## Client Setup
|
||||
|
||||
### 1. Install mcp-remote
|
||||
|
||||
```bash
|
||||
npm install -g mcp-remote
|
||||
```
|
||||
|
||||
### 2. Configure Claude Desktop
|
||||
|
||||
Edit Claude Desktop config:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"n8n-documentation": {
|
||||
"command": "mcp-remote",
|
||||
"args": [
|
||||
"https://your-domain.com/mcp",
|
||||
"--header",
|
||||
"Authorization: Bearer your-secure-token-here"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Test Connection
|
||||
|
||||
1. Restart Claude Desktop
|
||||
2. The MCP tools should be available
|
||||
3. Test with: "List all n8n nodes"
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Always use HTTPS** in production
|
||||
2. **Keep AUTH_TOKEN secret** - treat it like a password
|
||||
3. **Firewall rules** - Only expose necessary ports
|
||||
4. **Regular updates** - Keep dependencies updated
|
||||
5. **Monitor logs** - Check for unauthorized access attempts
|
||||
|
||||
## Health Monitoring
|
||||
|
||||
Check server health:
|
||||
```bash
|
||||
curl https://your-domain.com/health
|
||||
```
|
||||
|
||||
Expected response:
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"mode": "http",
|
||||
"version": "2.3.0"
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Refused
|
||||
- Check firewall rules
|
||||
- Verify server is running
|
||||
- Check nginx/proxy configuration
|
||||
|
||||
### Authentication Failed
|
||||
- Verify AUTH_TOKEN matches in both server and client
|
||||
- Check Authorization header format
|
||||
|
||||
### MCP Tools Not Available
|
||||
- Restart Claude Desktop
|
||||
- Check mcp-remote installation
|
||||
- Verify server logs for errors
|
||||
|
||||
## Performance Tips
|
||||
|
||||
1. Use a VPS with good network connectivity
|
||||
2. Enable gzip compression in your proxy
|
||||
3. Consider using PM2 for process management:
|
||||
```bash
|
||||
pm2 start npm --name "n8n-mcp" -- run start:http
|
||||
```
|
||||
|
||||
## Example Systemd Service
|
||||
|
||||
Create `/etc/systemd/system/n8n-mcp.service`:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=n8n MCP HTTP Server
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=your-user
|
||||
WorkingDirectory=/path/to/n8n-mcp
|
||||
ExecStart=/usr/bin/npm run start:http
|
||||
Restart=on-failure
|
||||
Environment=NODE_ENV=production
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Enable and start:
|
||||
```bash
|
||||
sudo systemctl enable n8n-mcp
|
||||
sudo systemctl start n8n-mcp
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
- Single-user design (no multi-tenancy)
|
||||
- Stateless (no session persistence)
|
||||
- No built-in rate limiting
|
||||
- Basic token authentication only
|
||||
|
||||
For multi-user deployments, consider implementing a proper API gateway with user management.
|
||||
Reference in New Issue
Block a user