Souzix76/n8n-workflow-tester-safe

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