n8n-mcp/README-v2.md

n8n Node Documentation MCP Server

An MCP (Model Context Protocol) server that provides n8n node documentation, source code, and usage examples to AI assistants.

Purpose

This MCP server serves as a knowledge base for AI assistants (like Claude) to understand and work with n8n nodes. It provides:

• Complete node source code - The actual implementation of each n8n node
• Official documentation - Markdown documentation from the n8n-docs repository
• Usage examples - Sample workflow JSON showing how to use each node
• Search capabilities - Full-text search across node names, descriptions, and documentation

Features

• 🔍 Full-text search - Search nodes by name, description, or documentation content
• 📚 Complete documentation - Fetches and indexes official n8n documentation
• 💻 Source code access - Provides full source code for each node
• 🎯 Usage examples - Generates example workflows for each node type
• 🔄 Auto-rebuild - Rebuilds the entire database on startup or on demand
• ⚡ Fast SQLite storage - All data stored locally for instant access

Installation

Prerequisites

• Node.js 18+
• n8n instance (for node extraction)
• Git (for cloning n8n-docs)

Setup

# Clone the repository
git clone https://github.com/yourusername/n8n-mcp.git
cd n8n-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Rebuild the database with all nodes
npm run db:rebuild

Usage with Claude Desktop

1. Configure Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "n8n-nodes": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-mcp/dist/index-v2.js"],
      "env": {
        "NODE_DB_PATH": "/absolute/path/to/n8n-mcp/data/nodes.db",
        "REBUILD_ON_START": "false"
      }
    }
  }
}

2. Available MCP Tools

Once configured, you can ask Claude to:

• List all n8n nodes: "Show me all available n8n nodes"
• Get node information: "Show me the IF node documentation and code"
• Search for nodes: "Find all webhook-related nodes"
• Get examples: "Show me an example of using the HTTP Request node"

MCP Tools Reference

list_nodes

Lists all available n8n nodes with basic information.

Parameters:
- category (optional): Filter by category
- packageName (optional): Filter by package
- isTrigger (optional): Show only trigger nodes

get_node_info

Gets complete information about a specific node including source code, documentation, and examples.

Parameters:
- nodeType (required): The node type (e.g., "n8n-nodes-base.if", "If", "webhook")

search_nodes

Searches for nodes by name, description, or documentation content.

Parameters:
- query (required): Search query
- category (optional): Filter by category
- hasDocumentation (optional): Only show nodes with docs
- limit (optional): Max results (default: 20)

get_node_example

Gets example workflow JSON for a specific node.

Parameters:
- nodeType (required): The node type

get_node_source_code

Gets only the source code of a node.

Parameters:
- nodeType (required): The node type
- includeCredentials (optional): Include credential definitions

get_node_documentation

Gets only the documentation for a node.

Parameters:
- nodeType (required): The node type
- format (optional): "markdown" or "plain" (default: markdown)

Database Management

Initial Setup

# Build and populate the database
npm run db:rebuild

Database Structure

The SQLite database stores:

• Node source code
• Official documentation from n8n-docs
• Generated usage examples
• Node metadata (category, triggers, webhooks, etc.)

Rebuild Process

The rebuild process:

1. Clears the existing database
2. Fetches latest n8n-docs repository
3. Extracts source code from all n8n nodes
4. Fetches documentation for each node
5. Generates usage examples
6. Stores everything in SQLite with full-text search

Example Responses

IF Node Example

When asking for the IF node, the server returns:

{
  "nodeType": "n8n-nodes-base.if",
  "name": "If",
  "displayName": "If",
  "description": "Route items based on comparison operations",
  "sourceCode": "// Full TypeScript source code...",
  "documentation": "# If Node\n\nThe If node splits a workflow...",
  "exampleWorkflow": {
    "nodes": [{
      "parameters": {
        "conditions": {
          "options": {
            "caseSensitive": true,
            "leftValue": "",
            "typeValidation": "strict",
            "version": 2
          },
          "conditions": [{
            "id": "871274c8-dabf-465a-a6cf-655a1786aa55",
            "leftValue": "={{ $json }}",
            "rightValue": "",
            "operator": {
              "type": "object",
              "operation": "notEmpty",
              "singleValue": true
            }
          }],
          "combinator": "and"
        },
        "options": {}
      },
      "type": "n8n-nodes-base.if",
      "typeVersion": 2.2,
      "position": [220, 120],
      "id": "64b5d49f-ac2e-4456-bfa9-2d6eb9c7a624",
      "name": "If"
    }],
    "connections": {
      "If": {
        "main": [[], []]
      }
    }
  }
}

Development

Running in Development Mode

# Start with auto-reload
npm run dev

# Run tests
npm test

# Type checking
npm run typecheck

Environment Variables

# Database location
NODE_DB_PATH=/path/to/nodes.db

# Rebuild database on server start
REBUILD_ON_START=true

# Logging
LOG_LEVEL=debug

# Documentation repository location (optional)
DOCS_REPO_PATH=/path/to/n8n-docs

Architecture

n8n-mcp/
├── src/
│   ├── mcp/
│   │   ├── server-v2.ts      # MCP server implementation
│   │   └── tools-v2.ts       # MCP tool definitions
│   ├── services/
│   │   └── node-documentation-service.ts  # Database service
│   ├── utils/
│   │   ├── documentation-fetcher.ts       # n8n-docs fetcher
│   │   ├── example-generator.ts           # Example generator
│   │   └── node-source-extractor.ts       # Source extractor
│   └── scripts/
│       └── rebuild-database-v2.ts         # Database rebuild
└── data/
    └── nodes.db              # SQLite database

Troubleshooting

Database not found

npm run db:rebuild

No documentation for some nodes

Some nodes may not have documentation in the n8n-docs repository. The server will still provide source code and generated examples.

Rebuild takes too long

The initial rebuild processes 500+ nodes and fetches documentation. Subsequent starts use the cached database unless REBUILD_ON_START=true.

License

ISC