feat: add Railway deployment support with CI/CD integration
- Add Railway-specific Docker image build to CI/CD workflow - Builds n8n-mcp-railway image alongside standard image - Railway image optimized for AMD64 architecture - Automatically published to ghcr.io on main branch pushes - Create comprehensive Railway deployment documentation - Step-by-step deployment guide with security best practices - Claude Desktop connection instructions via mcp-remote - Troubleshooting guide for common issues - Architecture details and single-instance design explanation - Update README with Railway documentation link - Removed inline Railway content to keep README focused - Added link to dedicated Railway deployment guide This enables zero-configuration cloud deployment of n8n-mcp with automatic HTTPS, global access, and built-in monitoring. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
54
.github/workflows/docker-build.yml
vendored
54
.github/workflows/docker-build.yml
vendored
@@ -70,6 +70,60 @@ jobs:
|
||||
labels: ${{ steps.meta.outputs.labels }}
|
||||
provenance: false
|
||||
|
||||
build-railway:
|
||||
name: Build Railway Docker Image
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
packages: write
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
lfs: true
|
||||
|
||||
- name: Set up QEMU
|
||||
uses: docker/setup-qemu-action@v3
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
id: buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Log in to GitHub Container Registry
|
||||
if: github.event_name != 'pull_request'
|
||||
uses: docker/login-action@v3
|
||||
with:
|
||||
registry: ${{ env.REGISTRY }}
|
||||
username: ${{ github.actor }}
|
||||
password: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Extract metadata for Railway
|
||||
id: meta-railway
|
||||
uses: docker/metadata-action@v5
|
||||
with:
|
||||
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-railway
|
||||
tags: |
|
||||
type=ref,event=branch
|
||||
type=ref,event=pr
|
||||
type=semver,pattern={{version}}
|
||||
type=semver,pattern={{major}}.{{minor}}
|
||||
type=semver,pattern={{major}}
|
||||
type=sha,prefix={{branch}}-,format=short
|
||||
type=raw,value=latest,enable={{is_default_branch}}
|
||||
|
||||
- name: Build and push Railway Docker image
|
||||
uses: docker/build-push-action@v5
|
||||
with:
|
||||
context: .
|
||||
file: ./Dockerfile.railway
|
||||
no-cache: true
|
||||
platforms: linux/amd64
|
||||
push: ${{ github.event_name != 'pull_request' }}
|
||||
tags: ${{ steps.meta-railway.outputs.tags }}
|
||||
labels: ${{ steps.meta-railway.outputs.labels }}
|
||||
provenance: false
|
||||
|
||||
# Nginx build commented out until Phase 2
|
||||
# build-nginx:
|
||||
# name: Build nginx-enhanced Docker Image
|
||||
|
||||
108
README.md
108
README.md
@@ -2,80 +2,13 @@
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://github.com/czlonkowski/n8n-mcp)
|
||||
[](https://github.com/czlonkowski/n8n-mcp)
|
||||
[](https://github.com/czlonkowski/n8n-mcp)
|
||||
[](https://www.npmjs.com/package/n8n-mcp)
|
||||
[](https://github.com/n8n-io/n8n)
|
||||
[](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
|
||||
|
||||
A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. Deploy in minutes to give Claude and other AI assistants deep knowledge about n8n's 525+ workflow automation nodes.
|
||||
|
||||
## 🚀 Zero-Configuration Railway Deployment
|
||||
|
||||
Deploy n8n-MCP to Railway with **one click** - no configuration required to start!
|
||||
|
||||
[](https://railway.com/deploy/AQSZuP?referralCode=xdb4OL)
|
||||
|
||||
### ✨ Features
|
||||
- **Works immediately** - Pre-configured with working defaults
|
||||
- **Secure by design** - Prominent warnings for default AUTH_TOKEN
|
||||
- **Production-ready** - Optimized environment variables included
|
||||
- **No setup required** - Just click deploy!
|
||||
|
||||
### 🚀 Quick Deploy Steps
|
||||
|
||||
1. **Click Deploy** - Use the button above
|
||||
2. **Wait ~2 minutes** - Railway builds and deploys automatically
|
||||
3. **Get your URL** - Railway provides a public URL instantly
|
||||
4. **Start using** - Connect to Claude Desktop immediately!
|
||||
|
||||
### ⚠️ IMPORTANT: Post-Deployment Security
|
||||
|
||||
**The deployment includes a default AUTH_TOKEN for instant functionality.**
|
||||
|
||||
After deployment, you MUST:
|
||||
1. Go to Railway dashboard → Variables
|
||||
2. Find `AUTH_TOKEN` variable
|
||||
3. Replace with secure token: `openssl rand -base64 32`
|
||||
4. Railway will automatically redeploy
|
||||
|
||||
> **Security Note**: The server will display warnings every 5 minutes until you change the default token!
|
||||
|
||||
### 🔧 Environment Variables (Auto-Configured)
|
||||
|
||||
| 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 (customize later) |
|
||||
| `PORT` | (Railway provides) | Don't set manually |
|
||||
|
||||
### 📝 Optional: n8n API Integration
|
||||
|
||||
To enable workflow management features, add these variables in Railway:
|
||||
- `N8N_API_URL` - Your n8n instance URL
|
||||
- `N8N_API_KEY` - API key from n8n settings
|
||||
|
||||
### 🎯 Creating Your Own Railway Template
|
||||
|
||||
Want to customize and create your own Railway deploy button?
|
||||
|
||||
1. **Deploy this project** first using the button above
|
||||
2. **Customize** environment variables as needed
|
||||
3. **Go to Railway dashboard** → Your project → Settings
|
||||
4. **Click "Generate Template"** at the bottom
|
||||
5. **Configure template**:
|
||||
- Set required variables (AUTH_TOKEN)
|
||||
- Add description and icon
|
||||
- Publish the template
|
||||
6. **Get your template URL** and button code
|
||||
7. **Update this README** with your custom button
|
||||
|
||||
> **Note**: The current button deploys from kimbo128's fork. Create your own template to deploy from your repository!
|
||||
|
||||
## Overview
|
||||
|
||||
n8n-MCP serves as a bridge between n8n's workflow automation platform and AI models, enabling them to understand and work with n8n nodes effectively. It provides structured access to:
|
||||
@@ -265,6 +198,8 @@ Add to Claude Desktop config:
|
||||
|
||||
**Important:** The `-i` flag is required for MCP stdio communication.
|
||||
|
||||
> 🔧 If you encounter any issues with Docker, check our [Docker Troubleshooting Guide](./docs/DOCKER_TROUBLESHOOTING.md).
|
||||
|
||||
**Configuration file locations:**
|
||||
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
@@ -272,6 +207,26 @@ Add to Claude Desktop config:
|
||||
|
||||
**Restart Claude Desktop after updating configuration** - That's it! 🎉
|
||||
|
||||
## 💖 Support This Project
|
||||
|
||||
<div align="center">
|
||||
<a href="https://github.com/sponsors/czlonkowski">
|
||||
<img src="https://img.shields.io/badge/Sponsor-❤️-db61a2?style=for-the-badge&logo=github-sponsors" alt="Sponsor n8n-mcp" />
|
||||
</a>
|
||||
</div>
|
||||
|
||||
**n8n-mcp** started as a personal tool but now helps tens of thousands of developers automate their workflows efficiently. Maintaining and developing this project competes with my paid work.
|
||||
|
||||
Your sponsorship helps me:
|
||||
- 🚀 Dedicate focused time to new features
|
||||
- 🐛 Respond quickly to issues
|
||||
- 📚 Keep documentation up-to-date
|
||||
- 🔄 Ensure compatibility with latest n8n releases
|
||||
|
||||
Every sponsorship directly translates to hours invested in making n8n-mcp better for everyone. **[Become a sponsor →](https://github.com/sponsors/czlonkowski)**
|
||||
|
||||
---
|
||||
|
||||
### Option 3: Local Installation (For Development)
|
||||
|
||||
**Prerequisites:** [Node.js](https://nodejs.org/) installed on your system
|
||||
@@ -330,6 +285,22 @@ Add to Claude Desktop config:
|
||||
|
||||
> 💡 Tip: If you’re running n8n locally on the same machine (e.g., via Docker), use http://host.docker.internal:5678 as the N8N_API_URL.
|
||||
|
||||
## 💻 Connect your IDE
|
||||
|
||||
n8n-MCP works with multiple AI-powered IDEs and tools. Choose your preferred development environment:
|
||||
|
||||
### [Claude Code](./docs/CLAUDE_CODE_SETUP.md)
|
||||
Quick setup for Claude Code CLI - just type "add this mcp server" and paste the config.
|
||||
|
||||
### [Visual Studio Code](./docs/VS_CODE_PROJECT_SETUP.md)
|
||||
Full setup guide for VS Code with GitHub Copilot integration and MCP support.
|
||||
|
||||
### [Cursor](./docs/CURSOR_SETUP.md)
|
||||
Step-by-step tutorial for connecting n8n-MCP to Cursor IDE with custom rules.
|
||||
|
||||
### [Windsurf](./docs/WINDSURF_SETUP.md)
|
||||
Complete guide for integrating n8n-MCP with Windsurf using project rules.
|
||||
|
||||
## 🤖 Claude Project Setup
|
||||
|
||||
For the best results when using n8n-MCP with Claude Projects, use these enhanced system instructions:
|
||||
@@ -635,6 +606,7 @@ npm run dev:http # HTTP dev mode
|
||||
- [Validation System](./docs/validation-improvements-v2.4.2.md) - Smart validation profiles
|
||||
|
||||
### Development & Deployment
|
||||
- [Railway Deployment](./docs/RAILWAY_DEPLOYMENT.md) - One-click cloud deployment guide
|
||||
- [HTTP Deployment](./docs/HTTP_DEPLOYMENT.md) - Remote server setup guide
|
||||
- [Dependency Management](./docs/DEPENDENCY_UPDATES.md) - Keeping n8n packages in sync
|
||||
- [Claude's Interview](./docs/CLAUDE_INTERVIEW.md) - Real-world impact of n8n-MCP
|
||||
|
||||
247
docs/RAILWAY_DEPLOYMENT.md
Normal file
247
docs/RAILWAY_DEPLOYMENT.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# 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/Ep_b-Y?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
|
||||
|
||||
### 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: 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](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!
|
||||
Reference in New Issue
Block a user