n8n-workflow-builder

Exposes standardized MCP tools (create_workflow, get_workflow, update_workflow, delete_workflow, list_workflows) that translate natural language requests from Claude/ChatGPT into n8n HTTP API calls with JSON payload validation. The server implements tool handlers that parse MCP tool requests, validate workflow schema compliance, and forward authenticated requests to the n8n instance, returning structured workflow metadata (ID, name, nodes, connections, active status) back to the client.

Provides activate_workflow and deactivate_workflow MCP tools that toggle the active status of n8n workflows without modifying their definitions. These tools call n8n's state-change endpoints, returning confirmation of the new active/inactive status. The implementation handles idempotent state transitions (activating an already-active workflow returns success without error) and tracks execution history changes when workflows are toggled.

Reads and validates required environment variables (N8N_HOST, N8N_API_KEY) at server startup, ensuring the server can connect to n8n before accepting client requests. The implementation checks that N8N_HOST is a valid URL and N8N_API_KEY is non-empty, returning startup errors if configuration is missing or invalid. The server logs configuration status (without exposing sensitive values) for debugging.

Provides TypeScript type definitions for all MCP tools, resources, and n8n API responses, enabling type-safe development and IDE autocompletion. The implementation includes runtime type checking for incoming MCP requests and outgoing n8n API responses, catching type mismatches before they cause runtime errors. The server exports type definitions for use by client applications and extensions.

Exposes list_executions and get_execution MCP tools that query n8n's execution history with optional filters (workflow ID, status, date range) and pagination support. The server translates MCP tool parameters into n8n API query strings, retrieves execution records with full details (execution ID, status, start/end time, error messages, output data), and returns paginated result sets. The get_execution tool retrieves detailed execution logs including node-by-node execution traces.

Provides delete_execution MCP tool that removes execution records from n8n's history. The tool calls n8n's execution deletion endpoint, which cascades cleanup of associated logs, output data, and temporary files. The implementation returns confirmation of deletion and validates that the execution exists before attempting removal, preventing errors from deleting non-existent records.

Exposes HTTP resources (static and dynamic templates) that provide efficient context access to workflow definitions and execution details without requiring separate MCP tool calls. Static resources (/workflows, /execution-stats) return aggregated data (all workflows, execution statistics), while dynamic resource templates (/workflows/{id}, /executions/{id}) return detailed information for specific resources. The server implements resource handlers that fetch data from n8n API and format it as MCP resources, allowing clients to include workflow context directly in prompts without tool invocation overhead.

Implements secure authentication to n8n instances using API keys passed via N8N_API_KEY environment variable, with automatic header injection (X-N8N-API-KEY) on all HTTP requests. The server maintains a persistent connection to the n8n API endpoint (N8N_HOST) and reuses HTTP connections through Node.js's built-in connection pooling, reducing latency for repeated requests. The implementation handles authentication errors (401, 403) and returns structured error messages to MCP clients.

Defines MCP tool schemas for all workflow and execution management operations, specifying required parameters, types, descriptions, and constraints. The server uses these schemas to validate incoming MCP tool requests before forwarding to n8n API, rejecting invalid parameters with structured error messages. The implementation follows MCP specification for tool definition, enabling AI assistants to discover available tools and their parameters through schema introspection.

Implements comprehensive error handling across all MCP tool and resource handlers, catching n8n API errors (4xx, 5xx responses) and translating them into structured MCP error responses. The server categorizes errors (authentication, validation, not found, server error) and returns descriptive error messages with relevant context (failed parameter, API status code, n8n error details). The implementation prevents sensitive information (API keys, internal paths) from leaking in error messages.

Implements the Model Context Protocol (MCP) server using stdio-based communication, where the server reads JSON-RPC requests from stdin and writes responses to stdout. The implementation uses the MCP SDK for Node.js to handle protocol serialization, message framing, and bidirectional communication with MCP clients (Claude Desktop, ChatGPT, custom clients). The server maintains a persistent connection to the client and processes tool requests and resource queries asynchronously.

Handles conversion between n8n's internal workflow graph format (nodes array, connections array, settings object) and JSON representations suitable for transmission via MCP. The implementation preserves workflow structure (node IDs, connection references, parameter bindings) during serialization and validates that deserialized workflows conform to n8n's schema before sending to API. The server supports both full workflow definitions and partial updates.