ros/n8n-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7a71c3c3f89e7759f36fbc8a79e4b868d3f6a49c
n8n-mcp/docs/RAILWAY_DEPLOYMENT.md

7.8 KiB
Raw Blame History

Railway Deployment Guide for n8n-MCP

Deploy n8n-MCP to Railway's cloud platform with zero configuration and connect it to Claude Desktop from anywhere.

🚀 Quick Deploy

Deploy n8n-MCP with one click:

Deploy on Railway

📋 Overview

Railway deployment provides:

  • ☁️ Instant cloud hosting - No server setup required
  • 🔒 Secure by default - HTTPS included, auth token warnings
  • 🌐 Global access - Connect from any Claude Desktop
  • ⚡ Auto-scaling - Railway handles the infrastructure
  • 📊 Built-in monitoring - Logs and metrics included

🎯 Step-by-Step Deployment

1. Deploy to Railway

  1. Click the Deploy button above
  2. Sign in to Railway (or create account)
  3. Configure your deployment:
    • Project name (optional)
    • Environment (leave as "production")
    • Region (choose closest to you)
  4. Click "Deploy" and wait ~2-3 minutes

2. Configure Security

IMPORTANT: The deployment includes a default AUTH_TOKEN for instant functionality, but you MUST change it:

Railway Dashboard - Variables Tab

  1. Go to your Railway dashboard
  2. Click on your n8n-mcp service
  3. Navigate to "Variables" tab
  4. Find AUTH_TOKEN
  5. Replace with secure token: 
    # Generate secure token locally:
openssl rand -base64 32
  6. Railway will automatically redeploy with the new token

⚠️ Security Warning: The server displays warnings every 5 minutes until you change the default token!

3. Get Your Service URL

Railway Dashboard - Domain Settings

  1. In Railway dashboard, click on your service
  2. Go to "Settings" tab
  3. Under "Domains", you'll see your URL: 
    https://your-app-name.up.railway.app
  4. Copy this URL for Claude Desktop configuration and add /mcp at the end

4. Connect Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "n8n-railway": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-app-name.up.railway.app/mcp",
        "--header",
        "Authorization: Bearer YOUR_SECURE_TOKEN_HERE"
      ]
    }
  }
}

Configuration file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop after saving the configuration.

🔧 Environment Variables

Default Variables (Pre-configured)

These are automatically set by the Railway template:

Variable Default Value Description
AUTH_TOKEN REPLACE_THIS... ⚠️ CHANGE IMMEDIATELY
MCP_MODE http Required for cloud deployment
USE_FIXED_HTTP true Stable HTTP implementation
NODE_ENV production Production optimizations
LOG_LEVEL info Balanced logging
TRUST_PROXY 1 Railway runs behind proxy
CORS_ORIGIN * Allow any origin
HOST 0.0.0.0 Listen on all interfaces
PORT (Railway provides) Don't set manually

Optional: n8n API Integration

To enable workflow management features:

  1. Go to Railway dashboard → Your service → Variables
  2. Add these variables:
    • N8N_API_URL: Your n8n instance URL (e.g., https://n8n.example.com)
    • N8N_API_KEY: API key from n8n Settings → API
  3. Save changes - Railway will redeploy automatically

🏗️ Architecture Details

How It Works

Claude Desktop → mcp-remote → Railway (HTTPS) → n8n-MCP Server
  1. Claude Desktop uses mcp-remote as a bridge
  2. mcp-remote converts stdio to HTTP requests
  3. Railway provides HTTPS endpoint and infrastructure
  4. n8n-MCP runs in HTTP mode on Railway

Single-Instance Design

Important: The n8n-MCP HTTP server is designed for single n8n instance deployment:

  • n8n API credentials are configured server-side via environment variables
  • All clients connecting to the server share the same n8n instance
  • For multi-tenant usage, deploy separate Railway instances

Security Model

  • Bearer Token Authentication: All requests require the AUTH_TOKEN
  • HTTPS by Default: Railway provides SSL certificates
  • Environment Isolation: Each deployment is isolated
  • No State Storage: Server is stateless (database is read-only)

🚨 Troubleshooting

Connection Issues

"Invalid URL" error in Claude Desktop:

  • Ensure you're using the exact configuration format shown above
  • Don't add "connect" or other arguments before the URL
  • The URL should end with /mcp

"Unauthorized" error:

  • Check that your AUTH_TOKEN matches exactly (no extra spaces)
  • Ensure the Authorization header format is correct: Authorization: Bearer TOKEN

"Cannot connect to server":

  • Verify your Railway deployment is running (check Railway dashboard)
  • Ensure the URL is correct and includes https://
  • Check Railway logs for any errors

Railway-Specific Issues

Build failures:

  • Railway uses AMD64 architecture - the template is configured for this
  • Check build logs in Railway dashboard for specific errors

Environment variable issues:

  • Variables are case-sensitive
  • Don't include quotes in the Railway dashboard (only in JSON config)
  • Railway automatically restarts when you change variables

Domain not working:

  • It may take 1-2 minutes for the domain to become active
  • Check the "Deployments" tab to ensure the latest deployment succeeded

📊 Monitoring & Logs

View Logs

  1. Go to Railway dashboard
  2. Click on your n8n-mcp service
  3. Click on "Logs" tab
  4. You'll see real-time logs including:
    • Server startup messages
    • Authentication attempts
    • API requests (without sensitive data)
    • Any errors or warnings

Monitor Usage

Railway provides metrics for:

  • Memory usage (typically ~100-200MB)
  • CPU usage (minimal when idle)
  • Network traffic
  • Response times

💰 Pricing & Limits

Railway Free Tier

  • $5 free credit monthly
  • 500 hours of runtime
  • Sufficient for personal use of n8n-MCP

Estimated Costs

  • n8n-MCP typically uses: ~0.1 GB RAM
  • Monthly cost: ~$2-3 for 24/7 operation
  • Well within free tier for most users

🔄 Updates & Maintenance

Manual Updates

Since the Railway template uses a specific Docker image tag, updates are manual:

  1. Check for updates on GitHub
  2. Update image tag in Railway:
    • Go to Settings → Deploy → Docker Image
    • Change tag from current to new version
    • Click "Redeploy"

Automatic Updates (Not Recommended)

You could use the latest tag, but this may cause unexpected breaking changes.

📝 Best Practices

  1. Always change the default AUTH_TOKEN immediately
  2. Use strong, unique tokens (32+ characters)
  3. Monitor logs for unauthorized access attempts
  4. Keep credentials secure - never commit them to git
  5. Use environment variables for all sensitive data
  6. Regular updates - check for new versions monthly

🆘 Getting Help

🎉 Success!

Once connected, you can use all n8n-MCP features from Claude Desktop:

  • Search and explore 500+ n8n nodes
  • Get node configurations and examples
  • Validate workflows before deployment
  • Manage n8n workflows (if API configured)

The cloud deployment means you can access your n8n knowledge base from any computer with Claude Desktop installed!