Back to Browse

N8n Guard MCP Server

ProductivityLow Risk10.0MCP RegistryLocal
Free

Server data from the Official MCP Registry

Read-only health checks for self-hosted n8n: datastore growth, stuck runs, retention, git drift.

About

Read-only health checks for self-hosted n8n: datastore growth, stuck runs, retention, git drift.

Security Report

10.0
Low Risk10.0Low Risk

Valid MCP server (4 strong, 3 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.

10 files analyzed · 1 issue found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

database

Check that this permission is expected for this type of plugin.

env_vars

Check that this permission is expected for this type of plugin.

Shell Command Execution

Runs commands on your machine. Be cautious — only use if you trust this plugin.

What You'll Need

Set these up before or after installing:

Base URL of the n8n instance. Defaults to http://localhost:5678.Optional

Environment variable: N8N_URL

n8n Public API key. Required for the execution and workflow checks.Required

Environment variable: N8N_API_KEY

Path to the n8n database.sqlite file. Required for datastore checks on SQLite.Optional

Environment variable: N8N_SQLITE_PATH

Postgres connection string. Takes precedence over N8N_SQLITE_PATH.Required

Environment variable: N8N_POSTGRES_URL

Checkout holding exported workflow JSON. Required for the git drift check.Optional

Environment variable: N8N_GIT_REPO_PATH

Minutes a run may stay in `running` before it counts as stuck. Defaults to 15.Optional

Environment variable: N8N_GUARD_STUCK_MINUTES

Datastore warning threshold in bytes. Defaults to 1073741824 (1 GB).Optional

Environment variable: N8N_GUARD_DB_WARN_BYTES

Datastore critical threshold in bytes. Defaults to 4294967296 (4 GB).Optional

Environment variable: N8N_GUARD_DB_CRITICAL_BYTES

Per-request API timeout in milliseconds. Defaults to 15000.Optional

Environment variable: N8N_GUARD_TIMEOUT_MS

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "n8n-guard": {
      "command": "npx",
      "args": [
        "-y",
        "n8n-guard@0.1.0"
      ],
      "env": {
        "N8N_URL": "your-n8n-url-here",
        "N8N_API_KEY": "your-n8n-api-key-here",
        "N8N_SQLITE_PATH": "your-n8n-sqlite-path-here",
        "N8N_POSTGRES_URL": "your-n8n-postgres-url-here",
        "N8N_GIT_REPO_PATH": "your-n8n-git-repo-path-here",
        "N8N_GUARD_TIMEOUT_MS": "your-n8n-guard-timeout-ms-here",
        "N8N_GUARD_DB_WARN_BYTES": "your-n8n-guard-db-warn-bytes-here",
        "N8N_GUARD_STUCK_MINUTES": "your-n8n-guard-stuck-minutes-here",
        "N8N_GUARD_DB_CRITICAL_BYTES": "your-n8n-guard-db-critical-bytes-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

n8n-guard

npm MCP Registry License: MIT Node

An MCP server for the operational layer underneath the n8n Public API.

Most n8n MCP servers on the registry wrap the same public endpoints: list workflows, list executions, create, activate, delete. That is useful for building workflows. It is close to useless for keeping a self-hosted instance alive, because the things that actually take an instance down are not in that API at all.

n8n-guard answers the four questions the API cannot:

  1. How big is the datastore, and when does it become a problem? The Public API has no endpoint for database size. n8n-guard reads the SQLite file or queries Postgres directly, breaks the size down per table, derives the growth rate, and tells you how many days of headroom are left.
  2. Which executions are stuck? Listing executions by status is not detection. A run sitting in running looks identical to a healthy long job until you compare it against what that workflow normally takes. n8n-guard builds a per-workflow median from finished runs and flags the outliers.
  3. What is retention costing? How many execution records are stored, how far back they reach, and what a given retention window would free.
  4. Has the instance drifted from git? Existing servers diff one API object against another. n8n-guard diffs the running instance against the JSON exports in a repository: live but never exported, exported but deleted, and content that quietly diverged.

It is strictly read-only. n8n-guard never writes to your instance, never deletes executions, and never activates or edits a workflow. It reports; you decide.

Install

npx -y n8n-guard

Requires Node.js 22 or newer (it uses the built-in node:sqlite). For a permanent install use npm install -g n8n-guard.

Claude Desktop / any MCP client

{
  "mcpServers": {
    "n8n-guard": {
      "command": "n8n-guard",
      "env": {
        "N8N_URL": "https://n8n.example.com",
        "N8N_API_KEY": "n8n_api_...",
        "N8N_SQLITE_PATH": "/var/lib/n8n/.n8n/database.sqlite",
        "N8N_GIT_REPO_PATH": "/srv/workflow-exports"
      }
    }
  }
}

Configuration

Everything is an environment variable. There are no hardcoded hosts, paths, container names or accounts, so the server runs against any self-hosted instance.

VariableRequiredDefaultPurpose
N8N_URLnohttp://localhost:5678Base URL of the instance
N8N_API_KEYfor execution and workflow checksnonePublic API key (Settings, n8n API)
N8N_SQLITE_PATHfor datastore checks on SQLitenonePath to database.sqlite
N8N_POSTGRES_URLfor datastore checks on PostgresnoneConnection string, takes precedence over SQLite
N8N_GIT_REPO_PATHfor the drift checknoneCheckout holding exported workflow JSON
N8N_GUARD_STUCK_MINUTESno15Minutes in running before a run counts as stuck
N8N_GUARD_DB_WARN_BYTESno1073741824 (1 GB)Datastore warning threshold
N8N_GUARD_DB_CRITICAL_BYTESno4294967296 (4 GB)Datastore critical threshold
N8N_GUARD_TIMEOUT_MSno15000Per-request API timeout

Partial configuration is a supported mode, not an error. With only N8N_URL and N8N_SQLITE_PATH you still get disk and retention answers; the API-backed checks report that they are unconfigured and the rest of the run continues.

Tools

ToolWhat it does
instance_infoReachability, configured datastore, workflow inventory. Shows which checks are usable.
db_healthDatastore size, per-table breakdown, growth rate, projected days until the critical threshold.
stuck_executionsRuns stuck in running, judged against the absolute threshold and each workflow's own median.
retention_reportExecution count, age span, and what pruning to a retention window would free.
git_driftLive workflows against the repository exports: missing, deleted, drifted, duplicated.
guard_runAll of the above in one resilient sweep. This is the one to schedule.

Example call

Point the server at an instance and let your client call a tool. Every tool answers with a readable summary first and the full structured payload after it:

## Retention report
- 200 execution records spanning 8.3 days (24.1/day)
- nothing older than 30 days, retention is already tight
- n8n-guard never deletes. To act on this, set EXECUTIONS_DATA_PRUNE=true and
  EXECUTIONS_DATA_MAX_AGE=720 (hours) on the n8n instance, then restart it.

followed by the structured payload the summary was derived from:

{
  "executionCount": 200,
  "oldestExecutionAt": "2026-08-28T23:43:28.651Z",
  "spanDays": 8.29,
  "executionsPerDay": 24.12,
  "buckets": [
    { "olderThanDays": 7, "rows": 32, "share": 0.16, "estimatedBytes": 3277 },
    { "olderThanDays": 30, "rows": 0, "share": 0, "estimatedBytes": 0 }
  ]
}

guard_run wraps all six checks. With only a datastore configured it reports the gap instead of aborting:

## Guard run (degraded)
- stuck_executions failed after 3 attempt(s): N8N_API_KEY is not set, so the n8n Public API cannot be queried
- git_drift failed after 2 attempt(s): N8N_GIT_REPO_PATH is not set, so there is nothing to diff the instance against
- 4 of 6 checks completed despite the failures above

Recovery: guard_run survives a partial outage

A monitoring run that aborts on the first unreachable dependency is worthless precisely when it matters. The API being down is the incident, and it is no reason to stop looking at the disk.

guard_run isolates every step. A failing step is retried with backoff, and if it still fails it becomes a finding while the remaining checks run to completion. Steps that depend on a failed step are skipped with the reason attached rather than crashing on missing input. The report says so plainly:

## Guard run (degraded)
- stuck_executions failed after 3 attempt(s): cannot reach http://n8n.internal:5678: fetch failed
- git_drift skipped: depends on instance, which failed
- 4 of 6 checks completed despite the failures above

This behaviour is covered by tests in test/unit/runner.test.ts and test/unit/serviceRecovery.test.ts, the latter running a real SQLite datastore against a deliberately dead API endpoint.

Render Workflows

The same sweep also runs as a Render Workflow: one Render task per check, with ordering, retries and backoff declared in the task definitions and executed by Render rather than by the in-process runner. Deploy steps, the task table and how to trigger a run (including a deliberate failure that demonstrates the retry path) are in docs/render-workflow.md.

Try it on a throwaway instance

The compose file starts a fresh n8n you can safely point the server at. The data directory is bind-mounted, which is exactly how n8n-guard reads a real deployment.

git clone https://github.com/flow-84/n8n-guard && cd n8n-guard
npm install && npm run build

docker compose up -d
./scripts/demo-setup.sh     # owner, API key, workflows, and a drifted export folder

The script generates the owner password, keeps it in the gitignored .n8n-demo-credentials, and prints it along with the environment block to run the server with. It seeds one workflow that matches its export, one that was never exported, one that points at a sink container so a run can hang, and one export whose workflow does not exist, so git_drift and stuck_executions have something real to find.

export N8N_URL=http://localhost:5679
export N8N_API_KEY=...            # printed by the script
export N8N_SQLITE_PATH=$PWD/.n8n-demo/database.sqlite
export N8N_GIT_REPO_PATH=$PWD/.n8n-demo-exports
npm start

The instance publishes on 5679, not on n8n's default 5678, so it cannot collide with an instance you care about. Set N8N_DEMO_PORT to move it, and pass the same value to demo-setup.sh, the integration tests and N8N_URL.

Tests

npm test              # unit tests, no instance required
npm run test:integration   # against the compose instance above

The integration suite skips the API-backed cases when N8N_API_KEY is unset, so it stays runnable on a bare docker compose up.

License

MIT

Reviews

No reviews yet

Be the first to review this server!