MCP 服务器

n8n-workflow-tester-safe

Safe MCP server and CLI tool for testing, scoring, and inspecting n8n workflows. Features 19 tools for workflow testing, execution traces, tiered scoring, and a built-in node catalog with 800+ node types. Designed with safety-first approach: no credential management, no secrets lifecycle, no auto-fix loops.

README

Safe MCP server + CLI for testing, scoring, and inspecting n8n workflows Config-driven test suites with tiered scoring, execution traces, and a built-in node catalog.

Why?

Most n8n MCP integrations give you full admin access — credentials, destructive operations, auto-fix loops. That's fine for development, but risky for CI, shared environments, or autonomous agents.

n8n-workflow-tester-safe takes a different approach:

Feature	This MCP	Full admin MCPs
Test workflows with scoring	Yes	No
Execution traces (lightweight)	Yes	No
Node catalog with suggestions	Yes	No
Credential management	Excluded	Yes
Secret lifecycle	Excluded	Yes
Auto-fix loops	Excluded	Some

Result: A focused tool that does testing and inspection really well, without the risk surface of a full admin wrapper.

Quick Start

1. Install

git clone https://github.com/souzix76/n8n-workflow-tester-safe.git
cd n8n-workflow-tester-safe
npm install && npm run build

2. Configure

cp .env.example .env
# Edit .env with your n8n URL and API key

N8N_BASE_URL=http://127.0.0.1:5678
N8N_API_KEY=your_n8n_api_key_here
DEFAULT_TIMEOUT_MS=30000

3. Run

As MCP server (for Claude, OpenClaw, or any MCP client):

node dist/index.js

As CLI (for scripts and CI):

node dist/cli.js --config ./workflows/example.json

MCP Client Configuration

Claude Code (`~/.claude.json`)

{
  "mcpServers": {
    "n8n-workflow-tester": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/n8n-workflow-tester-safe/dist/index.js"],
      "env": {
        "N8N_BASE_URL": "http://localhost:5678",
        "N8N_API_KEY": "your_api_key"
      }
    }
  }
}

OpenClaw / Any MCP client

The server uses stdio transport — compatible with any MCP client that supports stdio.

How It Works

Test Config

Define your tests in a JSON file:

{
  "workflowId": "abc123",
  "workflowName": "my-webhook-handler",
  "triggerMode": "webhook",
  "webhookPath": "/webhook/my-handler",
  "timeoutMs": 15000,
  "qualityThreshold": 85,
  "testPayloads": [
    {
      "name": "happy-path",
      "data": { "message": "Hello", "userId": "user_001" }
    },
    {
      "name": "empty-input",
      "data": { "message": "" }
    },
    {
      "name": "large-payload",
      "data": { "items": ["a","b","c","d","e","f","g","h","i","j"] }
    }
  ],
  "tier3Checks": [
    {
      "name": "has-response",
      "field": "output",
      "check": "not_empty",
      "severity": "error"
    },
    {
      "name": "response-length",
      "field": "output.message",
      "check": "min_length",
      "value": 5,
      "severity": "warning",
      "message": "Response too short"
    }
  ]
}

Scoring System

Every test run produces a two-tier score:

Final Score = (Tier 1 x 70%) + (Tier 3 x 30%)

Tier	Weight	What it checks
Tier 1 (Infrastructure)	70%	HTTP success, timeout compliance, non-empty output
Tier 3 (Quality)	30%	Custom field checks: contains, equals, min/max length, not_empty

A test passes when:

Tier 1 score = 100 (all infrastructure checks pass)
Final score >= quality threshold (default 85)
No issues with severity error

Example Output

{
  "passed": true,
  "score": 93,
  "tier1Score": 100,
  "tier3Score": 80,
  "issues": [
    {
      "tier": "tier3",
      "severity": "warning",
      "check": "response-length",
      "message": "Response too short"
    }
  ]
}

Tools Reference

Testing (3 tools)

Tool	Description
`test_workflow`	Run a single payload test from a config file
`evaluate_workflow_result`	Run a test and return evaluation score + issues
`run_workflow_suite`	Run all payloads in a config, return per-payload scores

Workflow Operations (5 tools)

Tool	Description
`create_workflow`	Create a new workflow from JSON
`update_workflow`	Replace an existing workflow by ID
`delete_workflow`	Delete a workflow by ID
`add_node_to_workflow`	Append a node to an existing workflow
`connect_nodes`	Create a connection between two nodes

Introspection (5 tools)

Tool	Description
`get_workflow_summary`	Compact summary: node count, names, types, disabled status
`list_node_types`	List all available node types from the n8n instance
`get_node_type`	Full schema/metadata for a specific node type
`list_executions`	Recent executions, filterable by workflow and status
`get_execution`	Full execution data by ID
`get_execution_trace`	Lightweight per-node trace — timing, errors, item counts

Catalog (5 tools)

Tool	Description
`get_catalog_stats`	Node/trigger/credential counts from imported catalog
`search_nodes`	Fuzzy search by name, optional trigger-only filter
`list_triggers`	All trigger nodes from the catalog
`validate_node_type`	Check if a node type exists, get close matches
`suggest_nodes_for_task`	Natural-language task in, relevant nodes out

Example Configs

The workflows/ directory includes ready-to-use test configs:

File	Trigger Mode	Payloads	Description
`example.json`	webhook	2	Basic webhook echo test
`telegram-bot.json`	webhook	3	Telegram bot command handler
`api-pipeline.json`	execute	3	Multi-step API data pipeline

Architecture

src/
  index.ts        MCP server (stdio) + tool registration
  cli.ts          CLI runner for config-driven tests
  n8n-client.ts   REST client for n8n API v1
  evaluator.ts    Two-tier scoring engine
  catalog.ts      Node catalog parser + fuzzy search
  config.ts       JSON config reader + Zod validation
  types.ts        TypeScript interfaces

catalog/          Imported n8n node catalog (436 nodes, 389 credentials)
workflows/        Example test suite configs

Design Constraints

stdio-only transport — no HTTP server, no auth to manage
Explicit tool surface — 19 tools, each with a clear purpose
Small dependency footprint — only @modelcontextprotocol/sdk and zod
No credential lifecycle — won't read, create, or delete credentials
No agentic auto-repair — reports issues, doesn't auto-fix them

Safety Posture

Included

Workflow test execution (webhook + API)
Output evaluation with tiered scoring
Workflow CRUD (create, read, update, delete)
Graph editing (add nodes, connect)
Execution inspection and tracing
Node catalog lookup and validation

Deliberately Excluded

Credentials management
Secrets lifecycle
Destructive restore flows
Autonomous LLM auto-fix loops
Production deployment operations

Roadmap

[ ] Read-only mode flag (disable all mutation tools)
[ ] Workflow diff summaries (before/after comparison)
[ ] Reusable evaluation presets for common patterns
[ ] Richer trace visualization
[ ] Fixture libraries for test payloads
[ ] npm package for npx usage

Contributing

Fork the repo
Create a feature branch (git checkout -b feat/my-feature)
Commit changes (git commit -m 'feat: add my feature')
Push to branch (git push origin feat/my-feature)
Open a Pull Request

License

MIT

Originally created by James (<a href="https://openclaw.org">OpenClaw</a>). Enhanced and maintained by <a href="https://github.com/Souzix76">Souzix76</a>. Built for <a href="https://n8n.io">n8n</a> operators who want testing without the risk surface. Compatible with <a href="https://claude.ai">Claude</a>, <a href="https://openclaw.org">OpenClaw</a>, and any MCP client.