MCP n8n Server

Управляйте n8n и создавайте в нём процессы прямо из Cursor или Claude — администрирование вашего инстанса (пользователи, проекты, выполнения, аудит) и полный цикл конструирования: каталог из 560 узлов с реальными схемами параметров, извлечённых из официальных пакетов n8n, проверка перед сохранением, автоматическое исправление, снимки с откатом и сравнением, отладка выполнения по каждому узлу, отчёты о состоянии и полное резервное копирование инстанса.

Две переменные окружения. Работает на вашей машине (stdio) или как удалённый HTTP-сервер. Не требуется облачная учётная запись.

🎯 Оптимизация токенов

Этот сервер оптимизирован для минимизации потребления токенов, что решает одну из самых больших проблем MCP-серверов — чрезмерное использование токенов API.

Что мы оптимизировали:

• Снижение расхода токенов на 90% при выводе списка рабочих процессов с помощью нового эндпоинта n8n_list_workflows_summary

• Фильтрация полей — запрашивайте только нужные данные

• Умные значения по умолчанию — уменьшено со 100 до 10-20 результатов на запрос

• Интеллектуальные предупреждения — уведомления, когда операции будут потреблять значительное количество токенов

Подробное руководство по использованию см. в TOKEN_OPTIMIZATION.md.

Related MCP server: n8n Workflow Builder

✨ Возможности

🔄 Управление рабочими процессами

• Создание и развёртывание: создавайте рабочие процессы с помощью описаний на естественном языке

• CRUD-операции: полное управление жизненным циклом (создание, чтение, обновление, удаление)

• Управление активацией: включайте и отключайте рабочие процессы по требованию

• Перенос между проектами: легко перемещайте рабочие процессы между проектами

• Управление тегами: организуйте рабочие процессы с помощью пользовательских тегов

📊 Мониторинг выполнений

• Отслеживание в реальном времени: мониторинг выполнений рабочих процессов с расширенными фильтрами

• Детальная аналитика: доступ к полным данным и журналам выполнения

• Восстановление после ошибок: автоматический повтор неудачных выполнений

• Инструменты очистки: эффективное управление историей выполнений

🔐 Управление учётными данными

• Безопасное создание: добавляйте учётные данные для любого сервиса

• Обнаружение схем: автоматическое определение обязательных полей для типов учётных данных

• Изоляция проектов: безопасный перенос учётных данных между проектами

• Поддержка типов: совместимость со всеми типами учётных данных n8n

🧱 Конструктор рабочих процессов

• Полный каталог узлов — 560 узлов с реальными схемами: извлекается напрямую из n8n-nodes-base и @n8n/n8n-nodes-langchain (параметры с типами, допустимыми значениями, условиями отображения, учётными данными, актуальной typeVersion), еженедельно пересоздаётся CI. Поиск с помощью n8n_search_nodes, просмотр с помощью n8n_get_node

• Реальная проверка: n8n_validate_workflow проверяет по реальным схемам — несуществующие типы узлов, отсутствующие обязательные параметры (включая условно обязательные), недопустимые значения опций, неверная typeVersion, повреждённые соединения — до сохранения/активации

• Проверка выражений: обнаруживает выражения {{ }} без префикса = и ссылки на узлы, которых нет в рабочем процессе

• Автоматическое исправление: n8n_autofix_workflow исправляет отсутствующие typeVersion/позиции, дублирующиеся имена, оборванные соединения и префиксы выражений — сначала предпросмотр, затем применение со снимком

• Точечные правки: n8n_update_workflow_partial добавляет/удаляет узлы и соединения без перезаписи всего процесса

• Публичные шаблоны: поиск и импорт с n8n.io (n8n_search_public_templates, n8n_import_public_template), плюс 100 встроенных шаблонов в качестве запасного варианта

• Направляющие промпты: MCP-промпты build-workflow и fix-workflow проводят любого агента через полный цикл создания/проверки/тестирования/исправления

🔬 Глубокая отладка и состояние

• Данные выполнения по узлам: n8n_get_node_execution_data показывает, какие именно данные прошли через один узел (статус, количество элементов, примеры выводов, сведения об ошибках) без загрузки всего выполнения

• Цикл отладки: n8n_debug_last_error возвращает узел, в котором произошла ошибка, и сообщение из последней ошибки

• Отчёты о состоянии: n8n_workflow_health вычисляет процент успешных выполнений, количество сбоев, среднюю длительность и время последнего сбоя по каждому рабочему процессу на основе недавних выполнений, отсортированных от худших к лучшим

🛡️ Страховочная сеть и реальное тестирование

• Автоматические снимки: перед каждым обновлением, точечным изменением, автопоиском исправлений или удалением предыдущее состояние сохраняется локально (~/.mcp-n8n/snapshots, настраивается через N8N_SNAPSHOT_DIR)

• Откат: n8n_rollback_workflow восстанавливает любой снимок — вплоть до воссоздания удалённого рабочего процесса (recreate=true)

• Сравнение: n8n_diff_workflow_snapshot сравнивает снимок с текущим состоянием (добавленные/удалённые/изменённые узлы, изменённые параметры, изменения соединений) перед принятием решения об откате

• Полное резервное копирование инстанса: n8n_export_all_workflows сохраняет каждый рабочий процесс в виде JSON-файлов; n8n_import_workflows восстанавливает их

• Сквозное тестирование: n8n_trigger_webhook вызывает рабочий процесс с триггером Webhook на инстансе и возвращает реальный HTTP-ответ, чтобы агент мог убедиться, что процесс действительно работает

🎯 Встроенные шаблоны

• 100 локальных отправных точек с поиском по ключевым словам, если вы предпочитаете не обращаться к n8n.io

🏗️ Организация и администрирование

• Теги: категоризация и организация ресурсов

• Переменные: централизованное управление переменными окружения

• Проекты: поддержка мультитенантных проектов

• Пользователи и права: полное управление контролем доступа

• Журналы аудита: формирование отчётов по безопасности и соответствию требованиям

🚀 Быстрый старт

Установка через npm (рекомендуется)

Это самый простой способ начать:

npm install -g mcp-n8n

Настройка

1. Получите учётные данные n8n API:

   • Перейдите в свой инстанс n8n → Settings → n8n API

   • Создайте новый API-ключ

2. Настройте Claude Desktop:

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (Mac/Linux) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

Вариант A — с использованием глобальной установки (если вы выполнили npm install -g mcp-n8n):

{
  "mcpServers": {
    "n8n": {
      "command": "mcp-n8n",
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here",
        "N8N_TOOLSETS": "all"
      }
    }
  }
}

N8N_TOOLSETS необязателен (по умолчанию all). Используйте core,builder, если нужны операции + создание без инструментов администрирования пользователей/проектов. Используйте admin только для администрирования инстанса.

Удалённый HTTP-режим (необязательно)

По умолчанию сервер обменивается данными через stdio (локально). Чтобы запустить его как общий удалённый сервер (например, в Docker или на VPS), укажите порт:

N8N_BASE_URL=https://your-n8n-instance.com \
N8N_API_KEY=your-api-key \
N8N_MCP_HTTP_PORT=3000 \
N8N_MCP_HTTP_TOKEN=some-strong-secret \
mcp-n8n

Это открывает протокол MCP через потоковый HTTP на порту 3000, а также эндпоинт GET /health. Настоятельно рекомендуется задать N8N_MCP_HTTP_TOKEN: если он задан, каждый запрос должен содержать Authorization: Bearer <token>. Направьте любой MCP-клиент, поддерживающий потоковый HTTP, на http://your-host:3000 с этим заголовком.

Вариант B — с помощью npx (установка не требуется, всегда последняя версия):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Настройте Cursor:

Добавьте в настройки MCP в Cursor (Settings → Extensions → MCP):

Рекомендуется — с помощью npx (всегда используется последняя версия):

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "mcp-n8n"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Примечание: Cursor требует использования npx для MCP-серверов. Флаг -y автоматически устанавливает/обновляет пакет без запросов.

Вариант C — Docker:

docker build -t mcp-n8n .

{
  "mcpServers": {
    "n8n": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "N8N_BASE_URL", "-e", "N8N_API_KEY",
        "-v", "mcp-n8n-data:/data",
        "mcp-n8n"
      ],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Том /data сохраняет снимки рабочих процессов между запусками.

4. Перезапустите Claude Desktop или Cursor

💬 Примеры использования

После настройки взаимодействуйте с n8n на естественном языке:

Создание рабочих процессов

"Create a workflow that monitors my Gmail inbox and sends
Slack notifications for important emails"

"Build a daily report workflow that pulls data from my database,
generates charts, and emails them to my team"

Использование шаблонов

"I need a WhatsApp chatbot with AI for customer support"
→ Automatically creates workflow from "WhatsApp AI Response Bot" template

"Create an automated stock analysis workflow"
→ Uses "Automated Stock Analysis with GPT-4" template

Управление рабочими процессами

"Show me all active workflows in the production project"
→ Uses n8n_list_workflows_summary for efficient token usage

"Show me the details of workflow abc123"
→ Uses n8n_get_workflow to fetch complete details only when needed

"Deactivate the 'Daily Backup' workflow"

"What went wrong with execution abc123?"

Мониторинг и отладка

"Show me the last 10 failed executions"

"Retry all failed executions from workflow xyz456"

"Delete all successful executions older than 30 days"

🛠️ Доступные инструменты

• n8n_create_workflow — создание новых рабочих процессов (с предварительной проверкой)

• n8n_list_workflows_summary — экономичный по токенам список

• n8n_list_workflows — полные сведения с необязательной фильтрацией полей

• n8n_get_workflow — полный JSON рабочего процесса

• n8n_update_workflow — замена полей (опущенные поля сохраняют текущие значения)

• n8n_update_workflow_partial — точечные правки: добавление/удаление узлов и соединений

• n8n_delete_workflow — окончательное удаление рабочих процессов

• n8n_activate_workflow / n8n_deactivate_workflow

• n8n_transfer_workflow / инструменты тегов

• n8n_list_workflow_snapshots — локальная история всех изменений, сделанных через этот сервер

• n8n_rollback_workflow — восстановление предыдущей версии или воссоздание удалённого рабочего процесса

• n8n_diff_workflow_snapshot — сравнение снимка с текущим состоянием перед откатом

• n8n_trigger_webhook — вызов webhook-рабочего процесса и получение реального ответа

• n8n_export_all_workflows / n8n_import_workflows — полное резервное копирование и восстановление инстанса

• n8n_search_nodes / n8n_get_node — полный каталог: 560 узлов с реальными схемами параметров

• n8n_validate_workflow — проверка JSON по реальным схемам перед сохранением/активацией

• n8n_autofix_workflow — механические исправления: typeVersion, позиции, дубликаты, оборванные соединения, префиксы выражений

• n8n_search_public_templates / n8n_import_public_template — официальная библиотека n8n.io

• n8n_list_workflow_templates / n8n_get_workflow_template / n8n_create_workflow_from_template — встроенные шаблоны

100 встроенных шаблонов в 13 категориях:

• Электронная коммерция: автоматизация Shopify, агенты поддержки WooCommerce

• Социальные сети: автоматизация Instagram, TikTok, LinkedIn, Twitter

• ИИ/чаты: чат-боты, ИИ-агенты, голосовые ассистенты

• Коммуникации: автоматизация WhatsApp, Telegram, Email

• Контент: автоматизация блогов, генерация видео, SEO-оптимизация

• HR/рекрутинг: отбор резюме, поиск кандидатов

• Продажи/CRM: генерация лидов, пайплайны холодных звонков

• Финансы: анализ акций, извлечение счетов

• Сбор данных: Google Maps, LinkedIn, Amazon, TikTok

• Мониторинг: аптайм сайтов, отслеживание конкурентов

• Продуктивность: календарь, Notion, автоматизация планирования

• n8n_list_executions — фильтрация по статусу, рабочему процессу, проекту

• n8n_get_execution — детальные данные выполнения

• n8n_delete_execution — удаление записей о выполнениях

• n8n_retry_execution — повтор неудачных выполнений

• n8n_debug_last_error — узел с ошибкой + сообщение из последней ошибки

• n8n_get_node_execution_data — данные, которые прошли через конкретный узел

• n8n_workflow_health — процент успеха, сбои и длительность по каждому рабочему процессу

• n8n_create_credential — добавление новых учётных данных

• n8n_delete_credential — удаление учётных данных (только владелец)

• n8n_get_credential_schema — определение обязательных полей

• n8n_transfer_credential — перемещение между проектами

Теги: создание, список, получение, обновление, удаление Переменные: создание, список, обновление, удаление Пользователи: список, создание, получение, удаление, смена роли Проекты: создание, список, обновление, удаление, управление пользователями

• n8n_generate_audit — отчёты по аудиту безопасности

• n8n_pull_source_control — интеграция с системой контроля версий

61 инструмент по умолчанию (N8N_TOOLSETS=all). core,builder предоставляет 28. Плюс 2 MCP-промпта (build-workflow, fix-workflow).

📚 Документация

• Быстрый старт — начните работу за 5 минут

• Примеры и сценарии использования — реальные примеры автоматизации

• Справочник инструментов — подробная документация по инструментам

• Журнал изменений — история версий и обновления

🏗️ Структура проекта

mcp-n8n/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── n8n-client.ts     # n8n API client
│   └── types.ts          # TypeScript definitions
├── examples/
│   ├── templates-metadata.json
│   └── *.json            # Pre-built workflow templates
├── dist/                 # Compiled output
├── QUICKSTART.md         # Quick start guide
├── EXAMPLES.md           # Usage examples
├── NODE_REFERENCE.md     # API documentation
└── package.json

🔧 Разработка

Локальная установка (для разработки)

Если вы хотите внести вклад или протестировать локальные изменения:

1. Настройка

# Clone repository
git clone https://github.com/leonardosepulvedat/mcp-n8n.git
cd mcp-n8n

# Install dependencies
npm install

# Build
npm run build

# Development with auto-rebuild
npm run watch

2. Настройка с локальной сборкой

Для Claude Desktop добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Для Cursor добавьте в настройки MCP:

{
  "mcpServers": {
    "n8n": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-n8n/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Важно: Замените /absolute/path/to/mcp-n8n/ на фактический абсолютный путь к вашему клонированному репозиторию (например, /Users/yourname/projects/mcp-n8n/).

3. Тестирование

# Set environment variables
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
node dist/index.js

Как запустить

Чтобы запустить основной скрипт, выполните:

python main.py

Как тестировать

Чтобы запустить тесты, выполните:

pytest test_main.py

📋 Требования

• Node.js: 20 или выше

• Экземпляр n8n: Self-hosted или n8n Cloud (платный тариф)

• API-ключ n8n: Требуется для аутентификации

• AI IDE: Claude Desktop или Cursor с поддержкой MCP

Требования к n8n

• Self-hosted: Полный доступ к API ✅

• n8n Cloud: Требуется платный тариф для доступа к API

• Версия: Совместимо с n8n v1.0.0+

🤝 Вклад в проект

Вклад приветствуется! Не стесняйтесь отправлять Pull Request.

1. Сделайте форк репозитория

2. Создайте свою ветку функции (git checkout -b feature/AmazingFeature)

3. Зафиксируйте свои изменения (git commit -m 'Add some AmazingFeature')

4. Отправьте в ветку (git push origin feature/AmazingFeature)

5. Откройте Pull Request

📝 Лицензия

Этот проект лицензирован под лицензией MIT — подробности в файле LICENSE.

🙏 Благодарности

• n8n — платформа автоматизации рабочих процессов

• Anthropic — Claude и Model Context Protocol

• Cursor — редактор кода на базе ИИ

🔗 Ресурсы

• Документация по API n8n

• Model Context Protocol

• Сообщество n8n

• Реестр MCP-серверов

⚠️ Важные примечания

Доступ к API

• n8n Cloud требует платный тариф для доступа к API

• Self-hosted n8n имеет полный доступ к API на всех тарифах

• Некоторые операции требуют прав владельца/администратора

Безопасность

• Никогда не коммитьте файлы .env с учётными данными

• Используйте переменные окружения для конфиденциальных данных

• API-ключи предоставляют полный доступ к вашему экземпляру n8n

• Регулярно меняйте API-ключи для безопасности

Ограничение частоты запросов

• Соблюдайте лимиты частоты запросов API n8n

• Используйте пагинацию для больших наборов результатов

• Реализуйте обработку ошибок для ответов с ограничением частоты

🐛 Устранение неполадок

Проблемы с подключением

Проблема: «Не удаётся подключиться к API n8n»

• Проверьте, что N8N_BASE_URL корректен и доступен

• Проверьте, что API-ключ действителен

• Убедитесь, что экземпляр n8n запущен

Ошибки с правами

Проблема: «Недостаточно прав»

• Некоторые операции требуют роли владельца/администратора

• Проверьте, что у вашего пользователя есть соответствующие права

• Проверьте права доступа на уровне проекта

Проблемы с шаблонами

Проблема: «Шаблон не найден»

• Убедитесь, что каталог examples/ присутствует

• Проверьте, что templates-metadata.json существует

• Проверьте, что ссылки на файлы шаблонов корректны

💡 Советы и лучшие практики

1. Начните с шаблонов: Используйте готовые шаблоны как отправную точку

2. Используйте теги: Организуйте рабочие процессы с тегами для удобного управления

3. Отслеживайте выполнения: Регулярно проверяйте неудачные выполнения

4. Очистка: Удаляйте старые данные выполнения для экономии места

5. Контроль версий: Используйте встроенные функции контроля версий n8n

6. Сначала тестируйте: Тестируйте рабочие процессы перед активацией в продакшене

📧 Поддержка

• Проблемы: GitHub Issues

• Обсуждения: GitHub Discussions

• Сообщество n8n: community.n8n.io

⬆ Наверх