# How to Configure Webhook Security Modes for Local n8n Instance Access

> Learn how to configure webhook security modes for your local n8n instance with czlonkowski/n8n-mcp. Set WEBHOOK_SECURITY_MODE to moderate or permissive for localhost and private IP access during development.

- Repository: [Romuald Członkowski/n8n-mcp](https://github.com/czlonkowski/n8n-mcp)
- Tags: how-to-guide
- Published: 2026-03-24

---

**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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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:

```ts
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:

```bash

# .env

WEBHOOK_SECURITY_MODE=moderate

```

### Method 2: Docker Runtime

Pass the variable directly when running the Docker container:

```bash
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:

```bash
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`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/triggers/handlers/webhook-handler.ts)** validates the constructed URL before sending the request:

```ts
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:

```bash
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`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/utils/ssrf-protection.ts) and is invoked by [`src/triggers/handlers/webhook-handler.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/utils/ssrf-protection.ts) rejects these URLs before the webhook handler in [`src/triggers/handlers/webhook-handler.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/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`](https://github.com/czlonkowski/n8n-mcp/blob/main/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.