n8n-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

n8n-mcp is a comprehensive documentation and knowledge server that provides AI assistants with complete access to n8n node information through the Model Context Protocol (MCP). It serves as a bridge between n8n's workflow automation platform and AI models, enabling them to understand and work with n8n nodes effectively.

✅ Latest Updates (v2.7.4)

Update (v2.7.4) - Self-Documenting MCP Tools:

• ✅ RENAMED: start_here_workflow_guide → tools_documentation - More descriptive name
• ✅ NEW: Depth parameter - Control documentation detail level with "essentials" or "full"
• ✅ NEW: Per-tool documentation - Get help for any specific tool by name
• ✅ Concise by default - Essential info only, unless full depth requested
• ✅ LLM-friendly format - Plain text, not JSON for better readability
• ✅ Two-tier documentation:
  • Essentials: Brief description, key parameters, example, performance, 2-3 tips
  • Full: Complete documentation with all parameters, examples, use cases, best practices, pitfalls
• ✅ Quick reference - Call without parameters for immediate help
• ✅ 8 documented tools - Comprehensive docs for most commonly used tools
• ✅ Performance guidance - Clear indication of which tools are fast vs slow
• ✅ Error prevention - Common pitfalls documented upfront

Update (v2.7.0) - Diff-Based Workflow Editing with Transactional Updates:

• ✅ NEW: n8n_update_partial_workflow tool - Update workflows using diff operations for precise, incremental changes
• ✅ RENAMED: n8n_update_workflow → n8n_update_full_workflow - Clarifies that it replaces the entire workflow
• ✅ NEW: WorkflowDiffEngine - Applies targeted edits without sending full workflow JSON
• ✅ 80-90% token savings - Only send the changes, not the entire workflow
• ✅ 13 diff operations - addNode, removeNode, updateNode, moveNode, enableNode, disableNode, addConnection, removeConnection, updateConnection, updateSettings, updateName, addTag, removeTag
• ✅ Smart node references - Use either node ID or name for operations
• ✅ Transaction safety - Validates all operations before applying any changes
• ✅ Validation-only mode - Test your diff operations without applying them
• ✅ Comprehensive test coverage - All operations and edge cases tested
• ✅ Example guide - See workflow-diff-examples.md for usage patterns
• ✅ FIXED: MCP validation error - Simplified schema to fix "additional properties" error in Claude Desktop
• ✅ FIXED: n8n API validation - Updated cleanWorkflowForUpdate to remove all read-only fields
• ✅ FIXED: Claude Desktop compatibility - Added additionalProperties: true to handle extra metadata from Claude Desktop
• ✅ NEW: Transactional Updates - Two-pass processing allows adding nodes and connections in any order
• ✅ Operation Limit - Maximum 5 operations per request ensures reliability
• ✅ Order Independence - Add connections before nodes - engine handles dependencies automatically