n8n-guard

n8n-guard

n8n Public APIの下層にある運用レイヤー向けのMCPサーバーです。

レジストリにある多くのn8n MCPサーバーは、同じパブリックエンドポイントをラップしています。ワークフローの一覧表示、実行の一覧表示、作成、有効化、削除です。ワークフローの構築には便利ですが、セルフホストのインスタンスを稼働し続けるにはほとんど役に立ちません。実際にインスタンスを停止させる原因となる要素は、APIにはまったく含まれていないからです。

n8n-guardは、APIでは答えられない次の4つの質問に答えます。

1. データストアのサイズはどれくらいで、いつ問題になりますか？ Public APIにはデータベースサイズを取得するエンドポイントがありません。n8n-guardはSQLiteファイルを読み取るかPostgresに直接クエリを実行し、テーブルごとにサイズを分類して増加率を算出し、残り何日分の余裕があるかを示します。
2. 停止している実行はどれですか？ ステータスで実行を一覧表示するだけでは検出になりません。running状態の実行は、通常の所要時間と比較するまでは、正常な長時間ジョブと同じに見えます。n8n-guardは完了した実行からワークフローごとの中央値を算出し、外れ値を検出します。
3. 保持によってどれくらいのコストが発生していますか？ 保存されている実行レコードの数、どのくらい過去までさかのぼるか、指定した保持期間によってどれだけ削減できるかを確認できます。
4. インスタンスはgitとの差分が生じていますか？ 既存のサーバーは、あるAPIオブジェクトを別のAPIオブジェクトと比較します。n8n-guardは、稼働中のインスタンスをリポジトリ内のJSONエクスポートと比較し、エクスポートされていない稼働中のワークフロー、削除済みのエクスポート済みワークフロー、気付かないうちに内容が乖離したワークフローを検出します。

完全な読み取り専用です。n8n-guardはインスタンスへの書き込み、実行の削除、ワークフローの有効化や編集を一切行いません。結果を報告し、判断はユーザーに委ねます。

インストール

npx -y n8n-guard

Node.js 22以降が必要です（組み込みのnode:sqliteを使用します）。永続的にインストールするには、npm install -g n8n-guardを実行してください。

Claude Desktop／任意のMCPクライアント

{
  "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"
      }
    }
  }
}

設定

すべて環境変数で設定します。ホスト、パス、コンテナ名、アカウントはハードコードされていないため、任意のセルフホストインスタンスに対してサーバーを実行できます。

変数	必須	デフォルト	用途
N8N_URL	いいえ	http://localhost:5678	インスタンスのベースURL
N8N_API_KEY	実行とワークフローのチェックに必要	なし	Public APIキー（Settings、n8n API）
N8N_SQLITE_PATH	SQLiteのデータストアチェックに必要	なし	database.sqliteへのパス
N8N_POSTGRES_URL	Postgresのデータストアチェックに必要	なし	接続文字列。SQLiteより優先されます
N8N_GIT_REPO_PATH	差分チェックに必要	なし	エクスポートしたワークフローJSONを含むチェックアウト
N8N_GUARD_STUCK_MINUTES	いいえ	15	実行が停止中と見なされるまでにrunning状態で経過する時間（分）
N8N_GUARD_DB_WARN_BYTES	いいえ	1073741824（1 GB）	データストアの警告しきい値
N8N_GUARD_DB_CRITICAL_BYTES	いいえ	4294967296（4 GB）	データストアの重大なしきい値
N8N_GUARD_TIMEOUT_MS	いいえ	15000	APIリクエストごとのタイムアウト

部分的な設定もエラーではなく、サポートされている使用方法です。N8N_URLとN8N_SQLITE_PATHだけを設定した場合でも、ディスクと保持に関する情報を取得できます。APIを使うチェックは未設定であることを報告し、残りの処理は続行されます。

ツール

ツール	説明
instance_info	到達可能性、設定済みのデータストア、ワークフローの一覧を確認します。使用可能なチェックを表示します。
db_health	データストアのサイズ、テーブルごとの内訳、増加率、重大しきい値に達するまでの推定日数を確認します。
stuck_executions	running のまま停止している実行を、絶対しきい値と各ワークフロー固有の中央値に基づいて判定します。
retention_report	実行数、経過期間、保持期間を適用した場合に削減できるデータ量を確認します。
git_drift	稼働中のワークフローとリポジトリ内のエクスポートを照合し、不足、削除、差異、重複を確認します。
guard_run	上記すべてを、耐障害性のある一括チェックで実行します。スケジュール実行にはこれを使います。

呼び出し例

サーバーをインスタンスに接続し、クライアントからツールを呼び出します。各ツールは、まず読みやすい概要を返し、その後に構造化されたペイロード全体を返します。

## 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.

続いて、その概要の元になった構造化ペイロードが返されます。

{
  "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 は6つのチェックすべてを実行します。データストアだけが設定されている場合も、中断せずに不足している項目を報告します。

## 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

復旧：guard_run は一部の障害が発生しても処理を継続します

到達できない依存先が1つでもあると中断する監視実行は、まさに必要なときに役に立ちません。API の停止自体がインシデントであり、それを理由にディスクの確認までやめるべきではありません。

guard_run は各ステップを分離します。失敗したステップはバックオフを伴って再試行され、それでも失敗する場合は検出事項として記録され、残りのチェックは最後まで実行されます。失敗したステップに依存するステップは、入力がないためにクラッシュするのではなく、理由を添えてスキップされます。レポートにはそのことが明確に示されます。

## 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

この動作は test/unit/runner.test.ts と test/unit/serviceRecovery.test.ts のテストで検証されています。後者では、意図的に停止させた API エンドポイントに対して、実際の SQLite データストアを実行します。

Render ワークフロー

同じ一括チェックは、Render ワークフローとしても実行できます。チェックごとに1つの Render タスクを作成し、順序、再試行、バックオフをタスク定義で宣言して、プロセス内のランナーではなく Render が実行します。デプロイ手順、タスクの一覧、実行の開始方法（再試行の動作を示す意図的な失敗を含む）は、docs/render-workflow.md に記載されています。

使い捨てインスタンスで試す

compose ファイルは、新しい n8n を起動します。サーバーを安全に接続して試せます。データディレクトリはバインドマウントされており、これは n8n-guard が実際のデプロイを読み取る方法と同じです。

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

スクリプトはオーナーのパスワードを生成し、Git の追跡対象外である .n8n-demo-credentials に保存します。また、サーバーの実行に使う環境変数ブロックとともにパスワードを表示します。エクスポートと一致するワークフロー、エクスポートされたことのないワークフロー、実行が停止する可能性のある sink コンテナを参照するワークフロー、そして実在しないワークフローのエクスポートを1つずつ投入します。これにより、git_drift と stuck_executions が実際に検出できるものが用意されます。

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

このインスタンスは n8n のデフォルトである 5678 ではなく 5679 で公開されるため、使用中のインスタンスとポートが競合しません。ポートを変更するには N8N_DEMO_PORT を設定し、同じ値を demo-setup.sh、統合テスト、N8N_URL に渡してください。

テスト

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

N8N_API_KEY が設定されていない場合、統合テストでは API に依存するテストケースがスキップされるため、docker compose up だけの環境でも実行できます。

ライセンス

MIT