270 lines
8.4 KiB
Markdown
270 lines
8.4 KiB
Markdown
# 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:
|
|
|
|
[](https://railway.com/deploy/VY6UOG?referralCode=n8n-mcp)
|
|
|
|
## 📋 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:
|
|
|
|
|
|
|
|
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**:
|
|
```bash
|
|
# 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
|
|
|
|
|
|
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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 Variables
|
|
|
|
| Variable | Default Value | Description |
|
|
|----------|--------------|-------------|
|
|
| `N8N_MODE` | `false` | Enable n8n integration mode for MCP Client Tool |
|
|
| `N8N_API_URL` | - | URL of your n8n instance (for workflow management) |
|
|
| `N8N_API_KEY` | - | API key from n8n Settings → API |
|
|
|
|
### Optional: n8n Integration
|
|
|
|
#### For n8n MCP Client Tool Integration
|
|
|
|
To use n8n-MCP with n8n's MCP Client Tool node:
|
|
|
|
1. **Go to Railway dashboard** → Your service → **Variables**
|
|
2. **Add this variable**:
|
|
- `N8N_MODE`: Set to `true` to enable n8n integration mode
|
|
3. **Save changes** - Railway will redeploy automatically
|
|
|
|
#### For n8n API Integration (Workflow Management)
|
|
|
|
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](https://github.com/czlonkowski/n8n-mcp)
|
|
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
|
|
|
|
- **Railway Documentation**: [docs.railway.app](https://docs.railway.app)
|
|
- **n8n-MCP Issues**: [GitHub Issues](https://github.com/czlonkowski/n8n-mcp/issues)
|
|
- **Railway Community**: [Discord](https://discord.gg/railway)
|
|
|
|
## 🎉 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! |