n8n-mcp/docs/mcp-tools-documentation.md

MCP Tools Documentation for LLMs

This document provides comprehensive documentation for the most commonly used MCP tools in the n8n-mcp server. Each tool includes parameters, return formats, examples, and best practices.

Table of Contents

1. search_nodes
2. get_node_essentials
3. list_nodes
4. validate_node_minimal
5. validate_node_operation
6. get_node_for_task
7. n8n_create_workflow
8. n8n_update_partial_workflow

---

search_nodes

Brief Description: Search for n8n nodes by keywords in names and descriptions.

Parameters

• query (string, required): Search term - single word recommended for best results
• limit (number, optional): Maximum results to return (default: 20)

Return Format

{
  "nodes": [
    {
      "nodeType": "nodes-base.slack",
      "displayName": "Slack",
      "description": "Send messages to Slack channels"
    }
  ],
  "totalFound": 5
}

Common Use Cases

1. Finding integration nodes: search_nodes("slack") to find Slack integration
2. Finding HTTP nodes: search_nodes("http") for HTTP/webhook nodes
3. Finding database nodes: search_nodes("postgres") for PostgreSQL nodes

Examples

// Search for Slack-related nodes
{
  "query": "slack",
  "limit": 10
}

// Search for webhook nodes
{
  "query": "webhook",
  "limit": 20
}

Performance Notes

• Fast operation (cached results)
• Single-word queries are more precise
• Returns results with OR logic (any word matches)

Best Practices

• Use single words for precise results: "slack" not "send slack message"
• Try shorter terms if no results: "sheet" instead of "spreadsheet"
• Search is case-insensitive
• Common searches: "http", "webhook", "email", "database", "slack"

Common Pitfalls

• Multi-word searches return too many results (OR logic)
• Searching for exact phrases doesn't work
• Node types aren't searchable here (use exact type with get_node_info)

Related Tools

• list_nodes - Browse nodes by category
• get_node_essentials - Get node configuration after finding it
• list_ai_tools - Find AI-capable nodes specifically

---

get_node_essentials

Brief Description: Get only the 10-20 most important properties for a node with working examples.

Parameters

• nodeType (string, required): Full node type with prefix (e.g., "nodes-base.httpRequest")

Return Format

{
  "nodeType": "nodes-base.httpRequest",
  "displayName": "HTTP Request",
  "essentialProperties": [
    {
      "name": "method",
      "type": "options",
      "default": "GET",
      "options": ["GET", "POST", "PUT", "DELETE"],
      "required": true
    },
    {
      "name": "url",
      "type": "string",
      "required": true,
      "placeholder": "https://api.example.com/endpoint"
    }
  ],
  "examples": [
    {
      "name": "Simple GET Request",
      "configuration": {
        "method": "GET",
        "url": "https://api.example.com/users"
      }
    }
  ],
  "tips": [
    "Use expressions like {{$json.url}} to make URLs dynamic",
    "Enable 'Split Into Items' for array responses"
  ]
}

Common Use Cases

1. Quick node configuration: Get just what you need without parsing 100KB+ of data
2. Learning node basics: Understand essential properties with examples
3. Building workflows efficiently: 95% smaller responses than get_node_info

Examples

// Get essentials for HTTP Request node
{
  "nodeType": "nodes-base.httpRequest"
}

// Get essentials for Slack node
{
  "nodeType": "nodes-base.slack"
}

// Get essentials for OpenAI node
{
  "nodeType": "nodes-langchain.openAi"
}

Performance Notes

• Very fast (<5KB responses vs 100KB+ for full info)
• Curated for 20+ common nodes
• Automatic fallback for unconfigured nodes

Best Practices

• Always use this before get_node_info
• Node type must include prefix: "nodes-base.slack" not "slack"
• Check examples section for working configurations
• Use tips section for common patterns

Common Pitfalls

• Forgetting the prefix in node type
• Using wrong package name (n8n-nodes-base vs @n8n/n8n-nodes-langchain)
• Case sensitivity in node types

Related Tools

• get_node_info - Full schema when essentials aren't enough
• search_node_properties - Find specific properties
• get_node_for_task - Pre-configured for common tasks

---

list_nodes

Brief Description: List available n8n nodes with optional filtering by package, category, or capabilities.

Parameters

• package (string, optional): Filter by exact package name
• category (string, optional): Filter by category (trigger, transform, output, input)
• developmentStyle (string, optional): Filter by implementation style
• isAITool (boolean, optional): Filter for AI-capable nodes
• limit (number, optional): Maximum results (default: 50, max: 500)

Return Format

{
  "nodes": [
    {
      "nodeType": "nodes-base.webhook",
      "displayName": "Webhook",
      "description": "Receive HTTP requests",
      "categories": ["trigger"],
      "version": 2
    }
  ],
  "total": 104,
  "hasMore": false
}

Common Use Cases

1. Browse all triggers: list_nodes({category: "trigger", limit: 200})
2. List all nodes: list_nodes({limit: 500})
3. Find AI nodes: list_nodes({isAITool: true})
4. Browse core nodes: list_nodes({package: "n8n-nodes-base"})

Examples

// List all trigger nodes
{
  "category": "trigger",
  "limit": 200
}

// List all AI-capable nodes
{
  "isAITool": true,
  "limit": 100
}

// List nodes from core package
{
  "package": "n8n-nodes-base",
  "limit": 200
}

Performance Notes

• Fast operation (cached results)
• Default limit of 50 may miss nodes - use 200+
• Returns metadata only, not full schemas

Best Practices

• Always set limit to 200+ for complete results
• Use exact package names: "n8n-nodes-base" not "@n8n/n8n-nodes-base"
• Categories are singular: "trigger" not "triggers"
• Common categories: trigger (104), transform, output, input

Common Pitfalls

• Default limit (50) misses many nodes
• Using wrong package name format
• Multiple filters may return empty results

Related Tools

• search_nodes - Search by keywords
• list_ai_tools - Specifically for AI nodes
• get_database_statistics - Overview of all nodes

---

validate_node_minimal

Brief Description: Quick validation checking only for missing required fields.

Parameters

• nodeType (string, required): Node type to validate (e.g., "nodes-base.slack")
• config (object, required): Node configuration to check

Return Format

{
  "valid": false,
  "missingRequired": ["channel", "messageType"],
  "message": "Missing 2 required fields"
}

Common Use Cases

1. Quick validation: Check if all required fields are present
2. Pre-flight check: Validate before creating workflow
3. Minimal overhead: Fastest validation option

Examples

// Validate Slack message configuration
{
  "nodeType": "nodes-base.slack",
  "config": {
    "resource": "message",
    "operation": "send",
    "text": "Hello World"
    // Missing: channel
  }
}

// Validate HTTP Request
{
  "nodeType": "nodes-base.httpRequest",
  "config": {
    "method": "POST"
    // Missing: url
  }
}

Performance Notes

• Fastest validation option
• No schema loading overhead
• Returns only missing fields

Best Practices

• Use for quick checks during workflow building
• Follow up with validate_node_operation for complex nodes
• Check operation-specific requirements

Common Pitfalls

• Doesn't validate field values or types
• Doesn't check operation-specific requirements
• Won't catch configuration errors beyond missing fields

Related Tools

• validate_node_operation - Comprehensive validation
• validate_workflow - Full workflow validation

---

validate_node_operation

Brief Description: Comprehensive node configuration validation with operation awareness and helpful error messages.

Parameters

• nodeType (string, required): Node type to validate
• config (object, required): Complete node configuration including operation fields
• profile (string, optional): Validation profile (minimal, runtime, ai-friendly, strict)

Return Format

{
  "valid": false,
  "errors": [
    {
      "field": "channel",
      "message": "Channel is required to send Slack message",
      "suggestion": "Add channel: '#general' or '@username'"
    }
  ],
  "warnings": [
    {
      "field": "unfurl_links",
      "message": "Consider setting unfurl_links: false for better performance"
    }
  ],
  "examples": {
    "minimal": {
      "resource": "message",
      "operation": "send",
      "channel": "#general",
      "text": "Hello World"
    }
  }
}

Common Use Cases

1. Complex node validation: Slack, Google Sheets, databases
2. Operation-specific checks: Different rules per operation
3. Getting fix suggestions: Helpful error messages with solutions

Examples

// Validate Slack configuration
{
  "nodeType": "nodes-base.slack",
  "config": {
    "resource": "message",
    "operation": "send",
    "text": "Hello team!"
  },
  "profile": "ai-friendly"
}

// Validate Google Sheets operation
{
  "nodeType": "nodes-base.googleSheets",
  "config": {
    "operation": "append",
    "sheetId": "1234567890",
    "range": "Sheet1!A:Z"
  },
  "profile": "runtime"
}

Performance Notes

• Slower than minimal validation
• Loads full node schema
• Operation-aware validation rules

Best Practices

• Use "ai-friendly" profile for balanced validation
• Check examples in response for working configurations
• Follow suggestions to fix errors
• Essential for complex nodes (Slack, databases, APIs)

Common Pitfalls

• Forgetting operation fields (resource, operation, action)
• Using wrong profile (too strict or too lenient)
• Ignoring warnings that could cause runtime issues

Related Tools

• validate_node_minimal - Quick required field check
• get_property_dependencies - Understand field relationships
• validate_workflow - Validate entire workflow

---

get_node_for_task

Brief Description: Get pre-configured node settings for common automation tasks.

Parameters

• task (string, required): Task identifier (e.g., "post_json_request", "receive_webhook")

Return Format

{
  "task": "post_json_request",
  "nodeType": "nodes-base.httpRequest",
  "displayName": "HTTP Request",
  "configuration": {
    "method": "POST",
    "url": "={{ $json.api_endpoint }}",
    "responseFormat": "json",
    "options": {
      "bodyContentType": "json"
    },
    "bodyParametersJson": "={{ JSON.stringify($json) }}"
  },
  "userMustProvide": [
    "url - The API endpoint URL",
    "bodyParametersJson - The JSON data to send"
  ],
  "tips": [
    "Use expressions to make values dynamic",
    "Enable 'Split Into Items' for batch processing"
  ]
}

Common Use Cases

1. Quick task setup: Configure nodes for specific tasks instantly
2. Learning patterns: See how to configure nodes properly
3. Common workflows: Standard patterns like webhooks, API calls, database queries

Examples

// Get configuration for JSON POST request
{
  "task": "post_json_request"
}

// Get webhook receiver configuration
{
  "task": "receive_webhook"
}

// Get AI chat configuration
{
  "task": "chat_with_ai"
}

Performance Notes

• Instant response (pre-configured templates)
• No database lookups required
• Includes working examples

Best Practices

• Use list_tasks first to see available options
• Check userMustProvide section
• Follow tips for best results
• Common tasks: API calls, webhooks, database queries, AI chat

Common Pitfalls

• Not all tasks available (use list_tasks)
• Configuration needs customization
• Some fields still need user input

Related Tools

• list_tasks - See all available tasks
• get_node_essentials - Alternative approach
• search_templates - Find complete workflow templates

---

n8n_create_workflow

Brief Description: Create a new workflow in n8n with nodes and connections.

Parameters

• name (string, required): Workflow name
• nodes (array, required): Array of node definitions
• connections (object, required): Node connections mapping
• settings (object, optional): Workflow settings

Return Format

{
  "id": "workflow-uuid",
  "name": "My Workflow",
  "active": false,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "nodes": [...],
  "connections": {...}
}

Common Use Cases

1. Automated workflow creation: Build workflows programmatically
2. Template deployment: Deploy pre-built workflow patterns
3. Multi-workflow systems: Create interconnected workflows

Examples

// Create simple webhook → HTTP request workflow
{
  "name": "Webhook to API",
  "nodes": [
    {
      "id": "webhook-1",
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [250, 300],
      "parameters": {
        "path": "/my-webhook",
        "httpMethod": "POST"
      }
    },
    {
      "id": "http-1",
      "name": "HTTP Request",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [450, 300],
      "parameters": {
        "method": "POST",
        "url": "https://api.example.com/process",
        "responseFormat": "json"
      }
    }
  ],
  "connections": {
    "Webhook": {
      "main": [[{"node": "HTTP Request", "type": "main", "index": 0}]]
    }
  }
}

Performance Notes

• API call to n8n instance required
• Workflow created in inactive state
• Must be manually activated in UI

Best Practices

• Always include typeVersion for nodes
• Use node names (not IDs) in connections
• Position nodes logically ([x, y] coordinates)
• Test with validate_workflow first
• Start simple, add complexity gradually

Common Pitfalls

• Missing typeVersion causes errors
• Using node IDs instead of names in connections
• Forgetting required node properties
• Creating cycles in connections
• Workflow can't be activated via API

Related Tools

• validate_workflow - Validate before creating
• n8n_update_partial_workflow - Modify existing workflows
• n8n_trigger_webhook_workflow - Execute workflows

---

n8n_update_partial_workflow

Brief Description: Update workflows using diff operations for precise, incremental changes without sending the entire workflow.

Parameters

• id (string, required): Workflow ID to update
• operations (array, required): Array of diff operations (max 5)
• validateOnly (boolean, optional): Test without applying changes

Return Format

{
  "success": true,
  "workflow": {
    "id": "workflow-uuid",
    "name": "Updated Workflow",
    "nodes": [...],
    "connections": {...}
  },
  "appliedOperations": 3
}

Common Use Cases

1. Add nodes to existing workflows: Insert new functionality
2. Update node configurations: Change parameters without full replacement
3. Manage connections: Add/remove node connections
4. Quick edits: Rename, enable/disable nodes, update settings

Examples

// Add a new node and connect it
{
  "id": "workflow-123",
  "operations": [
    {
      "type": "addNode",
      "node": {
        "id": "set-1",
        "name": "Set Data",
        "type": "n8n-nodes-base.set",
        "typeVersion": 3,
        "position": [600, 300],
        "parameters": {
          "values": {
            "string": [{
              "name": "status",
              "value": "processed"
            }]
          }
        }
      }
    },
    {
      "type": "addConnection",
      "source": "HTTP Request",
      "target": "Set Data"
    }
  ]
}

// Update multiple properties
{
  "id": "workflow-123",
  "operations": [
    {
      "type": "updateName",
      "name": "Production Workflow v2"
    },
    {
      "type": "updateNode",
      "nodeName": "Webhook",
      "changes": {
        "parameters.path": "/v2/webhook"
      }
    },
    {
      "type": "addTag",
      "tag": "production"
    }
  ]
}

Performance Notes

• 80-90% token savings vs full updates
• Maximum 5 operations per request
• Two-pass processing handles dependencies
• Transactional: all or nothing

Best Practices

• Use validateOnly: true to test first
• Keep operations under 5 for reliability
• Operations can be in any order (v2.7.0+)
• Use node names, not IDs in operations
• For updateNode, use dot notation for nested paths

Common Pitfalls

• Exceeding 5 operations limit
• Using node IDs instead of names
• Forgetting required node properties in addNode
• Not testing with validateOnly first

Related Tools

• n8n_update_full_workflow - Complete workflow replacement
• n8n_get_workflow - Fetch current workflow state
• validate_workflow - Validate changes before applying

---

Quick Reference

Workflow Building Process

1. Discovery: search_nodes → list_nodes
2. Configuration: get_node_essentials → get_node_for_task
3. Validation: validate_node_minimal → validate_node_operation
4. Creation: validate_workflow → n8n_create_workflow
5. Updates: n8n_update_partial_workflow

Performance Tips

• Use get_node_essentials instead of get_node_info (95% smaller)
• Set high limits on list_nodes (200+)
• Use single words in search_nodes
• Validate incrementally while building

Common Node Types

• Triggers: webhook, schedule, emailReadImap, slackTrigger
• Core: httpRequest, code, set, if, merge, splitInBatches
• Integrations: slack, gmail, googleSheets, postgres, mongodb
• AI: agent, openAi, chainLlm, documentLoader

Error Prevention

• Always include node type prefixes: "nodes-base.slack"
• Use node names (not IDs) in connections
• Include typeVersion in all nodes
• Test with validateOnly before applying changes
• Check userMustProvide sections in templates