How to Configure Webhook Security Modes for Local n8n Instance Access

Set the WEBHOOK_SECURITY_MODE environment variable to moderate or permissive in the czlonkowski/n8n-mcp server to allow webhook requests to localhost and private IP addresses during local development.

The czlonkowski/n8n-mcp repository protects webhook calls against Server-Side Request Forgery (SSRF) through a configurable validation utility. When running the MCP server alongside a local n8n instance, you must adjust these webhook security modes to prevent legitimate development requests from being blocked.

Understanding SSRF Protection

The SSRF protection logic resides in src/utils/ssrf-protection.ts. This utility validates webhook URLs before the server dispatches requests, preventing attackers from using the MCP server to access internal network resources.

The protection mechanism reads the security configuration through the environment variable WEBHOOK_SECURITY_MODE, defaulting to strict if not specified:

const mode: SecurityMode = (process.env.WEBHOOK_SECURITY_MODE || 'strict') as SecurityMode;

Available Security Modes

The system supports three distinct security modes that determine how localhost and private IP ranges are treated:

• Strict (default): Blocks both localhost and any private network ranges. This mode is designed for production environments where internal network access must be prevented.
• Moderate: Allows localhost addresses while continuing to block private IP ranges. This is the recommended setting for local development when your n8n instance runs on localhost or 127.0.0.1.
• Permissive: Allows both localhost and private IP ranges, blocking only cloud-metadata endpoints. Use this mode only for testing scenarios where you need access to local network resources.

Configuring for Local Development

To enable webhook access to a local n8n instance, configure the environment variable before starting the MCP server.

Method 1: Environment File

Create or modify a .env file in the project root:

# .env

WEBHOOK_SECURITY_MODE=moderate

Method 2: Docker Runtime

Pass the variable directly when running the Docker container:

docker run -e WEBHOOK_SECURITY_MODE=moderate \
  -p 5678:5678 czlonkowski/n8n-mcp:latest

Method 3: Shell Export

Export the variable in your shell session before launching:

export WEBHOOK_SECURITY_MODE=moderate
npm run dev

After setting the variable, restart the MCP server to load the new configuration. The server now treats http://localhost:<port>/... URLs as valid webhook destinations.

How Webhook Validation Works

When a webhook is triggered, the handler in src/triggers/handlers/webhook-handler.ts validates the constructed URL before sending the request:

const { SSRFProtection } = await import('../../utils/ssrf-protection');
const validation = await SSRFProtection.validateWebhookUrl(webhookUrl);
if (!validation.valid) {
  return this.errorResponse(input, `SSRF protection: ${validation.reason}`, startTime);
}

If validation fails, the handler returns an error response immediately. In moderate mode, successful localhost requests generate an informational log indicating that the localhost webhook was allowed.

Testing the Configuration

Verify your configuration by triggering a webhook from your local n8n instance:

curl -X POST http://localhost:5678/webhook/my-test-path \
     -H 'Content-Type: application/json' \
     -d '{"name":"test"}'

The request succeeds because the moderate mode permits the localhost address, while the strict mode would reject it with an SSRF protection error.

Summary

• Three security modes control webhook access: strict (production), moderate (local development), and permissive (testing only).
• WEBHOOK_SECURITY_MODE environment variable configures the protection level, defaulting to strict.
• Local development requires setting the mode to moderate or permissive to allow localhost webhook targets.
• Validation occurs in src/utils/ssrf-protection.ts and is invoked by src/triggers/handlers/webhook-handler.ts before dispatching webhook requests.
• Production deployments should always use strict mode to prevent Server-Side Request Forgery attacks.

Frequently Asked Questions

What is the default webhook security mode in n8n-MCP?

The default mode is strict. If you do not set the WEBHOOK_SECURITY_MODE environment variable, the server will block all requests to localhost and private IP ranges. This default protects production deployments from SSRF vulnerabilities but requires explicit configuration changes for local development.

Why do I get SSRF errors when testing webhooks locally?

You receive SSRF errors because the default strict mode blocks localhost addresses. The validation logic in src/utils/ssrf-protection.ts rejects these URLs before the webhook handler in src/triggers/handlers/webhook-handler.ts can process them. Set WEBHOOK_SECURITY_MODE=moderate to allow localhost while maintaining protection against private network access.

Is it safe to use permissive mode in production?

No, permissive mode should never be used in production environments. This mode allows access to private IP ranges and internal network resources, creating significant security vulnerabilities. Reserve permissive for isolated testing environments only, and always deploy with strict mode in production.

How do I verify which security mode is active?

Check the MCP server startup logs or inspect the environment variable within the running process. The SSRFProtection.validateWebhookUrl function in src/utils/ssrf-protection.ts reads the mode at runtime, so you can verify the setting by attempting to trigger a webhook to a localhost URL. If strict mode is active, the request will fail with an SSRF protection error.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}