N8n Workflow Tester Safe 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:

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%)

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)

Workflow Operations (5 tools)

Introspection (5 tools)

Catalog (5 tools)

Example Configs

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

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.