by leonardosepulvedat (community) · Claude Desktop, Claude Code, OpenCode, Cursor, Node.js, n8n, Windows, macOS, Linux

показать оригинал переведено ИИ

MCP n8n Server

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

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

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

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

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

Сокращение на 90% токенов для списка рабочих процессов с новым конечной точкой n8n_list_workflows_summary
Фильтрация полей — запрашивайте только те данные, которые вам нужны
Умные значения по умолчанию — сокращение с 100 до 10-20 результатов на запрос
Интеллектуальные предупреждения — оповещения, когда операции будут потреблять значительное количество токенов

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

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

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

Создание и развёртывание: Создавайте рабочие процессы с помощью описаний на естественном языке
Операции 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/positions, дублирующиеся имена, висячие соединения и префиксы выражений — предварительный просмотр, применение с помощью снимка
Хирургические правки: 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

Конфигурация

Получите учётные данные API n8n:
- Перейдите в свой экземпляр n8n → Настройки → API n8n
- Сгенерируйте новый ключ API
Настройте 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"
      }
    }
  }
}

Настройте Cursor:

Добавьте в настройки MCP Cursor (Настройки → Расширения → 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 сохраняет снимки рабочих процессов между запусками.

Перезапустите 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 — Вызов вебхука рабочего процесса и получение реального ответа
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, автоматизация планирования

Выполнения (4 инструмента)

n8n_list_executions — Фильтрация по статусу, рабочему процессу, проекту
n8n_get_execution — Детальные данные выполнения
n8n_delete_execution — Удаление записей выполнения
n8n_retry_execution — Повторное выполнение неудачных запусков
n8n_debug_last_error — Неисправный узел + сообщение из последней ошибки
n8n_get_node_execution_data — Данные, прошедшие через конкретный узел
n8n_workflow_health — Уровень успешности, сбои и продолжительность по рабочему процессу

Учётные данные (4 инструмента)

n8n_create_credential — Добавление новых учётных данных
n8n_delete_credential — Удаление учётных данных (только для владельца)
n8n_get_credential_schema — Определение требуемых полей
n8n_transfer_credential — Перемещение между проектами

Организация (19 инструментов)

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

Расширенные возможности (2 инструмента)

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.

Форкните репозиторий
Создайте ветку для вашей функции (git checkout -b feature/УдивительнаяФункция)
Зафиксируйте изменения (git commit -m 'Добавлена УдивительнаяФункция')
Отправьте ветку в репозиторий (git push origin feature/УдивительнаяФункция)
Откройте Pull Request

📝 Лицензия

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

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

n8n — Платформа для автоматизации рабочих процессов
Anthropic — Claude и протокол Model Context Protocol
Cursor — Редактор кода с поддержкой ИИ

🔗 Ресурсы

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

Доступ к API

Для n8n Cloud требуется платный тариф для доступа к API
При самостоятельном хостинге n8n полный доступ к API предоставляется на всех тарифах
Некоторые операции требуют прав владельца/администратора

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

Никогда не коммитьте файлы .env с учётными данными
Используйте переменные окружения для конфиденциальных данных
API-ключи предоставляют полный доступ к вашему экземпляру n8n
Регулярно обновляйте API-ключи для безопасности

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

Соблюдайте ограничения частоты запросов API n8n
Используйте пагинацию для больших наборов результатов
Реализуйте обработку ошибок для ответов с ограничением частоты запросов

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

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

Проблема: "Не удаётся подключиться к API n8n" - Проверьте правильность и доступность N8N_BASE_URL - Убедитесь, что API-ключ действителен - Проверьте, запущен ли экземпляр n8n

Ошибки прав доступа

Проблема: "Недостаточно прав" - Некоторые операции требуют роли владельца/администратора - Убедитесь, что у вашего пользователя есть соответствующие права - Проверьте права доступа на уровне проекта

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

Проблема: "Шаблон не найден" - Убедитесь, что присутствует каталог examples/ - Проверьте наличие файла templates-metadata.json - Убедитесь, что ссылки на файлы шаблонов корректны

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

Начинайте с шаблонов: Используйте готовые шаблоны как отправную точку
Используйте теги: Организуйте рабочие процессы с помощью тегов для удобного управления
Мониторьте выполнение: Регулярно проверяйте неудачные выполнения
Очистка: Удаляйте старые данные выполнения для экономии места
Контроль версий: Используйте встроенные функции контроля версий n8n
Сначала тестируйте: Проверяйте рабочие процессы перед активацией в продакшене

📧 Поддержка

Проблемы: GitHub Issues
Обсуждения: GitHub Discussions
Сообщество n8n: community.n8n.io

⬆ Наверх