Hermes n8n MCP Plus

Hermes Agent에서 n8n을 관리하기 위한 로컬 stdio MCP 브리지 — 이제 쓰기 도구(write tools) 포함.

CyberSamuraiX/hermes-n8n-mcp의 포크(fork)로, 원래의 읽기 전용/운영 도구 세트 위에 create_workflow, update_workflow, delete_workflow를 추가했습니다. Hermes에 n8n을 공개 인터넷에 노출하지 않고, Hermes 설정에 API 키를 넣지 않으면서도 완전한 n8n 워크플로우 관리를 제공합니다.

제공 기능

다음 MCP 도구를 노출합니다:

• health — n8n API 도달 가능 여부 및 선택적 Docker 컨테이너 상태 확인

• list_workflows — 워크플로우 목록, 선택적으로 활성 상태로 필터링

• get_workflow — 시크릿(secret) 포함 필드를 마스킹하여 워크플로우 하나 조회

• 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(기본값)로 호출하면 어떤 일이 일어날지 미리 보기만 반환하고 n8n을 변경하는 API 호출은 하지 않습니다.

Related MCP server: n8n-ops-mcp

보안 자세

• Stdio 전용. HTTP 서버 없음. 공개 포트 없음.

• API 키는 환경 변수 또는 로컬 dotenv 파일에서 로드됩니다.

• .env는 gitignore 처리됩니다.

• 예제 설정은 실제 키 대신 REPLACE_ME를 사용합니다.

• 도구 응답은 명백한 자격 증명, 토큰, 시크릿, 비밀번호, 권한 부여 필드를 마스킹합니다.

• 실행 페이로드 데이터는 get_execution에서 기본적으로 비활성화되어 있습니다.

• 워크플로우 활성화/비활성화, 생성, 업데이트, 삭제는 모두 프로덕션 변경 작업입니다. 장전된 무기처럼 취급하세요.

• 쓰기 도구는 기본적으로 드라이런 미리 보기로 동작합니다. 호출자가 명시적으로 confirm=true를 전달하지 않는 한 아무것도 생성, 패치, 삭제되지 않습니다.

• delete_workflow는 확인된 삭제가 실행되기 전에 항상 워크플로우의 내보내기/백업 미리 보기를 가져옵니다.

요구 사항

• Python 3.10+

• 네이티브 MCP가 활성화된 Hermes Agent

• n8n API 키

• Hermes를 실행하는 머신에서 n8n에 접근 가능해야 하며, 일반적으로 http://127.0.0.1:5678

중요 종속성 고정: mcp==1.29.0

공식 mcp PyPI 패키지는 2026-07-28에 mcp.server.fastmcp를 완전히 제거하는( MCPServer로 이름 변경, 모듈 경로 이동, httpx를 httpx2로 교체 등) 파괴적인 v2.0.0을 출시했습니다. requirements.txt가 mcp>=1.29.0 같은 느슨한 제약 조건을 사용하면 pip install이 2.0.0을 해석하게 되어 서버가 import 시 다음 오류로 크래시됩니다:

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

이 저장소는 mcp==1.29.0(v2 이전 마지막 안정 릴리스)을 하한이 아닌 하드 핀(hard pin)으로 고정합니다. 코드베이스가 v2 MCPServer API로 마이그레이션될 때까지 이 제약 조건을 느슨하게 하지 마세요. 위 오류가 보이면 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를 로컬에서 교체하세요. 실제 파일을 커밋하지 마세요.

이 포크의 도구는 dotenv 파일뿐만 아니라 환경에서 직접 N8N_API_KEY / N8N_API_URL도 읽으므로, 아래 설명대로 ${N8N_API_KEY} 보간(interpolation)을 사용하여 ~/.hermes/config.yaml에서 직접 주입할 수도 있습니다.

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()))"

그런 다음 Hermes에서 MCP를 다시 로드하세요:

/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 — 각 단계에서 임시 워크플로우를 사용하고 n8n UI에서 확인하세요.

Docker 로그

container_logs는 Docker를 셸로 호출합니다. Hermes를 실행하는 사용자가 Docker에 접근할 수 없으면 다음을 설정하세요:

N8N_MCP_ALLOW_DOCKER_LOGS=false

나머지 API 도구는 계속 작동합니다.

프로덕션 사용 시 참고 사항

• n8n을 역방향 프록시 뒤에서 루프백에 바인딩된 상태로 유지하세요.

• 이 MCP 브리지를 Caddy, nginx 또는 Docker 포트를 통해 노출하지 마세요.

• n8n API 키가 채팅 로그, 터미널, CI 출력, 스크린샷 또는 이슈 트래커에 노출된 적이 있다면 교체하세요.

• 워크플로우를 변경하기 전에 백업하세요. update_workflow와 delete_workflow는 모두 확인 전에 상태를 미리 보여주지만, confirm=true를 전달하기 전에 항상 직접 미리 보기를 확인하세요.

• MCPServer v2 API로 먼저 테스트하지 않고 requirements.txt의 mcp==1.29.0 고정을 느슨하게 만들지 마세요.

로드맵

• v2 API가 안정화되고 이 포크의 도구 세트가 호환성이 검증되면 FastMCP(v1.x)에서 MCPServer(v2.x)로 마이그레이션.

• 수동 실행 트리거를 위한 네 번째 쓰기 도구로 run_workflow 추가 고려.

라이선스

MIT. LICENSE 참조.