# czlonkowski/n8n-mcp architecture

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

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

## Overview

n8n-MCP is an MCP server that gives AI assistants structured access to n8n node knowledge and tools for managing workflows. The main path is an assistant making MCP requests, tool dispatch into discovery, validation, or management handlers, and—where requested—calls to an n8n instance. The repository also documents templates, community-node discovery, and UI results as product capabilities. Storage and parsing support the knowledge layer. Several subsystem links are documented rather than verified in sampled implementation; those links are dashed, and unsampled internals are not inferred.

Main entry points: [`src/mcp/server.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/server.ts) (MCP Server), [`src/database/node-repository.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/database/node-repository.ts) (Node Repository), [`src/mcp/handlers-n8n-manager.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/handlers-n8n-manager.ts) (n8n Handlers), [`src/services/workflow-validator.ts`](https://github.com/czlonkowski/n8n-mcp/blob/main/src/services/workflow-validator.ts) (Workflow Validator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP Runtime"]
  node_server["MCP Server<br/>[server.ts]"]
  node_tooldefs["Tool Definitions<br/>[tools.ts]"]
  node_managerdefs["Management Tools"]
end

subgraph group_knowledge["Node Knowledge"]
  node_nodeparser["Node Parser<br/>[node-parser.ts]"]
end

subgraph group_workflow["Workflow Tools"]
  node_n8nhandlers["n8n Handlers"]
  node_officialhandlers["Official MCP Tools"]
  node_n8nclient["n8n API Client<br/>[n8n-api-client.ts]"]
  node_diffhandlers["Workflow Diff Handlers"]
  node_diffengine["Diff Engine"]
  node_workflowvalidator["Workflow Validator"]
  node_configvalidator["Configuration Validator"]
end

subgraph group_extensions["Product Extensions"]
  node_community["Community Nodes"]
  node_templates["Template Library"]
  node_ui["Tool Result UIs<br/>[App.tsx]"]
end

subgraph group_storage["Knowledge Storage"]
  node_repository[("Node Repository<br/>[node-repository.ts]")]
  node_dbadapter["Database Adapter"]
end

node_assistant(("AI Assistant"))
node_n8n["n8n Instance"]
node_db[("Local Database")]

node_assistant -->|"sends MCP requests"| node_server
node_server -->|"dispatches tools"| node_tooldefs
node_server -->|"registers tools"| node_managerdefs
node_managerdefs -.->|"routes management"| node_n8nhandlers
node_n8nhandlers -->|"calls API"| node_n8nclient
node_n8nclient -.->|"manages workflows"| node_n8n
node_server -->|"dispatches tools"| node_officialhandlers
node_officialhandlers -.->|"uses instance MCP"| node_n8n
node_n8nhandlers -.->|"applies workflow diffs"| node_diffengine
node_diffhandlers -->|"uses diff engine"| node_diffengine
node_diffhandlers -->|"validates workflows"| node_workflowvalidator
node_workflowvalidator -->|"validates node settings"| node_configvalidator
node_workflowvalidator -->|"reads node data"| node_repository
node_server -.->|"serves node discovery"| node_repository
node_repository -->|"parses node data"| node_nodeparser
node_repository -->|"uses adapter"| node_dbadapter
node_dbadapter -.->|"reads and writes"| node_db
node_server -.->|"offers community search"| node_community
node_server -.->|"offers template search"| node_templates
node_server -->|"serves tool interfaces"| node_ui

click node_server "https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/server.ts"
click node_tooldefs "https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/tools.ts"
click node_managerdefs "https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/tools-n8n-manager.ts"
click node_n8nhandlers "https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/handlers-n8n-manager.ts"
click node_officialhandlers "https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/handlers-official-tools.ts"
click node_n8nclient "https://github.com/czlonkowski/n8n-mcp/blob/main/src/services/n8n-api-client.ts"
click node_diffhandlers "https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/handlers-workflow-diff.ts"
click node_diffengine "https://github.com/czlonkowski/n8n-mcp/blob/main/src/services/workflow-diff-engine.ts"
click node_workflowvalidator "https://github.com/czlonkowski/n8n-mcp/blob/main/src/services/workflow-validator.ts"
click node_configvalidator "https://github.com/czlonkowski/n8n-mcp/blob/main/src/services/enhanced-config-validator.ts"
click node_nodeparser "https://github.com/czlonkowski/n8n-mcp/blob/main/src/parsers/node-parser.ts"
click node_community "https://github.com/czlonkowski/n8n-mcp/blob/main/src/community/community-node-service.ts"
click node_templates "https://github.com/czlonkowski/n8n-mcp/blob/main/src/templates/template-service.ts"
click node_ui "https://github.com/czlonkowski/n8n-mcp/blob/main/ui-apps/src/apps/validation-summary/App.tsx"
click node_repository "https://github.com/czlonkowski/n8n-mcp/blob/main/src/database/node-repository.ts"
click node_dbadapter "https://github.com/czlonkowski/n8n-mcp/blob/main/src/database/database-adapter.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_tooldefs,node_managerdefs toneBlue
class node_nodeparser,node_db toneAmber
class node_n8nhandlers,node_officialhandlers,node_n8nclient,node_diffhandlers,node_diffengine,node_workflowvalidator,node_configvalidator toneMint
class node_community,node_templates,node_ui toneRose
class node_repository,node_dbadapter,node_assistant,node_n8n toneIndigo
```

## Components

### MCP Runtime

- [MCP Server](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [Tool Definitions](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/tools.ts): `src/mcp/tools.ts`
- [Management Tools](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/tools-n8n-manager.ts): `src/mcp/tools-n8n-manager.ts`

### Node Knowledge

- [Node Parser](https://github.com/czlonkowski/n8n-mcp/blob/main/src/parsers/node-parser.ts): `src/parsers/node-parser.ts`

### Workflow Tools

- [n8n Handlers](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/handlers-n8n-manager.ts): `src/mcp/handlers-n8n-manager.ts`
- [Official MCP Tools](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/handlers-official-tools.ts): `src/mcp/handlers-official-tools.ts`
- [n8n API Client](https://github.com/czlonkowski/n8n-mcp/blob/main/src/services/n8n-api-client.ts): `src/services/n8n-api-client.ts`
- [Workflow Diff Handlers](https://github.com/czlonkowski/n8n-mcp/blob/main/src/mcp/handlers-workflow-diff.ts): `src/mcp/handlers-workflow-diff.ts`
- [Diff Engine](https://github.com/czlonkowski/n8n-mcp/blob/main/src/services/workflow-diff-engine.ts): `src/services/workflow-diff-engine.ts`
- [Workflow Validator](https://github.com/czlonkowski/n8n-mcp/blob/main/src/services/workflow-validator.ts): `src/services/workflow-validator.ts`
- [Configuration Validator](https://github.com/czlonkowski/n8n-mcp/blob/main/src/services/enhanced-config-validator.ts): `src/services/enhanced-config-validator.ts`

### Product Extensions

- [Community Nodes](https://github.com/czlonkowski/n8n-mcp/blob/main/src/community/community-node-service.ts): `src/community/community-node-service.ts`
- [Template Library](https://github.com/czlonkowski/n8n-mcp/blob/main/src/templates/template-service.ts): `src/templates/template-service.ts`
- [Tool Result UIs](https://github.com/czlonkowski/n8n-mcp/blob/main/ui-apps/src/apps/validation-summary/App.tsx): `ui-apps/src/apps/validation-summary/App.tsx`

### Knowledge Storage

- [Node Repository](https://github.com/czlonkowski/n8n-mcp/blob/main/src/database/node-repository.ts): `src/database/node-repository.ts`
- [Database Adapter](https://github.com/czlonkowski/n8n-mcp/blob/main/src/database/database-adapter.ts): `src/database/database-adapter.ts`

### Other components

- **AI Assistant**
- **n8n Instance**
- **Local Database**

## Connections

- AI Assistant → MCP Server: sends MCP requests (evidence: `README.md`)
- MCP Server → Tool Definitions: dispatches tools (evidence: `src/mcp/server.ts`)
- MCP Server → Management Tools: registers tools (evidence: `src/mcp/server.ts`)
- Management Tools → n8n Handlers: routes management
- n8n Handlers → n8n API Client: calls API (evidence: `src/mcp/handlers-n8n-manager.ts`)
- n8n API Client → n8n Instance: manages workflows
- MCP Server → Official MCP Tools: dispatches tools (evidence: `src/mcp/server.ts`)
- Official MCP Tools → n8n Instance: uses instance MCP
- n8n Handlers → Diff Engine: applies workflow diffs
- Workflow Diff Handlers → Diff Engine: uses diff engine (evidence: `src/mcp/handlers-workflow-diff.ts`)
- Workflow Diff Handlers → Workflow Validator: validates workflows (evidence: `src/mcp/handlers-workflow-diff.ts`)
- Workflow Validator → Configuration Validator: validates node settings (evidence: `src/services/workflow-validator.ts`)
- Workflow Validator → Node Repository: reads node data (evidence: `src/services/workflow-validator.ts`)
- MCP Server → Node Repository: serves node discovery (evidence: `src/mcp/server.ts`)
- Node Repository → Node Parser: parses node data (evidence: `src/database/node-repository.ts`)
- Node Repository → Database Adapter: uses adapter (evidence: `src/database/node-repository.ts`)
- Database Adapter → Local Database: reads and writes
- MCP Server → Community Nodes: offers community search
- MCP Server → Template Library: offers template search (evidence: `src/mcp/server.ts`)
- MCP Server → Tool Result UIs: serves tool interfaces (evidence: `src/mcp/server.ts`)
