# coleam00/n8n-nodes-mcp architecture

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

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

## Overview

##### Project type and purpose
- This is an n8n community-node package written in TypeScript/JavaScript.
- Purpose: provide an MCP Client node for n8n workflows, allowing users to connect to Model Context Protocol (MCP) servers via STDIO or Server-Sent Events (SSE), list tools/prompts/resources, and execute tools.

##### File structure
- Top level: configuration files (.eslintrc, tsconfig.json, gulpfile.js), CI/CD workflows (.github/workflows), tests (__tests__), credentials definitions (credentials/*.credentials.ts), the published entry point (index.js), and the main node implementation under nodes/McpClient/.
- Build pipeline: gulpfile.js orchestrates TypeScript compilation and bundling.
- Testing: Jest config in jest.config.js and tests in __tests__ folder.
- Packaging: package.json, .npmignore, and lockfiles for npm/pnpm.

##### README for additional insights
- Describes two transport mechanisms—STDIO (spawning MCP server processes) and SSE (long-lived HTTP connections).
- Outlines credential schemes, environment variable usage, and example workflows (Brave Search, multi-server, local SSE).
- Emphasizes use inside n8n’s plugin/AI Agent ecosystem.

a. Main components
- n8n Core Platform – hosts workflows and community nodes
- MCP Client Node – plugin loaded by n8n, implements node logic & UI
- Credentials Store – where n8n saves command/arguments, SSE URLs, headers, env-vars
- Transport Layer
– STDIO Transport: spawns MCP server process (child_process)
– SSE Transport: opens EventSource connection + HTTP POST endpoint
- MCP Server(s) – external services (e.g., Brave Search, OpenAI, Serper, Weather)
- Build & CI/CD Pipeline – gulp build, Jest tests, GitHub Actions, publishing to npm

b. Relationships & interactions
1. Developer commits code → GitHub CI runs lint/test/build → package published
2. At runtime, n8n loads community-nodes folder → registers MCP Client node
3. User drags MCP Client node into workflow → selects transport & credentials
4. Node executes:
- STDIO: spawn MCP server with configured command, arguments, env-vars → communicate via stdin/stdout JSON messages
- SSE: open EventSource to SSE URL, send operations via HTTP POST → listen for server-sent events
5. MCP Server processes requests → returns tool lists, prompts, resource data, or executes tools → responses flow back to node → n8n displays outputs

c. Architectural patterns & design principles
- Plugin/extension pattern: node implements n8n’s NodeInterface and credential types
- Strategy pattern for transports: abstract common operations behind STDIO or SSE modules
- Separation of concerns: UI/credentials definitions, core node logic, transport implementations, and tests
- Event-driven I/O for SSE transport; process spawning for STDIO transport

d. Key technologies & libraries
- TypeScript/JavaScript, Node.js
- n8n Node API (Node Interface, Credential Interface)
- child_process for STDIO transport
- EventSource or fetch for SSE transport
- Gulp for build tasks; Jest for testing
- GitHub Actions for CI/CD

##### Detail
- File/folder names where relevant (e.g., build script gulpfile.js, test suite __tests__).
- Both STDIO and SSE transport modules and their unique communication channels.
- External dependency list (Brave Search server, OpenAI server, etc.) as MCP servers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer & Repo
    Dev["Developer"]:::pipeline
    Repo["Code Repository"]:::pipeline
    click Repo "https://github.com/coleam00/n8n-nodes-mcp/blob/main/."

    %% CI/CD Pipeline
    subgraph "Build & CI/CD Pipeline"
        direction TB
        CI["GitHub Actions CI/CD"]:::pipeline
        PR["GitHub Actions PR Validation"]:::pipeline
        Gulp["Build: gulpfile.js"]:::pipeline
        Jest["Test: jest.config.js & __tests__"]:::pipeline
        Publish["Publish to npm"]:::pipeline
        click CI "https://github.com/coleam00/n8n-nodes-mcp/blob/main/.github/workflows/ci-cd.yml"
        click PR "https://github.com/coleam00/n8n-nodes-mcp/blob/main/.github/workflows/pr-validation.yml"
        click Gulp "https://github.com/coleam00/n8n-nodes-mcp/blob/main/gulpfile.js"
        click Jest "https://github.com/coleam00/n8n-nodes-mcp/blob/main/jest.config.js"
        click Publish "https://github.com/coleam00/n8n-nodes-mcp/blob/main/package.json"
    end

    %% Runtime Components
    subgraph "Runtime Environment"
        direction TB
        n8n["n8n Core Platform"]:::runtime
        CredStore(("[Credentials Store]")):::config
        subgraph "MCP Client Node"
            direction TB
            Node["MCP Client Node"]:::runtime
            click Node "https://github.com/coleam00/n8n-nodes-mcp/blob/main/nodes/McpClient/McpClient.node.ts"
            subgraph "Transports"
                direction TB
                STDIO["STDIO Transport"]:::runtime
                SSE["SSE Transport"]:::runtime
            end
        end
        subgraph "External MCP Servers"
            direction TB
            Brave["Brave Search Server"]:::external
            OpenAI["OpenAI Server"]:::external
            Serper["Serper Server"]:::external
            Weather["Weather Server"]:::external
        end
        Index["Entry Point: index.js"]:::config
        click Index "https://github.com/coleam00/n8n-nodes-mcp/blob/main/index.js"
        subgraph "Credentials Definitions"
            direction TB
            CredentialsSTDIO["STDIO Credentials"]:::config
            CredentialsSSE["SSE Credentials"]:::config
            click CredentialsSTDIO "https://github.com/coleam00/n8n-nodes-mcp/blob/main/credentials/McpClientApi.credentials.ts"
            click CredentialsSSE "https://github.com/coleam00/n8n-nodes-mcp/blob/main/credentials/McpClientSseApi.credentials.ts"
        end
        TSConfig["tsconfig.json"]:::config
        ESLint1[".eslintrc.js"]:::config
        ESLint2[".eslintrc.prepublish.js"]:::config
        JestConfig["jest.config.js"]:::config
        click TSConfig "https://github.com/coleam00/n8n-nodes-mcp/blob/main/tsconfig.json"
        click ESLint1 "https://github.com/coleam00/n8n-nodes-mcp/blob/main/.eslintrc.js"
        click ESLint2 "https://github.com/coleam00/n8n-nodes-mcp/blob/main/.eslintrc.prepublish.js"
        click JestConfig "https://github.com/coleam00/n8n-nodes-mcp/blob/main/jest.config.js"
    end

    %% Test Suite mapping
    TestSuite["Test Suite: McpClient.test.ts"]:::pipeline
    click TestSuite "https://github.com/coleam00/n8n-nodes-mcp/blob/main/__tests__/McpClient.test.ts"

    %% Flows
    Dev --> Repo
    Repo --> CI
    CI --> Gulp
    CI --> Jest
    CI --> Publish

    %% Runtime registration
    n8n -->|loads community-nodes| Node
    Node -->|uses| CredStore
    CredStore -->|provides| Node
    Node -->|spawns| STDIO
    Node -->|opens| SSE
    STDIO -->|stdin/stdout JSON| Brave
    STDIO -->|stdin/stdout JSON| OpenAI
    SSE -->|HTTP POST / EventSource| Serper
    SSE -->|HTTP POST / EventSource| Weather
    Node -->|exposed via| Index

    %% Styles
    classDef runtime fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef config fill:#E6FFEA,stroke:#22863A,color:#22863A;
    classDef pipeline fill:#FFF5E6,stroke:#D97706,color:#D97706;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
```
