AurelienFAGIOLI/n8n-mcp-aurelien

📋 Table of Contents

• Overview
• Features
• Prerequisites
• Quick Start
• Installation
  • Docker (Recommended)
  • Node.js
  • Docker Hub
• Configuration
• Available Tools
• Usage Examples
• Architecture
• Development
• Troubleshooting
• Security
• Contributing
• License

🎯 Overview

n8n MCP Server is a production-ready Model Context Protocol server that bridges Claude AI with n8n workflow automation. It enables natural language workflow creation, intelligent template search, and complete workflow lifecycle management.

What is MCP?

The Model Context Protocol (MCP) is an open standard by Anthropic that enables AI assistants to securely interact with external tools and data sources.

Why This Project?

• 🎨 Natural Language Workflows: Create complex automations by simply describing what you want
• 🔍 Smart Discovery: Search through 541 n8n nodes and 2700+ templates instantly
• ⚡ Production Ready: Type-safe, tested, and containerized for easy deployment
• 🧠 AI-Powered: Automatically matches your requirements with the best nodes and templates
• 🐳 Docker Native: One-command deployment with full isolation

✨ Features

🚀 Core Capabilities

🛠️ Technical Features

• ✅ TypeScript — Fully typed for reliability and maintainability
• ✅ SQLite + FTS5 — Fast full-text search with minimal setup
• ✅ Docker Support — Multi-stage builds with health checks
• ✅ Zod Validation — Runtime input/output validation
• ✅ Error Handling — Comprehensive error messages and recovery
• ✅ Secure by Default — Non-root container, environment-based secrets

📋 Prerequisites

Before you begin, ensure you have:

• n8n Instance (v1.0+)

  • Self-hosted or n8n.cloud account
  • API access enabled
  • API key generated ()

• One of the following:

  • Docker (recommended) — For containerized deployment
  • Node.js 18+ — For local development

• Claude Desktop — To use the MCP server

🚀 Quick Start

Option 1: Docker (Recommended)

The fastest way to get started:

# 1. Clone the repository
git clone https://github.com/aurelienfagioli/n8n-mcp-aurelien.git
cd n8n-mcp-aurelien

# 2. Configure your n8n credentials
cp .env.example .env
nano .env  # Edit with your n8n URL and API key

# 3. Initialize database
npm install
npm run db:init

# 4. Build Docker image
npm run docker:build

# 5. Configure Claude Desktop
# See Configuration section below

Option 2: One-Line Docker Run

If you already have the image built:

docker run -i --rm \
  -e N8N_API_URL="https://your-n8n.hostinger.com" \
  -e N8N_API_KEY="your_api_key_here" \
  -v n8n-mcp-data:/app/data \
  n8n-mcp-aurelien:latest

📦 Installation

Choose your preferred installation method:

Option 1: Docker (Recommended)

Step 1: Clone and Configure

git clone https://github.com/aurelienfagioli/n8n-mcp-aurelien.git
cd n8n-mcp-aurelien
cp .env.example .env

Step 2: Edit .env file

N8N_API_URL=https://your-n8n-instance.com
N8N_API_KEY=n8n_api_xxxxxxxxxxxxxxxxxxxxx
DATABASE_PATH=/app/data/nodes.db
LOG_LEVEL=info
MCP_MODE=stdio

Step 3: Initialize Database

npm install
npm run db:init

Step 4: Build Image

docker build -t n8n-mcp-aurelien:latest -f docker/Dockerfile .
# or
npm run docker:build

Step 5: Test the Server

docker run -i --rm \
  -e N8N_API_URL="$N8N_API_URL" \
  -e N8N_API_KEY="$N8N_API_KEY" \
  -v n8n-mcp-data:/app/data \
  n8n-mcp-aurelien:latest

Option 2: Node.js (Local Installation)

Step 1: Clone and Install

git clone https://github.com/aurelienfagioli/n8n-mcp-aurelien.git
cd n8n-mcp-aurelien
npm install

Step 2: Configure

cp .env.example .env
nano .env  # Edit with your credentials

Step 3: Build and Initialize

npm run build
npm run db:init

Step 4: Run

npm start

Option 3: Pull from GitHub Container Registry (Recommended)

📦 Available Now: Pull the pre-built image directly from GHCR:

# Pull the latest image from GitHub Container Registry
docker pull ghcr.io/aurelienfagioli/n8n-mcp-aurelien:latest

# Run immediately
docker run -i --rm \
  -e N8N_API_URL="https://your-n8n.com" \
  -e N8N_API_KEY="your_key" \
  -v n8n-mcp-data:/app/data \
  ghcr.io/aurelienfagioli/n8n-mcp-aurelien:latest

⚠️ Important: The -v n8n-mcp-data:/app/data volume mount is required for the database!

See for more deployment options.

⚙️ Configuration

Configure Claude Desktop

Add the MCP server to Claude Desktop's configuration file:

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

For Docker Deployment:

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "N8N_API_URL=https://your-n8n-instance.com",
        "-e", "N8N_API_KEY=your_api_key_here",
        "-v", "n8n-mcp-data:/app/data",
        "ghcr.io/aurelienfagioli/n8n-mcp-aurelien:latest"
      ]
    }
  }
}

For Local Node.js Installation:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": [
        "/absolute/path/to/n8n-mcp-aurelien/dist/index.js"
      ],
      "env": {
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your_api_key_here",
        "DATABASE_PATH": "/absolute/path/to/n8n-mcp-aurelien/data/nodes.db"
      }
    }
  }
}

⚠️ Important: Replace your-n8n-instance.com and your_api_key_here with your actual credentials!

Restart Claude Desktop after saving the configuration.

🛠️ Available Tools

Once configured, Claude can use these 12 powerful tools:

📝 Workflow Management

🔍 Node Explorer

📦 Template Library

💡 Usage Examples

Example 1: Create an Email Reminder Workflow

You:

"Create a workflow that sends me an email every Monday at 9am reminding me to review weekly reports"

Claude (using MCP):

1. ✅ Calls create-workflow with your description
2. 🔍 Searches database for schedule and email nodes
3. 📋 Finds relevant template or creates from scratch
4. 🚀 Creates workflow in your n8n instance
5. ✨ Returns: "Workflow created! ID: abc123, URL: https://your-n8n.com/workflow/abc123"

Example 2: Discover Integration Options

You:

"What nodes can I use to work with Google Sheets?"

Claude:

1. 🔍 Calls search-nodes with query "google sheets"
2. 📊 Returns available nodes: Google Sheets, Google Sheets Trigger, etc.
3. 📖 Shows capabilities and operations for each node

Example 3: Use a Pre-Built Template

You:

"Find me a template for syncing data between Notion and Airtable"

Claude:

1. 📦 Calls search-templates with your query
2. 📋 Shows top matching templates
3. 🎨 You can then ask: "Create a workflow from template #5"
4. ✅ Claude creates the workflow using that template

Example 4: Manage Existing Workflows

You:

"Show me all my workflows that are currently inactive"

Claude:

1. 📋 Calls list-workflows with filter active: false
2. 📊 Displays list of inactive workflows
3. 💡 You can then activate or modify them

🏗️ Architecture

System Overview

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│   Claude    │ ◄─MCP─► │  n8n MCP     │ ◄─API─► │   n8n       │
│  Desktop    │         │   Server     │         │  Instance   │
└─────────────┘         └──────────────┘         └─────────────┘
                              │
                              ▼
                        ┌─────────────┐
                        │  SQLite DB  │
                        │  (FTS5)     │
                        └─────────────┘
                         Nodes + Templates

Project Structure

n8n-mcp-aurelien/
├── 📄 README.md                  # You are here
├── 📄 INSTALL.md                 # Installation guide
├── 📄 QUICKSTART.md              # Quick start guide
├── 📄 CONTRIBUTING.md            # Contribution guidelines
├── 📄 DEPLOYMENT.md              # Docker Hub deployment
├── 📄 CHANGELOG.md               # Version history
├── 📄 LICENSE                    # MIT License
│
├── 📦 package.json               # Dependencies & scripts
├── 🔧 tsconfig.json              # TypeScript config
├── 🔐 .env.example               # Environment template
├── 🚫 .gitignore                 # Git ignore rules
│
├── 📂 src/                       # Source code
│   ├── index.ts                 # Entry point
│   ├── server.ts                # MCP server setup
│   │
│   ├── 📂 types/                # TypeScript interfaces
│   │   └── index.ts             # All type definitions
│   │
│   ├── 📂 database/             # SQLite database
│   │   ├── db.ts               # Database client
│   │   └── schema.sql          # DB schema with FTS5
│   │
│   ├── 📂 n8n-api/             # n8n REST API client
│   │   └── client.ts           # Axios-based API wrapper
│   │
│   └── 📂 tools/                # MCP tool implementations
│       ├── workflow-creator.ts  # AI workflow creation
│       ├── workflow-manager.ts  # CRUD operations
│       ├── node-explorer.ts     # Node search & docs
│       └── template-search.ts   # Template discovery
│
├── 📂 scripts/                   # Utility scripts
│   ├── init-db.ts               # Database initialization
│   ├── fetch-nodes.ts           # Scrape n8n nodes
│   └── fetch-templates.ts       # Scrape templates
│
├── 📂 docker/                    # Docker configuration
│   ├── Dockerfile               # Multi-stage build
│   ├── docker-compose.yml       # Compose setup
│   └── healthcheck.sh           # Container health check
│
├── 📂 data/                      # Database storage
│   ├── nodes.db                 # SQLite database
│   └── nodes-sample.json        # Sample data
│
└── 📂 dist/                      # Compiled JavaScript
    └── (auto-generated)

Technology Stack

🔧 Development

Development Mode

Run with auto-reload on file changes:

npm run dev

This uses tsx to watch TypeScript files and restart automatically.

Build

Compile TypeScript to JavaScript:

npm run build

Output goes to dist/ directory.

Database Management

Initialize/Reset Database:

# Warning: This deletes existing data!
rm -f data/nodes.db
npm run db:init

Fetch Real Node Data:

npm run fetch:nodes    # Scrape n8n documentation for nodes
npm run fetch:templates # Scrape workflow templates
npm run db:seed        # Fetch + initialize in one command

Testing

# Test database operations
node -e "
const { N8nDatabase } = require('./dist/database/db.js');
const db = new N8nDatabase('./data/nodes.db');
console.log(db.getStats());
"

# Test n8n API connection
curl -H "X-N8N-API-KEY: your_key" \
     https://your-n8n.com/api/v1/workflows

🐛 Troubleshooting

Common Issues

❌ "Failed to connect to n8n API"

Symptoms: MCP server can't reach n8n instance

Solutions:

1. Verify N8N_API_URL is correct and accessible
2. Check API key is valid: Settings → API → API Keys
3. Test connection manually:

   curl -H "X-N8N-API-KEY: your_key" \
        https://your-n8n.com/api/v1/workflows
   

4. Ensure n8n API is enabled in settings

❌ "Database file not found"

Symptoms: ENOENT: no such file or directory

Solution:

npm run db:init

❌ "Claude Desktop doesn't see the server"

Symptoms: MCP tools not appearing in Claude

Solutions:

1. Check config file path is correct for your OS
2. Verify JSON syntax is valid (use JSONLint)
3. Use absolute paths (not ~ or ./)
4. Completely quit Claude Desktop (not just close window)
5. Check logs: Claude Desktop → Settings → Developer

❌ "Docker container exits immediately"

Symptoms: Container starts and stops

Solutions:

# Check logs
docker logs n8n-mcp-aurelien

# Verify environment variables
docker inspect n8n-mcp-aurelien

# Ensure database exists in volume
docker volume inspect n8n-mcp-data

❌ "Permission denied" on Docker

Symptoms: Can't run docker commands

Solutions:

# Linux/macOS: Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in

# Or run with sudo (not recommended)
sudo docker run ...

Debug Mode

Enable verbose logging:

# In .env file
LOG_LEVEL=debug

# Or via environment variable
LOG_LEVEL=debug npm start

Getting Help

1. 📖 Check for installation issues
2. 📖 Review for setup guide
3. 🐛 Open an issue on GitHub
4. 📚 Consult MCP Documentation
5. 📚 Review n8n API Docs

🔒 Security

Best Practices

• ✅ Never commit .env files or API keys to Git
• ✅ Use environment variables for all secrets
• ✅ Run containers as non-root user (already configured)
• ✅ Regularly update dependencies: npm audit fix
• ✅ Use HTTPS for n8n API endpoints
• ✅ Rotate API keys periodically

Docker Security

The Dockerfile includes security best practices:

# Non-root user
RUN adduser -S n8nmcp && chown -R n8nmcp /app
USER n8nmcp

# Minimal base image
FROM node:20-alpine

# No unnecessary privileges
# Read-only filesystem where possible

Data Privacy

• 🔐 API keys stored in environment variables only
• 🔐 SQLite database contains only public n8n node/template data
• 🔐 No workflow data or user credentials stored locally
• 🔐 All API calls use secure HTTPS connections

🤝 Contributing

We welcome contributions! See for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'feat: add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Workflow

# Clone your fork
git clone https://github.com/aurelienfagioli/n8n-mcp-aurelien.git
cd n8n-mcp-aurelien

# Install dependencies
npm install

# Create feature branch
git checkout -b feature/my-feature

# Make changes, then test
npm run build
npm run dev

# Commit with conventional commits
git commit -m "feat: add new feature"

# Push and create PR
git push origin feature/my-feature

📜 License

This project is licensed under the MIT License - see the file for details.

MIT License

Copyright (c) 2025 Aurélien Fagioli

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

🙏 Acknowledgments

This project wouldn't exist without:

• n8n — The amazing workflow automation platform
• Anthropic — For Claude and the Model Context Protocol
• czlonkowski/n8n-mcp — Inspiration and reference implementation
• The MCP Community — For building an incredible ecosystem

📊 Project Stats

• 541 n8n nodes with full documentation
• 2700+ workflow templates ready to use
• 12 MCP tools for complete automation
• 100% TypeScript for type safety
• 0 dependencies on proprietary services

🗺️ Roadmap

• 📦 Publish to Docker Hub for one-command installation
• 🔍 Add advanced template filtering (by popularity, rating, etc.)
• 🎨 Web UI for browsing nodes and templates
• 📊 Analytics dashboard for workflow usage
• 🔄 Auto-sync with n8n.io template library
• 🧪 Comprehensive test suite with Vitest
• 📝 Video tutorials and documentation
• 🌐 Multi-language support

📞 Contact & Support

• Author: Aurélien Fagioli
• GitHub: @aurelienfagioli
• Issues: Report a bug
• Discussions: Ask questions