# nerding-io/n8n-nodes-mcp architecture

> Architecture diagram of the GitHub repository nerding-io/n8n-nodes-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nerding-io/n8n-nodes-mcp
- Repository: https://github.com/nerding-io/n8n-nodes-mcp

## Overview

##### Main Components
- n8n Workflow Engine (External) – The orchestrator that loads and runs community nodes.
- MCP Client Node – The primary component in this project. It is integrated into n8n workflows and is responsible for (a) executing tools, (b) listing available prompts/resources, and (c) generally facilitating communication with an MCP server.
- Credential Management – There are two types of credentials for handling the different transport mechanisms:
◦ STDIO-based Credentials (with command, arguments, and environment variables)
◦ SSE-based Credentials (with SSE URL, message endpoint, and headers)
- External MCP Servers – Represent the actual MCP servers (e.g., Brave Search, OpenAI, Weather, etc.) with which the client node communicates.
- Environment & Configuration Files – Files such as package.json, tsconfig.json, gulpfile.js, and various configuration files (e.g., ESLint, Prettier) that indicate project setup and tooling.
- Testing Infrastructure – The __tests__ folder (e.g., McpClient.test.ts) indicating unit tests for the node functions.

##### Relationship and Interactions Between Components
- n8n loads the MCP Client node, which then connects to an MCP server using one of the two supported transports.
- The node obtains operational parameters and connection details via credentials specified by the user. These credentials are stored/configured (see the credentials folder) and are passed along as either command-line (STDIO) arguments or interfaced through SSE endpoints.
- Environment variables and Docker configurations (as explained in the README) are used to securely pass sensitive information and to enable tool usage within n8n.
- The MCP Client node exposes various operations (List Tools, Execute Tool, Get Prompt, etc.) that n8n workflows can call. Each operation results in a request-response to/from the external MCP server.

##### Architectural Patterns and Design Principles
- Separation of Concerns: “Nodes” handle workflow integration in n8n, while the credential management abstracts away the details of communicating, whether over STDIO or SSE.
- Modular Design: Credentials and node implementations are separated into different directories, suggesting a clear modular approach.
- Extensibility: With clearly defined operations (e.g., List Tools, Execute Tool), the design anticipates adding more tools or capabilities without heavily coupling to core functionality.

##### Relevant Technologies and Frameworks
- Node.js and TypeScript (the presence of tsconfig.json and .ts files) – the core language and runtime.
- Testing Framework: Jest (with jest.config.js) for unit testing.
- Build Tools: gulpfile.js for build tasks.
- Static Code Analysis: ESLint, Prettier, etc.
- n8n as the underlying workflow automation engine.

##### Elements
- Data flow from n8n initiating a workflow.
- Requests from the MCP Client node to an external MCP server.
- Return flows for tool execution, resource listings, etc.

- In the center, show the MCP Client Node as the core module, possibly divided into subcomponents:
▫ Credential Handling (with two branches: STDIO and SSE).
▫ Operation Handlers (Execute Tool, List Tools, etc.).
- On the right, represent External MCP Servers, indicating that they might be multiple (Brave Search, OpenAI, etc.) depending on user configuration.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Component
    n1["n8n Workflow Engine"]:::external

    %% Internal MCP Client Node with Credential Handling
    n2["MCP Client Node"]:::internal
    n21["STDIO Credential Manager"]:::credential
    n22["SSE Credential Manager"]:::credential

    %% External MCP Servers
    n3["External MCP Server(s)"]:::external

    %% Support Components: Environment & Config Files and Testing
    subgraph "Project Support"
        p1["Project Setup & Configurations"]:::config
        t1["Testing Infrastructure"]:::test
    end

    %% Flow Connections
    n1 -->|"initiates-workflow"| n2
    n2 -->|"STDIO:Command+ArgsEnvVars"| n21
    n2 -->|"SSE:SSEStream"| n22
    n2 -->|"toolExecution/GetPrompt"| n3
    p1 -->|"runtime-configs"| n2
    n2 -->|"unit-tests"| t1

    %% Click Events for Components
    click n2 "https://github.com/nerding-io/n8n-nodes-mcp/blob/main/nodes/McpClient/McpClient.node.ts"
    click n21 "https://github.com/nerding-io/n8n-nodes-mcp/blob/main/credentials/McpClientApi.credentials.ts"
    click n22 "https://github.com/nerding-io/n8n-nodes-mcp/blob/main/credentials/McpClientSseApi.credentials.ts"
    click t1 "https://github.com/nerding-io/n8n-nodes-mcp/blob/main/__tests__/McpClient.test.ts"
    click p1 "https://github.com/nerding-io/n8n-nodes-mcp/blob/main/package.json"

    %% Styles
    classDef internal fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef external fill:#ABEBC6,stroke:#239B56,stroke-width:2px;
    classDef credential fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef config fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef test fill:#E8DAEF,stroke:#7D3C98,stroke-width:2px;
```
