n8n + n8n-MCP Agent Template

This guide sets up:

1. A self-hosted n8n on Railway (Primary + Worker + Redis + Postgres) 2. n8n-mcp on Railway in the same project 3. Local agent config for codex and claude using .env

What This Repo Includes

🧠 Skill Pack

This repo includes the n8n skill pack under .codex/skills/, sourced from:

• czlonkowski/n8n-skills

Included skill areas:

• 🧩 n8n expression syntax
• 🛠️ n8n MCP tools usage
• 🏗️ n8n workflow patterns
• ✅ n8n validation troubleshooting
• ⚙️ n8n node configuration guidance
• 💻 n8n Code node support (JavaScript + Python)

🌉 n8n-MCP Capability Snapshot

n8n-MCP gives your agent structured access to the n8n ecosystem, including:

• 📚 Large node catalog coverage (core + community)
• 🔎 Node property and operation metadata
• 📄 Documentation-aware guidance
• 🤖 AI tool variants and node discovery
• 💡 Real-world examples from templates
• 🎯 Template library search and deployment support
• 🌐 Community node discovery with verified-source filtering

🚀 How To Use This Repo (Suggested Flow)

1. Start your agent in plan mode and define the target automation flow 2. Ask it to map the flow into n8n nodes and data handoff between nodes 3. Let it use n8n-MCP tools to search nodes/templates and validate configs 4. Let it use bundled skills for expressions, Code nodes, and troubleshooting 5. Build iteratively: generate workflow, validate, fix errors, then deploy/test

Prerequisites

• Railway account: railway.com
• Domain + DNS access (optional but recommended)
• Local codex and/or claude CLI
• npx installed (for Claude via mcp-remote)

1) Deploy n8n (with workers) on Railway

1. Open Railway templates: railway.com/new/template 2. Search n8n 3. Select n8n (w/ workers) 4. Click Deploy (default config is fine)

This template creates four services:

• Primary (n8n main app)
• Worker
• Redis
• Postgres

2) Configure n8n Domain and DNS

If you are using a custom domain:

1. In Railway, open the Primary service 2. Go to Networking 3. Click Custom Domain and add your domain (for example n8n.example.com) 4. In your DNS provider, create the DNS record Railway asks for (usually a CNAME) 5. Wait for Railway domain verification to turn healthy

Use this domain as your main n8n URL.

3) Deploy n8n-mcp on Railway

1. Open the repo: github.com/czlonkowski/n8n-mcp 2. Click Deploy on Railway 3. When Railway asks where to deploy, choose the same project as your n8n stack 4. Deploy and wait for service status Online

4) Configure n8n-mcp Variables on Railway

In the n8n-mcp service, go to Variables and set:

• AUTH_TOKEN:
• Generate locally:

    openssl rand -base64 32

• Paste this value into Railway variable AUTH_TOKEN
• Do not keep the template default token
• N8N_API_URL:
• Open Railway -> your n8n Primary service -> Networking
• Copy your public/custom n8n domain (for example https://n8n.example.com)
• Use that full URL as N8N_API_URL (no trailing slash)
• N8N_API_KEY:
• Open your n8n app in browser
• Go to Settings -> API (or n8n API)
• Create/copy an API key
• Paste into Railway variable N8N_API_KEY

Optional:

• N8N_MODE=true when using n8n MCP client integration mode

After saving variables, Railway redeploys automatically.

5) Get Your n8n-mcp Endpoint

From Railway service settings/domains, copy the public URL and append /mcp:

https://YOUR_N8N_MCP_SERVER_URL/mcp

6) Local .env Setup

1. Copy env template:

cp .env.example .env

2. Add your Railway AUTH_TOKEN:

N8N_MCP_AUTH_TOKEN=your_auth_token_from_railway

3. Start agents through wrappers:

./scripts/codex
./scripts/claude

Wrappers auto-load .env before launching.

7) Agent MCP Config

Codex (config.toml)

PS: bearer_token_env_var references your env var name

[mcp_servers.n8n_railway]
url = "https://YOUR_N8N_MCP_SERVER_URL/mcp"
bearer_token_env_var = "N8N_MCP_AUTH_TOKEN"

Claude (.mcp.json)

Use mcp-remote with Authorization header:

{
  "mcpServers": {
    "n8n_railway": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR_N8N_MCP_SERVER_URL/mcp",
        "--header",
        "Authorization: Bearer ${N8N_MCP_AUTH_TOKEN}"
      ]
    }
  }
}

Claude expands ${...} from your environment, so this uses the variable names from .env directly. You can also use a variable for the URL if you like.

8) Recommended Validation

1. Confirm n8n is reachable on your custom domain 2. Confirm n8n-mcp service is healthy on Railway 3. Run ./scripts/codex or ./scripts/claude 4. In agent chat, run a simple n8n query (for example node search) to verify MCP connectivity

Reference

• n8n-mcp Railway guide: RAILWAY_DEPLOYMENT.md

Optional: Shell Aliases

Add to ~/.zshrc or ~/.bashrc:

alias codex-n8n='~/path/to/your/n8n-template/scripts/codex'
alias claude-n8n='~/path/to/your/n8n-template/scripts/claude'