n8n-mcp/docs/HTTP_DEPLOYMENT.md

# 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:

**Option 1: Using global mcp-remote installation**
```json
{
  "mcpServers": {
    "n8n-remote": {
      "command": "mcp-remote",
      "args": [
        "connect",
        "https://your-domain.com/mcp"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "your-secure-token-here"
      }
    }
  }
}
```

**Option 2: Using npx (no installation required)**
```json
{
  "mcpServers": {
    "n8n-remote": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/mcp-remote@latest",
        "connect",
        "https://your-domain.com/mcp"
      ],
      "env": {
        "MCP_AUTH_TOKEN": "your-secure-token-here"
      }
    }
  }
}
```

**Option 3: Using custom headers (if needed)**
```json
{
  "mcpServers": {
    "n8n-remote": {
      "command": "mcp-remote",
      "args": [
        "connect",
        "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"
}
```

## Testing

Use the included test script to verify your HTTP server:

```bash
# Test local server
./scripts/test-http.sh

# Test remote server
./scripts/test-http.sh https://your-domain.com

# Test with custom token
AUTH_TOKEN=your-token ./scripts/test-http.sh

# Verbose output
VERBOSE=1 ./scripts/test-http.sh
```

The test script checks:
- Health endpoint
- CORS preflight
- Authentication
- Valid MCP requests
- Error handling
- Request size limits

## Troubleshooting

### Connection Refused
- Check firewall rules
- Verify server is running
- Check nginx/proxy configuration
- Run the test script to diagnose

### Authentication Failed
- Verify AUTH_TOKEN matches in both server and client
- Check Authorization header format
- Token should be at least 32 characters

### MCP Tools Not Available
- Restart Claude Desktop
- Check mcp-remote installation
- Verify server logs for errors
- Ensure CORS headers are working

## 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.