Skip to main content
Connect n8n-MCP to Windsurf IDE for enhanced n8n workflow development with AI assistance.

Video Tutorial

Watch the complete setup process

​
Prerequisites

  • Windsurf IDE installed
  • Node.js installed on your system
  • n8n instance (optional, for full workflow management)

​
Installation

1

Access MCP Configuration

Navigate to the MCP configuration in Windsurf:
  1. Go to Settings in Windsurf
  2. Navigate to Windsurf Settings
  3. Go to MCP Servers > Manage Plugins
  4. Click “View Raw Config”
2

Add n8n-MCP Configuration

Add the n8n-MCP configuration to your MCP config:
Documentation tools only - No n8n API connection required.
{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
}
3

Apply Configuration

  1. Save the configuration file
  2. Click the refresh button to apply the changes
  3. Verify that n8n-mcp appears in the list of active MCP servers
4

Set Up Project Instructions

Create a .windsurfrules file in your project root:
touch .windsurfrules
Copy the Claude Project instructions from the Claude Project Setup section into this file.

​
Configuration Options

​
Environment Variables

​
MCP_MODE
string
default:"stdio"
required
Mode for MCP communication. Use “stdio” for Windsurf.
​
LOG_LEVEL
string
default:"info"
Logging level. Set to “error” to reduce noise.
​
DISABLE_CONSOLE_OUTPUT
string
default:"false"
Set to “true” to disable console output.
​
N8N_API_URL
string
Your n8n instance URL (e.g., https://your-n8n-instance.com or http://localhost:5678)
​
N8N_API_KEY
string
Your n8n API key for workflow management operations

​
Verification

To verify your setup is working:
1

Check MCP Status

Go to Windsurf Settings > MCP Servers and verify n8n-mcp is listed and active.
2

Open Windsurf Chat

Open the Windsurf AI chat panel.
3

Test a Command

Try a simple prompt:
Search for Slack integration nodes in n8n
4

Verify Tools Available

You should see n8n-mcp tools being used in the response. With API credentials, you’ll have access to all workflow management tools.

​
Usage Examples

​
Building a Workflow

Create an n8n workflow that:
1. Triggers when a new email arrives in Gmail
2. Extracts important information
3. Creates a task in Notion
4. Sends a summary via Slack

​
Validating Workflows

Validate this n8n workflow configuration and identify any issues:
[paste your workflow JSON]

​
Node Documentation

Show me how to configure the HTTP Request node with OAuth2 authentication

​
Tips

  • Use Windsurf’s Cascade mode for autonomous workflow building
  • Always validate workflows before deploying to n8n
  • Use .windsurfrules to maintain consistent AI behavior across sessions
  • Leverage Windsurf’s multi-file context for complex workflow projects

​
Troubleshooting

  1. Verify the JSON syntax in the MCP configuration is valid
  2. Click the refresh button in MCP Servers settings
  3. Restart Windsurf IDE
  4. Check the Windsurf console for error messages
  • Ensure Node.js is installed: node --version
  • Verify npm is in your PATH
  • Try using the full path to npx in the configuration
  • On Windows, ensure npm is accessible from the command line
  • Verify your n8n instance is running and accessible
  • Check the N8N_API_URL is correct
  • Verify your N8N_API_KEY is valid
  • Test the connection manually: curl -H "X-N8N-API-KEY: your-key" https://your-n8n-instance.com/api/v1/workflows
  • Verify .windsurfrules file exists in project root
  • Check that instructions are formatted correctly
  • Try removing and re-adding the MCP server
  • Review Windsurf’s output panel for detailed error logs

​
Windsurf-Specific Features

​
Cascade Mode

Windsurf’s Cascade mode works exceptionally well with n8n-MCP for autonomous workflow development: 
@cascade Create a complete n8n workflow for processing customer support tickets:
1. Monitor email inbox
2. Classify ticket urgency using AI
3. Create tickets in Linear
4. Notify team via Slack based on priority
5. Validate and deploy the workflow

​
Flow Mode

Use Flow mode for iterative workflow refinement: 
@flow Help me improve this n8n workflow by:
1. Adding error handling
2. Optimizing node configurations
3. Adding validation checks
4. Testing webhook triggers

​
Next Steps

Claude Project Setup

Configure optimal project instructions

Available Tools

Explore all n8n-MCP tools

Building Workflows

Learn workflow best practices

Video Tutorial

Watch the setup walkthrough

Build docs developers (and LLMs) love

Get started for freeTalk to us