HRJ n8n MCP

Local stdio MCP bridge for managing n8n from HRJ Agent.

This is the sanitized public version of the bridge built for a production VPS. It gives HRJ n8n tools without exposing n8n over the public internet and without putting API keys in your HRJ config.

What it does

Exposes these MCP tools:

Health & Info (Safe — Read Only)

Workflows — Read (Safe)

Workflows — Write (PROTECTED)

Executions (Safe — Read Only)

Docker (Safe — Read Only)

Related MCP server: mcp-n8n-builder

Security posture

• Stdio only. No HTTP server. No public port.

• API key is loaded from environment or a local dotenv file.

• .env is gitignored.

• Example config uses REPLACE_ME, never a real key.

• Tool responses redact obvious credential, token, secret, password, and authorization fields.

• Execution payload data is disabled by default in get_execution.

• Write tools are disabled by default — only read tools are enabled unless you explicitly enable them.

• Destructive operations require human CLI confirmation — tokens are generated via interactive script, not by AI.

• Audit logging — all write operations are logged to ~/.config/n8n-mcp/logs/audit.log (append-only).

• Automatic retry on transient 5xx errors and connection failures.

Tool enablement (recommended)

By default, only read-only tools are enabled. This follows the principle of least privilege — write tools must be explicitly enabled.

To enable write tools, add them to your HRJ config:

mcp_servers:
  n8n:
    # ... basic config ...
    tools:
      default_enabled:
        - health
        - list_workflows
        - get_workflow
        - find_workflows
        - list_executions
        - get_execution
        - recent_failures
        - export_workflow
        - container_logs
        - container_status
      # Enable write tools only when needed:
      # - create_workflow
      # - update_workflow
      # - delete_workflow
      # - activate_workflow
      # - deactivate_workflow

Destructive operations protection

For delete_workflow, activate_workflow, and deactivate_workflow, two layers of protection are required:

Layer 1: Environment variable (server-side)

Set in your ~/.config/n8n-mcp/env:

# For delete operations (KEEP FALSE UNLESS NEEDED)
N8N_MCP_ALLOW_DELETE=false

# For activate/deactivate operations (KEEP FALSE UNLESS NEEDED)
N8N_MCP_ALLOW_ACTIVATE=false

Important: Only set these to true temporarily when you need to perform the operation, then set them back to false.

Layer 2: Human confirmation token (CLI)

Even with the env flag enabled, you must generate a confirmation token via the interactive CLI script:

# For delete
./scripts/confirm-action.sh delete 123

# For activate
./scripts/confirm-action.sh activate 123

# For deactivate
./scripts/confirm-action.sh deactivate 123

The script will:

1. Display a clear warning about the action

2. Ask you to type YES to confirm

3. Generate a time-limited token (120 seconds)

4. The MCP server consumes this token when you call the tool

Why this is secure:

• The token is generated by a separate CLI process, not by the AI

• The AI cannot generate tokens — it requires interactive human input

• Tokens expire after 120 seconds

• Tokens are single-use (deleted after validation)

• Tokens are stored with restrictive permissions (600)

Example workflow

# 1. Enable delete temporarily
export N8N_MCP_ALLOW_DELETE=true

# 2. Generate confirmation token (interactive)
./scripts/confirm-action.sh delete 123
# Type: YES

# 3. Use the MCP tool (token is consumed automatically)
# The AI calls: delete_workflow(workflow_id="123")

# 4. Disable delete immediately
export N8N_MCP_ALLOW_DELETE=false

Audit logging

All operations are logged to ~/.config/n8n-mcp/logs/audit.log:

{"action": "DELETE_BLOCKED", "workflow_id": "123", "timestamp": "2026-07-28T21:30:00+00:00", "reason": "N8N_MCP_ALLOW_DELETE=false"}
{"action": "TOKEN_VALIDATED", "workflow_id": "123", "timestamp": "2026-07-28T21:35:00+00:00", "action": "delete"}
{"action": "DELETE_WORKFLOW", "workflow_id": "123", "timestamp": "2026-07-28T21:35:01+00:00", "status": "success"}

The log file is append-only — entries cannot be deleted or modified without root access.

Requirements

• Python 3.10+

• HRJ Agent with native MCP enabled

• n8n API key

• n8n reachable from the machine running HRJ, usually http://127.0.0.1:5678

Install

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

Store your n8n key

Interactive helper:

./scripts/set-key.sh

Default output path:

~/.config/n8n-mcp/env

Expected permissions:

stat -c '%a %U:%G %n' ~/.config/n8n-mcp/env
# 600 youruser:yourgroup /home/youruser/.config/n8n-mcp/env

Manual version:

install -d -m 700 ~/.config/n8n-mcp
cat > ~/.config/n8n-mcp/env <<'EOF'
N8N_BASE_URL=http://127.0.0.1:5678
N8N_API_KEY=REPLAC...hmod 600 ~/.config/n8n-mcp/env

Replace REPLACE_ME locally. Do not commit the real file.

HRJ config

Add this to ~/.hrj/config.yaml:

mcp_servers:
  n8n:
    command: "/absolute/path/to/hrj-n8n-mcp/.venv/bin/python"
    args:
      - "/absolute/path/to/hrj-n8n-mcp/server.py"
    env:
      N8N_MCP_ENV: "/absolute/path/to/.config/n8n-mcp/env"
    timeout: 120
    connect_timeout: 30
    sampling:
      enabled: false
    tools:
      default_enabled:
        - health
        - list_workflows
        - get_workflow
        - find_workflows
        - list_executions
        - get_execution
        - recent_failures
        - export_workflow
        - container_logs
        - container_status

Then reload MCP in HRJ:

/reload-mcp

Or from shell:

hrj mcp test n8n

Environment variables

Smoke test outside HRJ

. .venv/bin/activate
python -m py_compile server.py
hrj mcp test n8n

Docker logs

container_logs shells out to Docker. If the user running HRJ cannot access Docker, set:

N8N_MCP_ALLOW_DOCKER_LOGS=false

The rest of the API tools will still work.

Audit logs

Write operations are logged to ~/.config/n8n-mcp/logs/audit.log. Check this file to review:

• Which workflows were created, updated, or deleted

• When activation/deactivation occurred

• Failed attempts (blocked by env flag or missing token)

• Token validation events

Notes for production use

• Keep n8n bound to loopback behind your reverse proxy.

• Do not expose this MCP bridge over Caddy, nginx, or Docker ports.

• Rotate n8n API keys if they ever hit chat logs, terminals, CI output, screenshots, or issue trackers.

• Back up workflows before mutating them (export_workflow before update_workflow).

• Use delete_workflow with caution — it is irreversible.

• Keep write tools disabled by default — enable only when needed.

• Keep N8N_MCP_ALLOW_DELETE=false unless actively deleting.

• Review audit logs periodically.

License

MIT. See LICENSE.