DOCSEARCHbyAlgolia
Submit Docs

n8n Workflow Builder MCP Server

repository·main·Indexed 42 days ago

https://github.com/salacoste/mcp-n8n-workflow-builder

An AI-powered n8n workflow management tool using the Model Context Protocol (MCP). It enables developers to create, manage, and monitor n8n workflows through natural language via Claude AI or Cursor IDE. Version 0.9.3 features multi-instance architecture for managing multiple environments (Dev, Staging, Prod) and includes tools for workflow, execution, tag, and credential management.

Tokens
238.2K
Snippets
582
Records
994
Agent score
49%

What's inside n8n Workflow Builder

  1. Overview of n8n-workflow-builder MCP Tools

    main

    The n8n-workflow-builder MCP server provides 17 tools organized into four primary functional categories to automate n8n via natural language or MCP-compatible clients (like Claude Desktop).

    Tool Categories

    1. Workflows Management (8 tools): Operations for listing, creating, retrieving, updating, patching, deleting, activating, and deactivating workflows.
    2. Executions Management (4 tools): Operations for listing, getting, deleting, and retrying workflow executions.
    3. Tags Management (5 tools): Operations for creating, retrieving, and deleting tags.
    4. Credentials Management (6 tools): Operations for listing, getting, creating, updating, deleting, and inspecting credential schemas.

    Key Capabilities

    • Multi-Instance Support: Most tools accept an optional instance parameter to route requests to specific n8n environments managed by the EnvironmentManager.
    • MCP Resources: The server exposes data via the MCP Resources system using URI patterns like /workflows and /executions/{id}.
    • Schema Validation: All tool inputs are validated against JSON schemas defined in the server implementation.

  2. Overview of n8n Workflow Management Tools

    main

    The mcp-n8n-workflow-builder MCP server provides 8 core tools for managing n8n workflows via Claude Desktop. These tools allow for full lifecycle management including creation, retrieval, modification, and execution.

    Key Capabilities:

    • Lifecycle Management: Create, read, update, delete, activate, and deactivate workflows.
    • Execution: Manually trigger workflows.
    • Multi-Instance Support: Every tool accepts an optional instance parameter to route requests to specific n8n environments (e.g., production, staging, development). If no instance is specified, the server uses the default environment.
    • Performance Optimization: The list_workflows tool is optimized to return only streamlined metadata (ID, name, status, dates, node count, tags) rather than full JSON to prevent client crashes.

  3. Overview of Executions API operations

    main

    The Executions API allows you to programmatically monitor, debug, and manage workflow executions across different n8n instances. It provides access to execution history, detailed data, and recovery capabilities.

    Available Operations:

    • list_executions: List execution history (useful for monitoring, debugging, and analytics).
    • get_execution: Retrieve detailed execution data (useful for root cause analysis).
    • delete_execution: Remove execution records (useful for cleanup or compliance).
    • retry_execution: Retry failed executions (useful for error recovery).

  4. What is n8n MCP Workflow Builder?

    main

    n8n MCP Workflow Builder is an MCP (Model Context Protocol) server that enables AI assistants like Claude to create, manage, and monitor n8n workflows through natural language interactions.

    Key Features:

    • AI-Native: Natural language workflow creation via Claude Desktop.
    • Multi-Instance: Manage multiple n8n environments (production, staging, development).
    • 17 MCP Tools: Complete workflow, execution, credential, and tag management.
    • 4 Resources: Dynamic workflow and execution data access.
    • 5 Prompts: Pre-built workflow templates for common patterns.
    • Secure: Schema-driven credential management with encryption.

  5. Overview of Executions Management Tools

    main

    The MCP server provides several tools for managing n8n workflow executions, categorized by their operational purpose:

    • Query operations: Retrieve execution history and details (list_executions, get_execution).
    • Maintenance operations: Remove execution records (delete_execution).
    • Recovery operations: Retry failed executions (retry_execution).

    These tools allow for monitoring, debugging, and maintaining the health of your n8n automation environment.

  6. Overview of Test Scripts

    main

    The testing infrastructure is divided into a main comprehensive suite and several specialized scripts for specific domains.

    Main Test Suite

    • test-mcp-tools.js: Tests Workflow CRUD, activation, tag management, execution management, multi-instance routing, and error handling.

    Specialized Test Scripts

    • Credential Tests: test-credentials-all-methods-direct.js, test-credentials-api-direct.js, test-credentials-create.js, test-credentials-delete-and-schema.js, test-credentials-informative-messages.js.
    • Workflow Tests: test-activate-methods.js, test-patch-workflow.js, test-workflows-validation.js.
    • Tag Tests: test-check-tags.js, test-create-tag-simple.js, test-different-tag-names.js, test-tags-validation.js.
    • Execution Tests: test-executions-validation.js, test-retry-quick.js.
    • Integration Tests: test-comprehensive.js, test-e2e-all-tools.js.

    Unit Tests (Jest)

    Located in src/services/__tests__/, these cover the service layer, API wrappers, configuration loading, and multi-instance logic.

  7. Overview of MCP Server Tools and Categories

    main

    The mcp-n8n-workflow-builder provides a total of 17 MCP tools categorized into four main functional areas. This allows for comprehensive automation of n8n workflows, executions, tagging, and credential management.

    Tool Categories:

    • Workflows (8 tools): Covers the complete workflow lifecycle.
    • Executions (4 tools): Includes management and the retry_execution capability.
    • Tags (5 tools): Provides full CRUD (Create, Read, Update, Delete) operations for workflow tags.
    • Credentials (6 tools): Provides credential lifecycle management (3 full implementation tools and 3 informative tools).

  8. Overview of n8n API Implementation Status

    main

    The n8n Workflow Builder MCP server implements 24 REST API methods across four main categories. As of the documentation audit for version 0.10.0, the implementation targets 100% completion across all categories.

    API Categories and Method Counts

    • Workflows API: 9 methods (includes PATCH /workflows/{id})
    • Executions API: 4 methods (includes POST /executions/{id}/retry)
    • Credentials API: 6 methods (includes GET, POST, PUT, DELETE for credentials and credential testing)
    • Tags API: 5 methods

    Implementation Tracking

    Users and maintainers can track the progress of implementation and validation via the status tables in the project documentation. The target for version 0.10.0 is 24/24 methods implemented and validated.

  9. Overview of n8n REST API capabilities

    main

    The n8n REST API (v1) provides programmatic access to the n8n automation platform, allowing you to perform tasks via HTTP requests that are typically done in the GUI. The API is resource-based and follows standard REST principles using JSON for data exchange.

    Core Capabilities:

    • Workflows Management: Create, list, retrieve, update (full/partial), delete, activate/deactivate, clone, and export workflows.
    • Executions Monitoring: View execution history, get execution details, filter by status/workflow/date, retry failed executions, and delete history.
    • Credentials Management: Create, list, update, delete, and manage access to credentials for external services. (Note: While part of the n8n API, Credentials management is not implemented in the n8n-workflow-builder MCP server).
    • Tags Organization: Create, list, update, delete, and assign tags to workflows for classification.

  10. Overview of MCP Tools Categories

    main

    The mcp-n8n-workflow-builder provides 17 specialized MCP tools organized into four primary functional categories. These tools allow an AI agent or developer to interact with an n8n instance to manage workflows, monitor executions, organize with tags, and handle credentials.

    Tool Categories

    1. Workflows (8 tools): Foundational tools for the lifecycle of an n8n workflow, including listing, creating, retrieving, updating, patching, deleting, activating, and deactivating workflows.
    2. Executions (4 tools): Tools for monitoring and managing workflow runs, including listing executions, getting specific execution details, deleting executions, and retrying failed executions.
    3. Tags (5 tools): Tools for organizing workflows using the n8n tagging system, including creating, getting (list or single), updating, and deleting tags.
    4. Credentials (6 tools): Security-focused tools for managing n8n credentials, including listing, retrieving, creating, updating, deleting, and fetching credential schemas.

    Key Capabilities

    • Multi-Instance Support: All tools support routing requests to different n8n instances based on your configuration.
    • Schema-Driven: Tool parameters and credential creation are driven by strict schemas defined in the implementation.

  11. Overview of Execution Management Tools

    main

    The execution management tools allow you to monitor, analyze, and manage the history of workflow runs in n8n. You can track workflow runs, analyze failures, retry failed executions, and clean up execution history.

    Available Tools

    ToolPurposeFiltersPagination
    list_executionsGet execution historystatus, workflowId, includeData✅ Cursor
    get_executionGet detailed execution dataincludeData❌
    delete_executionRemove execution record-❌
    retry_executionRetry failed execution-❌

    Execution Lifecycle

    1. Trigger: Workflow starts.
    2. Execution: Nodes execute and data flows.
    3. Completion: Success or failure is recorded.
    4. Inspection: Use list_executions or get_execution to view history.
    5. Retry (Optional): Use retry_execution if a run failed.
    6. Cleanup (Optional): Use delete_execution to remove records.

  12. Overview of n8n REST API coverage in MCP

    main

    The mcp-n8n-workflow-builder project aims to provide full coverage of the n8n REST API through Model Context Protocol (MCP) tools. The implementation is organized into several functional categories:

    • Workflows: Managing workflow lifecycle (list, get, create, update, delete, activate, deactivate, and manual execution).
    • Executions: Managing workflow execution history (list, get, delete, and retry).
    • Tags: Managing workflow tags (list, get, create, update, and delete).
    • Credentials: Managing authentication credentials (list, get, create, update, delete, and schema retrieval).

    Note that execute_workflow is an MCP-specific wrapper and not a standard n8n REST API endpoint.