Hermes n8n MCP Plus

Локальный stdio MCP-мост для управления n8n из Hermes Agent — теперь с инструментами записи.

Это форк CyberSamuraiX/hermes-n8n-mcp, расширенный инструментами create_workflow, update_workflow и delete_workflow поверх исходного набора инструментов только для чтения/операций. Он даёт Hermes полное управление рабочими процессами n8n без публичного доступа к n8n через интернет и без хранения API-ключей в конфиге Hermes.

Что он делает

Предоставляет следующие MCP-инструменты:

• health — проверка доступности API n8n и, опционально, статуса Docker-контейнера

• list_workflows — список рабочих процессов, опционально с фильтром по состоянию активности

• get_workflow — просмотр одного рабочего процесса с редактированием полей, содержащих секреты

• find_workflows — поиск по метаданным рабочих процессов

• list_executions — список последних выполнений

• get_execution — просмотр одного выполнения; данные полезной нагрузки по умолчанию отключены

• recent_failures — недавние неудачные/ошибочные выполнения

• export_workflow — получение JSON рабочего процесса с редактированием секретов для резервного копирования/просмотра

• activate_workflow — активация рабочего процесса по ID

• deactivate_workflow — деактивация рабочего процесса по ID

• container_logs — опциональные логи Docker с редактированием на уровне строк

• create_workflow — создание нового рабочего процесса из JSON-определения. По умолчанию — пробный запуск (dry-run).

• update_workflow — изменение существующего рабочего процесса по ID (имя, узлы, соединения, настройки, теги). Показывает текущее состояние перед применением. По умолчанию — пробный запуск.

• delete_workflow — окончательное удаление рабочего процесса по ID. Перед удалением показывает экспортную резервную копию. По умолчанию — пробный запуск.

Все три инструмента записи требуют явного аргумента confirm=true для фактического изменения данных. При вызове с confirm=false (по умолчанию) они возвращают предпросмотр того, что произойдёт, и не выполняют ни одного вызова API, изменяющего n8n.

Related MCP server: n8n-ops-mcp

Позиция по безопасности

• Только stdio. Никакого HTTP-сервера. Никаких публичных портов.

• API-ключ загружается из окружения или локального dotenv-файла.

• .env исключён из git.

• Пример конфига использует REPLACE_ME, никогда не реальный ключ.

• Ответы инструментов редактируют очевидные поля с учётными данными, токенами, секретами, паролями и авторизацией.

• Данные полезной нагрузки выполнения по умолчанию отключены в get_execution.

• Активация/деактивация рабочих процессов, создание, обновление и удаление — всё это производственные изменения. Относитесь к ним как к заряженному оружию.

• Инструменты записи по умолчанию работают в режиме пробного предпросмотра; ничего не создаётся, не изменяется и не удаляется, пока вызывающий код явно не передаст confirm=true.

• delete_workflow всегда получает экспортную/резервную копию рабочего процесса перед подтверждённым удалением.

Требования

• Python 3.10+

• Hermes Agent с включённым нативным MCP

• API-ключ n8n

• n8n доступен с машины, на которой запущен Hermes, обычно http://127.0.0.1:5678

Критическая фиксация зависимости: mcp==1.29.0

Официальный PyPI-пакет mcp выпустил ломающий v2.0.0 2026-07-28, который полностью удалил mcp.server.fastmcp (переименован в MCPServer, перемещены пути модулей, httpx заменён на httpx2 и многое другое). Если в requirements.txt используется свободное ограничение вида mcp>=1.29.0, pip install разрешится в 2.0.0, и сервер упадёт при импорте с ошибкой:

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

Этот репозиторий фиксирует mcp==1.29.0 (последний стабильный релиз до v2) как жёсткую фиксацию, а не нижнюю границу. Не ослабляйте это ограничение, пока кодовая база не будет перенесена на v2 API MCPServer. Если вы когда-нибудь увидите ошибку выше, проверьте pip show mcp — если там указано 2.0.0 или новее, выполните:

pip uninstall -y mcp
pip install "mcp==1.29.0"

Установка

git clone https://github.com/csenguttuvan/hermes-n8n-mcp-plus.git
cd hermes-n8n-mcp-plus
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

Проверьте, что установка попала на правильную версию SDK, прежде чем продолжать:

pip show mcp
python -c "from mcp.server.fastmcp import FastMCP; print('OK')"

Сохранение ключа n8n

Ручная версия:

install -d -m 700 ~/.config/n8n-mcp-plus
cat > ~/.config/n8n-mcp-plus/env <<'EOF'
N8N_BASE_URL=http://127.0.0.1:5678
N8N_API_KEY=REPLACE_ME
N8N_MCP_TIMEOUT=30
N8N_CONTAINER_NAME=n8n
N8N_MCP_ALLOW_DOCKER_LOGS=true
EOF
chmod 600 ~/.config/n8n-mcp-plus/env

Замените REPLACE_ME локально. Не коммитьте реальный файл.

Инструменты этого форка также читают N8N_API_KEY / N8N_API_URL напрямую из окружения, а не только из dotenv-файла, так что вы можете альтернативно передавать их прямо из ~/.hermes/config.yaml с помощью интерполяции ${N8N_API_KEY} — см. ниже.

Конфиг Hermes

Добавьте это в ~/.hermes/config.yaml в раздел mcp_servers. Если исходный мост n8n уже зарегистрирован, добавьте это как вторую, отдельную запись (n8n_plus), а не заменяя её — это сохраняет безопасный запасной вариант только для чтения:

mcp_servers:
  n8n:
    command: /Users/admin/.hermes/mcp-installs/n8n/.venv/bin/python
    args:
      - /Users/admin/.hermes/mcp-installs/n8n/server.py
    enabled: true
    env:
      N8N_API_KEY: "${N8N_API_KEY}"
      N8N_API_URL: "http://localhost:5678/api/v1"

  n8n_plus:
    command: /Users/admin/projects/hermes-n8n-mcp-plus/.venv/bin/python
    args:
      - /Users/admin/projects/hermes-n8n-mcp-plus/server.py
    enabled: true
    env:
      N8N_API_KEY: "${N8N_API_KEY}"
      N8N_API_URL: "http://localhost:5678/api/v1"

Отступы важны. Оба ключа n8n: и n8n_plus: должны находиться на одном уровне отступа, непосредственно под mcp_servers:, без каких-либо других ключей верхнего уровня, разрывающих блок между ними. Проверьте, что файл корректно парсится перед перезагрузкой:

python3 -c "import yaml; d = yaml.safe_load(open('/Users/admin/.hermes/config.yaml')); print(list(d.get('mcp_servers', {}).keys()))"

Затем перезагрузите MCP в Hermes:

/reload-mcp

Или из оболочки:

hermes mcp test n8n_plus

Инструменты регистрируются с префиксом имени сервера, например mcp__n8n_plus__create_workflow, mcp__n8n_plus__health, в отличие от инструментов mcp__n8n__* исходного моста, если оба работают бок о бок.

Быстрая проверка вне Hermes

. .venv/bin/activate
python -m py_compile server.py
python -c "import server; print('imported OK')"
hermes mcp test n8n_plus

Если import server зависает или выдаёт ModuleNotFoundError: No module named 'mcp.server.fastmcp', перепроверьте фиксацию mcp==1.29.0 выше — это почти всегда проблема версии зависимости, а не кода.

Использование инструментов записи

Все три инструмента записи следуют одному и тому же шаблону «пробный запуск по умолчанию». Пример потока для create_workflow:

Call mcp__n8n_plus__create_workflow with workflow={"name": "test", "nodes": [], "connections": {}} and confirm=false.

Возвращает предпросмотр, без изменений:

{
  "ok": false,
  "error": "Dry run only. Set confirm=true to create the workflow.",
  "workflow_preview": { "name": "test", "nodes": [], "connections": {} }
}

Когда предпросмотр выглядит правильно, повторите с confirm=true, чтобы фактически создать. Тот же шаблон применяется к update_workflow (показывает текущее состояние и предлагаемый патч) и delete_workflow (показывает экспортную резервную копию перед удалением).

Рекомендуемый порядок тестирования для любого нового окружения: create_workflow, затем list_workflows для подтверждения создания, затем update_workflow, затем delete_workflow — каждый с одноразовым рабочим процессом, проверяемым в UI n8n на каждом шаге.

Логи Docker

container_logs обращается к Docker через оболочку. Если пользователь, запускающий Hermes, не имеет доступа к Docker, установите:

N8N_MCP_ALLOW_DOCKER_LOGS=false

Остальные API-инструменты продолжат работать.

Заметки для производственного использования

• Держите n8n привязанным к loopback за вашим обратным прокси.

• Не открывайте этот MCP-мост через Caddy, nginx или Docker-порты.

• Ротируйте API-ключи n8n, если они когда-либо попадали в логи чатов, терминалы, вывод CI, скриншоты или трекеры задач.

• Делайте резервные копии рабочих процессов перед их изменением. update_workflow и delete_workflow оба показывают состояние перед подтверждением, но всегда проверяйте предпросмотр сами, прежде чем передавать confirm=true.

• Никогда не ослабляйте фиксацию mcp==1.29.0 в requirements.txt без предварительного тестирования с v2 API MCPServer.

План развития

• Миграция с FastMCP (v1.x) на MCPServer (v2.x), когда v2 API стабилизируется и набор инструментов этого форка будет проверен на совместимость.

• Рассмотреть добавление run_workflow как четвёртого инструмента записи для ручных триггеров выполнения.

Лицензия

MIT. См. LICENSE.