n8n MCP Server for Windsurf: Setup & Config

What you can do with n8n in Windsurf

Pick it for workflow lifecycle controls, execution inspection, and webhook triggers against your n8n instance.

• Activate or deactivate existing automations.
• Trigger a Basic-Auth-protected n8n webhook by workflow name.

Before you start: n8n in Windsurf

• Node.js 20 or newer
• An n8n instance with API access enabled
• The globally installed @leonardsellem/n8n-mcp-server package
• An n8n API key

Install with npm install -g @leonardsellem/n8n-mcp-server before using this executable. N8N_WEBHOOK_USERNAME and N8N_WEBHOOK_PASSWORD are needed only for webhook tools. Source builds and Docker are documented alternatives.

n8n Windsurf configuration

1. Choose Windsurf configuration scope

   For n8n MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add n8n MCP Server to Windsurf

   Use the n8n-mcp-server entry below in mcpServers. Keep n8n MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check n8n MCP Server in Windsurf

   n8n MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "n8n-mcp-server": {
      "command": "n8n-mcp-server",
      "args": [],
      "env": {
        "N8N_API_URL": "<Full n8n API URL including /api/v1>",
        "N8N_API_KEY": "<n8n API key with appropriate permissions>"
      }
    }
  }
}

n8n tools available to Windsurf

n8n's stored tool list documents 12 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

workflow_list

After refreshing n8n in Windsurf settings, check Cascade's tool list for workflow_list.

workflow_get

After refreshing n8n in Windsurf settings, check Cascade's tool list for workflow_get.

workflow_create

After refreshing n8n in Windsurf settings, check Cascade's tool list for workflow_create.

workflow_update

After refreshing n8n in Windsurf settings, check Cascade's tool list for workflow_update.

Change an existing workflow definition.

workflow_delete

After refreshing n8n in Windsurf settings, check Cascade's tool list for workflow_delete.

Remove a workflow.

workflow_activate

After refreshing n8n in Windsurf settings, check Cascade's tool list for workflow_activate.

Enable a workflow.

workflow_deactivate

After refreshing n8n in Windsurf settings, check Cascade's tool list for workflow_deactivate.

execution_run

After refreshing n8n in Windsurf settings, check Cascade's tool list for execution_run.

run_webhook

After refreshing n8n in Windsurf settings, check Cascade's tool list for run_webhook.

execution_get

After refreshing n8n in Windsurf settings, check Cascade's tool list for execution_get.

Inspect details for a specific workflow run.

execution_list

After refreshing n8n in Windsurf settings, check Cascade's tool list for execution_list.

List runs associated with a workflow.

execution_stop

After refreshing n8n in Windsurf settings, check Cascade's tool list for execution_stop.

Stop an execution that is currently running.

n8n: full stored tool descriptions

Troubleshooting n8n in Windsurf

• Check n8n-mcp-server on the machine running Windsurf's MCP integration for n8n MCP Server; refresh MCP and inspect Cascade's tools.
• Check N8N_API_KEY, N8N_API_URL for n8n MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• n8n MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires an API-enabled n8n instance and suitable API credentials.
• Known limitation: Webhook use needs a configured workflow and Basic Authentication credentials.
• Known limitation: The README describes part-time maintenance and a search for co-maintainers.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions