Hermes n8n MCP Plus

Puente MCP stdio local para gestionar n8n desde Hermes Agent — ahora con herramientas de escritura.

Esto es un fork de CyberSamuraiX/hermes-n8n-mcp, ampliado con create_workflow, update_workflow y delete_workflow además del conjunto original de herramientas de solo lectura/operaciones. Le da a Hermes una gestión completa de flujos de trabajo de n8n sin exponer n8n a través de internet público y sin poner claves de API en la configuración de Hermes.

Qué hace

Expone estas herramientas MCP:

• health — comprueba la accesibilidad de la API de n8n y el estado opcional del contenedor Docker

• list_workflows — lista flujos de trabajo, opcionalmente filtrados por estado activo

• get_workflow — inspecciona un flujo de trabajo con los campos que contienen secretos redactados

• find_workflows — busca metadatos de flujos de trabajo

• list_executions — lista ejecuciones recientes

• get_execution — inspecciona una ejecución; los datos del payload están desactivados por defecto

• recent_failures — ejecuciones recientes fallidas/erróneas

• export_workflow — obtiene el JSON redactado del flujo de trabajo para copia de seguridad o revisión

• activate_workflow — activa un flujo de trabajo por ID

• deactivate_workflow — desactiva un flujo de trabajo por ID

• container_logs — registros de Docker opcionales con redacción a nivel de línea

• create_workflow — crea un nuevo flujo de trabajo a partir de una definición JSON. Dry-run por defecto.

• update_workflow — parchea un flujo de trabajo existente por ID (nombre, nodos, conexiones, configuración, etiquetas). Muestra una vista previa del estado actual antes de aplicar. Dry-run por defecto.

• delete_workflow — elimina permanentemente un flujo de trabajo por ID. Muestra una vista previa de una copia de seguridad exportada antes de eliminar. Dry-run por defecto.

Las tres herramientas de escritura requieren un argumento explícito confirm=true para mutar realmente cualquier cosa. Si se llaman con confirm=false (el valor por defecto), devuelven una vista previa de lo que ocurriría y no hacen ninguna llamada a la API que modifique n8n.

Related MCP server: n8n-ops-mcp

Postura de seguridad

• Solo stdio. Sin servidor HTTP. Sin puerto público.

• La clave de API se carga desde el entorno o desde un archivo dotenv local.

• .env está en gitignore.

• La configuración de ejemplo usa REPLACE_ME, nunca una clave real.

• Las respuestas de las herramientas redactan los campos evidentes de credenciales, tokens, secretos, contraseñas y autorización.

• Los datos del payload de ejecución están desactivados por defecto en get_execution.

• La activación/desactivación, creación, actualización y eliminación de flujos de trabajo son mutaciones de producción. Trátalas como armas cargadas.

• Las herramientas de escritura usan por defecto una vista previa dry-run; no se crea, parchea ni elimina nada a menos que quien llama pase explícitamente confirm=true.

• delete_workflow siempre obtiene una vista previa de exportación/copia de seguridad del flujo de trabajo antes de que se ejecute una eliminación confirmada.

Requisitos

• Python 3.10+

• Hermes Agent con MCP nativo habilitado

• Clave de API de n8n

• n8n accesible desde la máquina que ejecuta Hermes, normalmente http://127.0.0.1:5678

Fijación de dependencia crítica: mcp==1.29.0

El paquete oficial mcp de PyPI publicó una v2.0.0 incompatible el 2026-07-28 que eliminó mcp.server.fastmcp por completo (renombrado a MCPServer, movió las rutas de los módulos, sustituyó httpx por httpx2, entre otros cambios). Si requirements.txt usa una restricción flexible como mcp>=1.29.0, pip install resolverá a 2.0.0 y el servidor fallará al importarse con:

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

Este repositorio fija mcp==1.29.0 (la última versión estable anterior a la v2) como una fijación estricta, no como un mínimo. No aflojes esta restricción hasta que el código se migre a la API v2 de MCPServer. Si alguna vez ves el error anterior, comprueba pip show mcp — si indica 2.0.0 o más reciente, ejecuta:

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

Instalación

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

Verifica que la instalación haya dejado la versión correcta del SDK antes de continuar:

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

Guarda tu clave de n8n

Versión manual:

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

Reemplaza REPLACE_ME localmente. No confirmes el archivo real.

Las herramientas de este fork también leen N8N_API_KEY / N8N_API_URL directamente del entorno, no solo de un archivo dotenv, así que también puedes inyectarlas directamente desde ~/.hermes/config.yaml usando la interpolación ${N8N_API_KEY} — ver más abajo.

Configuración de Hermes

Añade esto a ~/.hermes/config.yaml bajo mcp_servers. Si el puente original n8n ya está registrado, añade esto como una segunda entrada separada (n8n_plus) en lugar de reemplazarlo — esto mantiene disponible una alternativa segura de solo lectura:

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"

La sangría importa. Tanto n8n: como n8n_plus: deben estar al mismo nivel de sangría, directamente bajo mcp_servers:, sin que ninguna otra clave de nivel superior interrumpa el bloque entre medias. Valida que el archivo se analiza correctamente antes de recargar:

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

Luego recarga MCP en Hermes:

/reload-mcp

O desde la shell:

hermes mcp test n8n_plus

Las herramientas se registran con el prefijo del nombre del servidor, p. ej. mcp__n8n_plus__create_workflow, mcp__n8n_plus__health, distintas de las herramientas mcp__n8n__* del puente original si ambos se ejecutan en paralelo.

Smoke test fuera de Hermes

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

Si import server se bloquea o lanza ModuleNotFoundError: No module named 'mcp.server.fastmcp', revisa de nuevo la fijación mcp==1.29.0 anterior — esto casi siempre es un problema de versión de dependencias, no de código.

Uso de las herramientas de escritura

Las tres herramientas de escritura siguen el mismo patrón de dry-run por defecto. Ejemplo de flujo para create_workflow:

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

Devuelve una vista previa, sin mutación:

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

Una vez que la vista previa se vea correcta, vuelve a ejecutarlo con confirm=true para crearlo de verdad. El mismo patrón se aplica a update_workflow (muestra una vista previa del estado actual y del parche propuesto) y a delete_workflow (muestra una vista previa de una copia de seguridad exportada antes de eliminar).

Orden de pruebas recomendado para cualquier entorno nuevo: create_workflow, luego list_workflows para confirmar que se creó, después update_workflow y finalmente delete_workflow — cada uno con un flujo de trabajo desechable, verificado contra la interfaz de n8n en cada paso.

Registros de Docker

container_logs ejecuta Docker desde la shell. Si el usuario que ejecuta Hermes no puede acceder a Docker, configura:

N8N_MCP_ALLOW_DOCKER_LOGS=false

El resto de herramientas de la API seguirán funcionando.

Notas para uso en producción

• Mantén n8n vinculado a loopback detrás de tu proxy inverso.

• No expongas este puente MCP a través de Caddy, nginx ni puertos de Docker.

• Rota las claves de API de n8n si alguna vez aparecen en registros de chat, terminales, salida de CI, capturas de pantalla o rastreadores de incidencias.

• Haz copias de seguridad de los flujos de trabajo antes de mutarlos. Tanto update_workflow como delete_workflow muestran una vista previa del estado antes de confirmar, pero comprueba siempre la vista previa tú mismo antes de pasar confirm=true.

• No aflojes nunca la fijación mcp==1.29.0 en requirements.txt sin probar antes contra la API v2 de MCPServer.

Hoja de ruta

• Migrar de FastMCP (v1.x) a MCPServer (v2.x) una vez que la API v2 se estabilice y el conjunto de herramientas de este fork se verifique como compatible.

• Considerar añadir run_workflow como cuarta herramienta de escritura para disparadores de ejecución manual.

Licencia

MIT. Consulta LICENSE.