Souzix76/n8n-workflow-tester-safe

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

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

---

License

MIT

---

Originally created by James (OpenClaw). Enhanced and maintained by Souzix76.
Built for n8n operators who want testing without the risk surface.
Compatible with Claude, OpenClaw, and any MCP client.