n8n-mcp-server-rules

Scope & goal

• This rule guides Cursor/agents to use the exposed MCP tools to build n8n workflows from scratch, add/edit nodes, and wire connections (including AI nodes) safely and predictably. Prefer to use MCP tools for AI agent if user didn't concrete this moment directly.
• Start every session by ensuring a valid workspace and workflow file exists.
• AVOID "node_type": "code" as much as possible. Use Specialized/Concise nodes that provide functionality out of the box.
• Start with linear workflow - make connection right there when you add a node.

Core tools (as implemented today)

• create_workflow(workflow_name, workspace_dir)
• list_workflows(limit?, cursor?)
• get_workflow_details(workflow_name, workflow_path?)
• list_available_nodes(search_term ?, n8n_version?, limit?, cursor?, tags?, token_logic?)
• get_n8n_version_info()
• add_node(workflow_name, node_type, position?, parameters?, node_name?, typeVersion?, webhookId?, workflow_path?, connect_from?, connect_to?)
• edit_node(workflow_name, node_id, node_type?, node_name?, position?, parameters?, typeVersion?, webhookId?, workflow_path?, connect_from?, connect_to?)
• delete_node(workflow_name, node_id, workflow_path?)
• add_connection(workflow_name, source_node_id, source_node_output_name, target_node_id, target_node_input_name, target_node_input_index?)
• add_ai_connections(workflow_name, agent_node_id, model_node_id?, tool_node_ids?, memory_node_id?, embeddings_node_id?, vector_store_node_id?, vector_insert_node_id?, vector_tool_node_id?, dry_run?, idempotency_key?)
• compose_ai_workflow(workflow_name, plan, dry_run?, idempotency_key?)
• validate_workflow(workflow_name, workflow_path?, strict_main_chain?, dry_run?)
• connect_main_chain(workflow_name, workflow_path?, dry_run?, idempotency_key?)
• list_template_examples(node_type?, template_name?, limit?, cursor?)

Quick-start recipes

• Create a new workflow

  {
    "workflow_name": "my_first_flow",
    "workspace_dir": "/absolute/path/to/project"
  }
  

• Optimized discovery (single call for multiple related nodes)
  • Prefer one multi-token query over multiple separate calls. Search defaults to OR logic and tag-style synonyms.
  • Examples:

    { "search_term": "webhook trigger" }
    

    { "search_term": "llm agent tool memory" }
    

    { "search_term": "vector embedding", "limit": 25 }
    

    • Require intersection of all terms:

    { "search_term": "webhook trigger", "token_logic": "and" }
    

    • Disable synonym expansion for strict tokens:

    { "search_term": "webhook trigger", "tags": false }
    

    • Paginate when results exceed the limit:

    { "search_term": "http request", "limit": 20, "cursor": "20" }
    

• Node parameter previews (default)
  • list_available_nodes returns a compact propertiesPreview for each node by default. Use it to pick nodes and pre-fill sensible parameters without opening the full schema.
  • Preview fields: name, displayName, type, default (if present), required (true only), and up to 5 optionValues.
  • Example result item:

    {
      "nodeType": "@n8n/n8n-nodes-langchain.informationExtractor",
      "displayName": "Information Extractor",
      "parameterCount": 4,
      "propertiesPreview": [
        { "name": "text", "displayName": "Text", "type": "string", "default": "" },
        { "name": "From Attribute Descriptions", "displayName": "From Attribute Descriptions", "type": "options", "default": "fromAttributes", "optionValues": ["fromAttributes"] },
        { "name": "attributes", "displayName": "Attributes", "type": "fixedCollection", "required": true },
        { "name": "options", "displayName": "Options", "type": "collection", "optionValues": ["systemPromptTemplate"] }
      ]
    }
    

  • Prefer using propertiesPreview to generate UI hints or starter parameter payloads when calling add_node/edit_node.
• Add a node (type casing auto-normalized)

  {
    "workflow_name": "my_first_flow",
    "node_type": "openai",
    "node_name": "OpenAI LLM",
    "position": { "x": 200, "y": 120 },
    "parameters": { "model": "gpt-4o", "temperature": 0.2 }
  }
  

• Connect two nodes (IDs from previous tool results)

  {
    "workflow_name": "my_first_flow",
    "source_node_id": "<NODE_ID_A>",
    "source_node_output_name": "main",
    "target_node_id": "<NODE_ID_B>",
    "target_node_input_name": "main",
    "target_node_input_index": 0
  }
  

• Wire AI agent, model, tools, memory (preferred for LangChain AI nodes)

  {
    "workflow_name": "my_first_flow",
    "agent_node_id": "<AGENT_ID>",
    "model_node_id": "<MODEL_ID>",
    "tool_node_ids": ["<TOOL_ID_1>", "<TOOL_ID_2>"],
    "memory_node_id": "<MEMORY_ID>",
    "embeddings_node_id": "<EMBEDDINGS_ID>",
    "vector_store_node_id": "<VECTOR_STORE_ID>",
    "vector_tool_node_id": "<VECTOR_TOOL_ID>",
    "dry_run": false,
    "idempotency_key": "optional-key-for-safe-retries"
  }
  

• Add a node and connect immediately (from existing → new)

  {
    "workflow_name": "my_first_flow",
    "node_type": "httpRequest",
    "position": { "x": 600, "y": 200 },
    "connect_from": [
      {
        "source_node_id": "<EXISTING_NODE_ID>",
        "source_node_output_name": "main",
        "target_node_input_name": "main",
        "target_node_input_index": 0
      }
    ]
  }
  

• Add a node and connect immediately (new → existing)

  {
    "workflow_name": "my_first_flow",
    "node_type": "@n8n/n8n-nodes-langchain.lmChatGoogleGemini",
    "position": { "x": 800, "y": 260 },
    "connect_to": [
      {
        "target_node_id": "<AGENT_NODE_ID>",
        "source_node_output_name": "ai_languageModel",
        "target_node_input_name": "ai_languageModel"
      }
    ]
  }