### Setup Development Environment

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/INSTALLATION.md

Copies the example environment file and prompts to edit it for development setup. Requires manual installation prerequisites.

```bash
cp .env.example .env
# Edit .env with your settings
```

--------------------------------

### Setting up Webhooks with Essentials

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/MCP_ESSENTIALS_README.md

Example of using `get_node_essentials` to configure a webhook node. It shows how to get essentials and start with a minimal example, then modify properties like the path.

```javascript
// Get webhook essentials
const essentials = get_node_essentials("nodes-base.webhook");

// Start with minimal
const config = essentials.examples.minimal;
config.path = "my-webhook-endpoint";
```

--------------------------------

### Local Installation and Build Commands

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/README.md

Steps to clone the n8n-mcp repository, install dependencies, build the project, and start the application locally for development.

```bash
# 1. Clone and setup
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
npm run rebuild

# 2. Test it works
npm start
```

--------------------------------

### Install Docker on Linux (Ubuntu/Debian)

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/README.md

Install Docker using apt-get, start and enable the service, and optionally add the user to the docker group.

```bash
# Update package index
sudo apt-get update

# Install Docker
sudo apt-get install docker.io

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Add your user to docker group (optional, to run without sudo)
sudo usermod -aG docker $USER
# Log out and back in for this to take effect
```

--------------------------------

### Local Development Setup for n8n-MCP (Without Docker)

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/HTTP_DEPLOYMENT.md

Use this for local development when not using Docker. It involves cloning the repository, installing dependencies, building the project, and starting the HTTP server with environment variables.

```bash
# 1. Clone and setup
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
npm run rebuild

# 2. Configure environment
export MCP_MODE=http
export AUTH_TOKEN=$(openssl rand -base64 32)
export PORT=3000

# 3. Start server
npm run start:http
```

--------------------------------

### Quick Start with Docker

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/INSTALLATION.md

The fastest way to get n8n-MCP running using Docker. Requires Docker and Docker Compose.

```bash
cat > .env << EOF
AUTH_TOKEN=$(openssl rand -base64 32)
EOF
docker compose up -d
```

--------------------------------

### Clone and Build n8n-mcp Locally

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/README.md

Clone the repository, optionally clone n8n docs, install dependencies, build the project, initialize the database, and start the server. Use `npm start` for stdio mode or `npm run start:http` for remote access.

```bash
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp

git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs

npm install
npm run build

npm run rebuild

npm start          # stdio mode for Claude Desktop
npm run start:http # HTTP mode for remote access
```

--------------------------------

### Correct SerpApi Tool Configuration Example

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/FINAL_AI_VALIDATION_SPEC.md

Demonstrates a correctly configured SerpApi tool with valid credentials and a helpful description. This is an example of proper setup.

```typescript
{
  type: '@n8n/n8n-nodes-langchain.toolSerpApi',
  name: 'Google Search',
  credentials: {
    serpApi: 'serpapi_credentials_id'
  },
  parameters: {
    description: 'Search Google for current news, recent events, and general web information. Use when you need up-to-date information from the internet.'
  }
}
// Valid: Has credentials and helpful description
```

--------------------------------

### Webhook Node Configuration Examples

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/local/TEMPLATE_MINING_ANALYSIS.md

Demonstrates configurations for a Webhook node, covering basic setup with HTTP methods and response modes, as well as handling binary data.

```json
{
  "path": "ytube",
  "options": {},
  "httpMethod": "POST",
  "responseMode": "responseNode"
}
```

```json
{
  "path": "your-endpoint",
  "options": {
    "binaryPropertyName": "data"
  },
  "httpMethod": "POST"
}
```

--------------------------------

### Manual Local Setup for n8n-MCP

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/N8N_DEPLOYMENT.md

Configure and start n8n-MCP locally for development or custom testing. Ensure your n8n instance is running and you have an API key.

```bash
# Set environment variables
export N8N_MODE=true
export MCP_MODE=http                       # Required for HTTP mode
export N8N_API_URL=http://localhost:5678  # Your n8n instance URL
export N8N_API_KEY=your-api-key-here       # Your n8n API key
export MCP_AUTH_TOKEN=test-token-minimum-32-chars-long
export AUTH_TOKEN=test-token-minimum-32-chars-long  # Same value as MCP_AUTH_TOKEN
export PORT=3001

# Start the server
npm start
```

--------------------------------

### Install Docker on Windows

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/README.md

Install Docker Desktop on Windows using winget, Chocolatey, or by downloading the installer.

```bash
# Option 1: Using winget (Windows Package Manager)
winget install Docker.DockerDesktop

# Option 2: Using Chocolatey
choco install docker-desktop

# Option 3: Download installer from https://www.docker.com/products/docker-desktop/
```

--------------------------------

### Vector Store Tool Configuration Example

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/FINAL_AI_VALIDATION_SPEC.md

This example shows a correctly configured Vector Store Tool node for a complete RAG setup. It includes the required 'name' and 'description' parameters, along with an optional 'topK' value.

```typescript
{
  type: 'toolVectorStore',
  name: 'Search Knowledge Base',
  parameters: {
    name: 'search_docs',
    description: 'Searches our product documentation and knowledge base articles to answer customer questions',
    topK: 5
  }
}
```

--------------------------------

### Example Prompt for Agent Mode

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/VS_CODE_PROJECT_SETUP.md

An example prompt to guide GitHub Copilot Chat in agent mode for building an n8n workflow based on external content and specific tools.

```markdown
#fetch https://blog.n8n.io/rag-chatbot/

use #sequentialthinking and #n8n-mcp tools to build a new n8n workflow step-by-step following the guidelines in the blog.
In the end, please deploy a fully-functional n8n workflow.
```

--------------------------------

### Test MCP tool with includeExamples

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/P0-R3-TEST-PLAN.md

Example of how to use the MCP tool to search nodes, including examples.

```javascript
search_nodes({query: "webhook", includeExamples: true})
```

--------------------------------

### Test MCP tool for node essentials with includeExamples

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/P0-R3-TEST-PLAN.md

Example of how to retrieve node essentials from the MCP tool, including examples.

```javascript
get_node_essentials({nodeType: "nodes-base.webhook", includeExamples: true})
```

--------------------------------

### Install and Build n8n-MCP Locally

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/README_CLAUDE_SETUP.md

Use these commands to clone the n8n-MCP repository, install dependencies, and build the project for local use.

```bash
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
npm run rebuild
```

--------------------------------

### Install Docker on macOS

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/README.md

Use Homebrew or download the installer for Docker Desktop on macOS.

```bash
# Using Homebrew
brew install --cask docker

# Or download from https://www.docker.com/products/docker-desktop/
```

--------------------------------

### Search Nodes by Keyword with Examples

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/ANTIGRAVITY_SETUP.md

Find nodes relevant to a keyword and include example configurations. Useful for understanding node capabilities.

```javascript
search_nodes({query: 'keyword', includeExamples: true})
```

--------------------------------

### Enhance get_node_essentials with Examples

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/local/P0_IMPLEMENTATION_PLAN.md

Updates the `get_node_essentials` handler to optionally include real-world examples from popular templates. This provides users with practical configuration examples for a given node type.

```APIDOC
## Function: getNodeEssentials

### Description
Retrieves essential information about a specific n8n node type, with an option to include real-world configuration examples.

### Parameters
#### Arguments
- **nodeType** (string) - Required - The full node type (e.g., "n8n-nodes-base.httpRequest").
- **options** (object) - Optional - Configuration options.
  - **includeExamples** (boolean) - Optional - If true, includes 2-3 real configuration examples from popular templates. Defaults to false.

### Returns
- **Promise<object>** - An object containing node essentials, potentially including an `examples` array if `includeExamples` is true.
```

--------------------------------

### Database Operations with Essentials

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/MCP_ESSENTIALS_README.md

Example of using `get_node_essentials` to configure a database node, such as for PostgreSQL. It demonstrates retrieving essentials, checking available operations, and using common examples.

```javascript
// Get database essentials
const essentials = get_node_essentials("nodes-base.postgres");

// Check available operations
const operations = essentials.operations;

// Use appropriate example
const config = essentials.examples.common;
```

--------------------------------

### Rebuild Database for Docker/Manual Install

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/INSTALLATION.md

Run this command to rebuild the database. Use `docker compose exec` for Docker installations.

```bash
# For Docker
docker compose exec n8n-mcp npm run rebuild
```

```bash
# For manual installation
npm run rebuild
```

--------------------------------

### Install Dependencies for Manual Installation

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/INSTALLATION.md

Installs all necessary Node.js dependencies for n8n-MCP. Requires Node.js v16+ and npm or yarn.

```bash
npm install
```

--------------------------------

### Set Node Configuration Example

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/local/N8N_AI_WORKFLOW_BUILDER_ANALYSIS.md

Example of configuring parameters for a Set node, including adding fields with static values, current dates, or data from previous nodes.

```typescript
{
  nodeId: "set-node-456",
  changes: [
    "Add field 'status' with value 'processed'",
    "Add field 'timestamp' with current date",
    "Add field 'userId' from previous HTTP Request node"
  ]
}
```

--------------------------------

### Default Calculator Tool Example

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/FINAL_AI_VALIDATION_SPEC.md

An example of a correctly configured default Calculator tool. No specific parameters are required for basic functionality.

```typescript
{
  type: '@n8n/n8n-nodes-langchain.toolCalculator',
  name: 'Calculator'
}
// Valid: No configuration needed, works with defaults
```

--------------------------------

### Copying Example Environment File

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/tests/setup/TEST_ENV_DOCUMENTATION.md

Troubleshoot missing test environment variables by copying the example .env file to .env.test. This ensures all required variables are present.

```bash
cp .env.test.example .env.test
```

--------------------------------

### Install Node.js and npx

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/HTTP_DEPLOYMENT.md

If 'npx' command is not found, install Node.js version 18 or later. Alternatively, find and use the full path to npx.

```bash
# Install Node.js 18+ which includes npx
# Or use full path:
which npx  # Find npx location
# Use that path in Claude config
```

--------------------------------

### Start Services with Docker Compose

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/N8N_HTTP_STREAMABLE_SETUP.md

Use this command to stop existing containers and start n8n and n8n-mcp services with HTTP Streamable configuration.

```bash
# Stop any existing containers
docker stop n8n n8n-mcp && docker rm n8n n8n-mcp

# Start with HTTP Streamable configuration
docker-compose -f docker-compose.n8n.yml up -d

# Services will be available at:
# - n8n: http://localhost:5678
# - n8n-mcp: http://localhost:3000
```

--------------------------------

### Complete IF Node Routing Example

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/ANTIGRAVITY_SETUP.md

This example demonstrates how to use `n8n_update_partial_workflow` to add connections for both the TRUE and FALSE branches of an IF node, ensuring proper logic routing.

```javascript
n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [
    {type: "addConnection", source: "If Node", target: "True Handler", sourcePort: "main", targetPort: "main", branch: "true"},
    {type: "addConnection", source: "If Node", target: "False Handler", sourcePort: "main", targetPort: "main", branch: "false"}
  ]
})
```

--------------------------------

### Basic Test Setup with Database Utilities

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/tests/utils/README.md

Demonstrates the basic setup for a test case using the database utilities. It shows how to create an in-memory database, seed test nodes, and clean up the database after the test.

```typescript
import { createTestDatabase, seedTestNodes, dbHelpers } from '../utils/database-utils';

describe('My Test', () => {
  let testDb;
  
  afterEach(async () => {
    if (testDb) await testDb.cleanup();
  });
  
  it('should test something', async () => {
    // Create in-memory database
    testDb = await createTestDatabase();
    
    // Seed test data
    await seedTestNodes(testDb.nodeRepository);
    
    // Run your tests
    const node = testDb.nodeRepository.getNode('nodes-base.httpRequest');
    expect(node).toBeDefined();
  });
});
```

--------------------------------

### Clone and Run n8n-MCP Integration Test

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/N8N_DEPLOYMENT.md

Use this script to quickly test n8n-MCP locally. It sets up a Dockerized n8n instance, starts n8n-MCP, and guides through API key setup for integration testing.

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

# Build the project
npm install
npm run build

# Run the integration test script
./scripts/test-n8n-integration.sh
```

--------------------------------

### AI Agent Prompt for Workflow Creation

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/N8N_DEPLOYMENT.md

An example prompt to guide an AI agent in using MCP tools for n8n workflow creation, including searching for nodes, getting configurations, validating, and creating workflows.

```text
You are an n8n workflow expert. Use the MCP tools to:
1. Search for appropriate nodes using search_nodes
2. Get configuration details with get_node_essentials
3. Validate configurations with validate_workflow
4. Create the workflow if all validations pass
```

--------------------------------

### Invalid Function Name Example

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/FINAL_AI_VALIDATION_SPEC.md

An example of an incorrect Code Tool configuration where the function name starts with a number, which is not permitted.

```typescript
{
  type: 'toolCode',
  name: 'Calculate Tax',
  parameters: {
    name: '3rd_party_calculator',  // ❌ Starts with number
    description: 'Calculates sales tax',
    code: 'return price * 0.085;'
  }
}
```

--------------------------------

### Get Node Essentials with Examples

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/local/P0_IMPLEMENTATION_PLAN.md

Tests the retrieval of essential node information, including examples, for a specified node type. Verifies that examples are returned and contain expected properties.

```typescript
describe('Enhanced Tools with Examples', () => {
  it('get_node_essentials should return examples when requested', async () => {
    const result = await getNodeEssentials('n8n-nodes-base.httpRequest', {
      includeExamples: true
    });

    expect(result.examples).toBeDefined();
    expect(result.examples.length).toBeGreaterThan(0);
    expect(result.examples[0].config).toHaveProperty('url');
  });

  it('search_nodes should return examples when requested', async () => {
    const result = await searchNodes('webhook', { includeExamples: true });

    expect(result.length).toBeGreaterThan(0);
    expect(result[0].examples).toBeDefined();
  });

  it('get_node_for_task should not exist', async () => {
    expect(toolRegistry.has('get_node_for_task')).toBe(false);
  });
});
```

--------------------------------

### tools_documentation

Source: https://context7.com/evolv3ai/n8n-mcp/llms.txt

Returns the built-in quick-reference guide for all available MCP tools. Call without arguments for a quick-start overview, or supply a `topic` matching a specific tool name for deeper documentation.

```APIDOC
## MCP Tool: `tools_documentation`

### Description
Returns the built-in quick-reference guide for all available MCP tools. Call without arguments for a quick-start overview, or supply a `topic` matching a specific tool name for deeper documentation.

### Parameters
#### Query Parameters
- **topic** (string) - Optional - The specific tool name to get documentation for.
- **depth** (string) - Optional - The level of detail for the documentation. Can be "essentials" (default) or "full".

### Request Example (TypeScript)
```typescript
const result = await client.callTool("tools_documentation", {
  topic: "search_nodes",
  depth: "full"
});
console.log(result.content[0].text);
```

### Response Example
```
// Returns markdown documentation for the search_nodes tool
```
```

--------------------------------

### JSON Configuration Example (Works)

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/README.md

This JSON configuration works because all necessary parameters, like 'select' and 'channelId', are explicitly defined.

```json
{
  "resource": "message",
  "operation": "post",
  "select": "channel",
  "channelId": "C123",
  "text": "Hello"
}
```

--------------------------------

### Create .env File and Start Services

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/N8N_DEPLOYMENT.md

Generates a .env file with authentication tokens and starts the necessary services using Docker Compose. Ensure you save the generated AUTH_TOKEN.

```bash
AUTH_TOKEN=$(openssl rand -hex 32)
cat > .env << EOF
N8N_API_URL=https://your-n8n-instance.com
N8N_API_KEY=your-n8n-api-key-here
MCP_AUTH_TOKEN=$AUTH_TOKEN
AUTH_TOKEN=$AUTH_TOKEN
EOF

# Save the AUTH_TOKEN!
echo "Your AUTH_TOKEN is: $AUTH_TOKEN"
echo "Save this token - you'll need it in n8n MCP Client Tool configuration"

# Start services
docker compose up -d
```

--------------------------------

### Get Documentation for Specific Tools

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/tools-documentation-usage.md

Retrieve detailed documentation for a list of specified tools, including parameters, examples, and best practices.

```json
{
  "name": "tools_documentation",
  "arguments": {
    "tools": ["search_nodes", "get_node_essentials"]
  }
}
```

--------------------------------

### Example: Learning About search_nodes

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/tools-documentation-usage.md

Request documentation for the 'search_nodes' tool to understand its usage, performance characteristics, common searches, and pitfalls.

```json
{
  "name": "tools_documentation",
  "arguments": {
    "tools": ["search_nodes"]
  }
}
```

--------------------------------

### Check Logs

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/INSTALLATION.md

Inspect logs to diagnose issues. Use `docker compose logs` for Docker or `LOG_LEVEL=debug npm start` for manual installations.

```bash
# Docker
docker compose logs
```

```bash
# Manual: Check console output or 
LOG_LEVEL=debug npm start
```

--------------------------------

### N8NMCPEngine.start

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/LIBRARY_USAGE.md

Starts the MCP engine, preparing it to handle requests.

```APIDOC
## N8NMCPEngine.start

### Description
Starts the MCP engine. This should be called before processing any requests.

### Method
`async start()`
```

--------------------------------

### Calculator Tool with Custom Description

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/FINAL_AI_VALIDATION_SPEC.md

An example of a Calculator tool with a custom description. This helps guide the LLM on its specific use cases for financial calculations.

```typescript
{
  type: '@n8n/n8n-nodes-langchain.toolCalculator',
  name: 'Financial Calculator',
  parameters: {
    description: 'Use for precise financial calculations, tax computations, and percentage calculations. Always use this instead of estimating numbers.'
  }
}
// Valid: Custom description guides LLM on specific use case
```

--------------------------------

### Run n8n-MCP with npx

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/README.md

Execute n8n-MCP directly using npx for a quick local setup. This command downloads and runs the latest version without requiring a global installation.

```bash
npx n8n-mcp
```

--------------------------------

### Building from Scratch: Node Discovery and Configuration

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/ANTIGRAVITY_SETUP.md

This snippet outlines the process of building a workflow from scratch, starting with parallel discovery of relevant nodes using `search_nodes` and then retrieving detailed configuration for them.

```javascript
// STEP 1: Discovery (parallel execution)
[Silent execution]
search_nodes({query: 'slack', includeExamples: true})
search_nodes({query: 'communication trigger'})

// STEP 2: Configuration (parallel execution)
[Silent execution]
get_node({nodeType: 'n8n-nodes-base.slack', detail: 'standard', includeExamples: true})
get_node({nodeType: 'n8n-nodes-base.webhook', detail: 'standard', includeExamples: true})
```

--------------------------------

### Basic Configuration Workflow: HTTP Request

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/MCP_ESSENTIALS_README.md

A recommended workflow for basic configuration of an HTTP Request node. It involves getting essentials, using provided examples, and optionally searching for specific features.

```text
get_node_essentials("nodes-base.httpRequest")
```

```text
search_node_properties("nodes-base.httpRequest", "header")
```

--------------------------------

### Include Quick Reference Guide

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/tools-documentation-usage.md

Request documentation for a specific tool along with a quick reference guide, which includes workflow building process, performance tips, and common patterns.

```json
{
  "name": "tools_documentation",
  "arguments": {
    "tools": ["n8n_create_workflow"],
    "includeQuickReference": true
  }
}
```

--------------------------------

### Correct SearXNG Tool Configuration Example

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/FINAL_AI_VALIDATION_SPEC.md

Demonstrates a correctly configured SearXNG tool node with necessary credentials and a descriptive parameter.

```typescript
{
  type: '@n8n/n8n-nodes-langchain.toolSearXng',
  name: 'Privacy Search',
  credentials: {
    searXng: 'searxng_credentials_id'  // Contains instance URL
  },
  parameters: {
    description: 'Privacy-focused metasearch aggregating results from multiple search engines. Use for general web searches.',
    categories: ['general', 'news']
  }
}
// Valid: Has credentials and configuration
```

--------------------------------

### Get Node Essentials for HTTP Request

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/MCP_ESSENTIALS_README.md

Use this tool to retrieve essential properties for configuring an HTTP Request node. It provides a concise set of common and required properties, along with examples.

```json
{
  "name": "get_node_essentials",
  "arguments": {
    "nodeType": "nodes-base.httpRequest"
  }
}
```

--------------------------------

### Correct WolframAlpha Tool Configuration Example

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/FINAL_AI_VALIDATION_SPEC.md

Shows a properly configured WolframAlpha tool node with API credentials and a detailed usage description.

```typescript
{
  type: '@n8n/n8n-nodes-langchain.toolWolframAlpha',
  name: 'Wolfram Computation',
  credentials: {
    wolframAlpha: 'wolfram_credentials_id'
  },
  parameters: {
    description: 'Use for complex mathematical calculations, scientific computations, unit conversions, and factual data queries (population, distances, dates). NOT for general web search.'
  }
}
// Valid: Has credentials and clear usage guidance
```

--------------------------------

### Think Tool with Custom Description for Complex Reasoning

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/FINAL_AI_VALIDATION_SPEC.md

An example of a Think tool configured with a detailed custom description. This guides the AI agent to use the thinking tool for complex planning and reasoning tasks.

```typescript
{
  type: '@n8n/n8n-nodes-langchain.toolThink',
  name: 'Strategic Planner',
  parameters: {
    description: 'Use this tool when you need to plan a complex multi-step approach, consider trade-offs between options, or validate your reasoning before taking action. Think through edge cases and potential failures.'
  }
}
// Valid: Detailed description guides agent on when to think vs. act
```

--------------------------------

### Building Workflow from Scratch - Node Configuration

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/README.md

This step involves retrieving detailed information for discovered nodes using `get_node`, preparing them for configuration. It's designed for parallel execution.

```javascript
// STEP 2: Configuration (parallel execution)
[Silent execution]
get_node({nodeType: 'n8n-nodes-base.slack', detail: 'standard', includeExamples: true})
get_node({nodeType: 'n8n-nodes-base.webhook', detail: 'standard', includeExamples: true})
```

--------------------------------

### Integration Test Server Setup with MSW

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/tests/mocks/README.md

Provides a dedicated MSW test server for integration tests requiring more control. Use `mswTestServer` to start, stop, and reset the server, and `n8nApiMock` for convenient mocking of n8n API operations.

```typescript
import { mswTestServer, n8nApiMock } from '@tests/integration/setup/msw-test-server';

describe('Integration Tests', () => {
  beforeAll(() => {
    mswTestServer.start({ onUnhandledRequest: 'error' });
  });
  
  afterAll(() => {
    mswTestServer.stop();
  });
  
  afterEach(() => {
    mswTestServer.reset();
  });
  
  it('should test workflow creation', async () => {
    // Use helper to mock workflow creation
    mswTestServer.use(
      n8nApiMock.mockWorkflowCreate({
        id: 'new-workflow',
        name: 'Created Workflow'
      })
    );
    
    // Your test code here
  });
});
```

--------------------------------

### Get Pre-configured n8n API Client for Tests

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/local/integration-testing-plan.md

Provides an n8n API client instance specifically for test utilities like setup and cleanup. This client should not be used within actual test cases, which must use MCP handlers.

```typescript
import { N8nApiClient } from '../../../src/services/n8n-api-client';
import { getN8nCredentials } from './credentials';

/**
 * IMPORTANT: This client is ONLY used for test setup/cleanup utilities.
 * DO NOT use this in actual test cases - use MCP handlers instead!
 *
 * Test utilities that need direct API access:
 * - cleanupOrphanedWorkflows() - bulk cleanup
 * - Fixture setup/teardown
 * - Pre-test verification
 *
 * Actual tests MUST use MCP handlers:
 * - handleCreateWorkflow()
 * - handleGetWorkflow()
 * - etc.
 */
let client: N8nApiClient | null = null;

export function getTestN8nClient(): N8nApiClient {
  if (!client) {
    const creds = getN8nCredentials();
    client = new N8nApiClient(creds.url, creds.apiKey);
  }
  return client;
}

export function resetTestN8nClient(): void {
  client = null;
}
```

--------------------------------

### Print Webhook Setup Instructions

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/local/integration-testing-plan.md

Prints setup instructions for webhook integration tests to the console. It outlines the steps required to create and activate workflows in n8n and specifies the corresponding .env variable names.

```typescript
export function printSetupInstructions(): void {
  console.log(`
╔════════════════════════════════════════════════════════════════╗
║  WEBHOOK WORKFLOW SETUP REQUIRED                               ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  Integration tests require 4 pre-activated webhook workflows:  ║
║                                                                ║
║  1. Create workflows manually in n8n UI                        ║
║  2. Use the configurations shown below                         ║
║  3. ACTIVATE each workflow in n8n UI                           ║
║  4. Copy workflow IDs to .env file                             ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

Required workflows:
`);

  Object.entries(WEBHOOK_WORKFLOW_CONFIGS).forEach(([method, config]) => {
    console.log(`
${method} Method:
  Name: ${config.name}
  Path: ${config.nodes[0].parameters.path}
  .env variable: N8N_TEST_WEBHOOK_${method}_ID
`);
  });
}

```

--------------------------------

### Get MCP Tool Documentation (TypeScript)

Source: https://context7.com/evolv3ai/n8n-mcp/llms.txt

Call the `tools_documentation` MCP tool to retrieve quick-reference guides for available tools. Omit the `topic` argument for a general overview or specify a tool name for detailed documentation. The `depth` argument controls the level of detail.

```typescript
const result = await client.callTool("tools_documentation", {
  topic: "search_nodes",   // omit for overview
  depth: "full"            // "essentials" (default) | "full"
});
console.log(result.content[0].text);
```

--------------------------------

### Update .env.example for Integration Testing

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/local/integration-testing-plan.md

Configure n8n API URL, API key, test webhook URLs, and test-specific settings like cleanup and naming conventions.

```bash
# ========================================
# INTEGRATION TESTING CONFIGURATION
# ========================================

# n8n API Configuration for Integration Tests
N8N_API_URL=http://localhost:5678
N8N_API_KEY=your-api-key-here

# Pre-activated Webhook URLs for Testing
# Create these workflows manually in n8n and activate them
# Store the full webhook URLs (not workflow IDs)
N8N_TEST_WEBHOOK_GET_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-get
N8N_TEST_WEBHOOK_POST_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-post
N8N_TEST_WEBHOOK_PUT_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-put
N8N_TEST_WEBHOOK_DELETE_URL=https://n8n-test.n8n-mcp.com/webhook/mcp-test-delete

# Test Configuration
N8N_TEST_CLEANUP_ENABLED=true           # Enable automatic cleanup
N8N_TEST_TAG=mcp-integration-test       # Tag for test workflows
N8N_TEST_NAME_PREFIX=[MCP-TEST]         # Name prefix for test workflows

```

--------------------------------

### Install n8n-MCP using systemd

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/N8N_DEPLOYMENT.md

Create a systemd service file for n8n-MCP for native installations. Ensure Node.js is installed and the working directory is set correctly.

```bash
sudo cat > /etc/systemd/system/n8n-mcp.service << EOF
[Unit]
Description=n8n-MCP Server
After=network.target

[Service]
Type=simple
User=nodejs
WorkingDirectory=/opt/n8n-mcp
Environment="N8N_MODE=true"
Environment="MCP_MODE=http"
Environment="N8N_API_URL=http://localhost:5678"
Environment="N8N_API_KEY=your-n8n-api-key"
Environment="MCP_AUTH_TOKEN=your-secure-token-32-chars-min"
Environment="AUTH_TOKEN=your-secure-token-32-chars-min"
Environment="PORT=3000"
ExecStart=/usr/bin/node /opt/n8n-mcp/dist/mcp/index.js
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl enable n8n-mcp
sudo systemctl start n8n-mcp
```

--------------------------------

### HTTP Request Node Configuration Example

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/local/N8N_AI_WORKFLOW_BUILDER_ANALYSIS.md

Example of how to configure parameters for an HTTP Request node using natural language instructions. Ensure correct syntax for headers and body.

```typescript
{
  nodeId: "http-node-123",
  changes: [
    "Set the URL to https://api.weather.com/v1/forecast",
    "Set method to POST",
    "Add header Content-Type with value application/json",
    "Set body to { city: {{ $json.city }} }"
  ]
}
```

--------------------------------

### Install n8n-mcp

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/LIBRARY_USAGE.md

Install the n8n-mcp package using npm.

```bash
npm install n8n-mcp
```

--------------------------------

### Enhance searchNodes with Examples (TypeScript)

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/local/P0_IMPLEMENTATION_PLAN.md

Modifies the `searchNodes` handler to optionally include example configurations for each found node when `includeExamples` is true. It queries `template_node_configs` for relevant examples.

```typescript
async function searchNodes(
  query: string,
  options?: {
    limit?: number;
    includeExamples?: boolean;
  }): Promise<any> {
  const nodes = repository.searchNodes(query, 'OR', options?.limit || 20);

  const results = nodes.map(node => {
    const result = {
      nodeType: node.nodeType,
      displayName: node.displayName,
      description: node.description,
      category: node.category
    };

    // NEW: Add examples if requested
    if (options?.includeExamples) {
      const examples = db.prepare(`
        SELECT parameters_json, template_name, complexity
        FROM template_node_configs
        WHERE node_type = ?
        ORDER BY rank
        LIMIT 2
      `).all(node.nodeType);

      result.examples = examples.map(ex => ({
        config: JSON.parse(ex.parameters_json),
        source: ex.template_name,
        complexity: ex.complexity
      }));
    }

    return result;
  });

  return results;
}
```

--------------------------------

### Print Webhook Workflow Setup Instructions

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/local/integration-tests-phase1-summary.md

Generates and prints detailed setup instructions for n8n webhook workflows. This includes necessary environment variables and configuration steps.

```typescript
import { printSetupInstructions } from "./webhook-workflows";

printSetupInstructions();
```

--------------------------------

### Install Claude Skills Plugin (Method 2)

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/CLAUDE_CODE_SETUP.md

Install n8n-skills by first adding a marketplace and then browsing for the plugin. This method allows you to discover and install other available plugins as well.

```bash
# Add as marketplace, then browse and install
/plugin marketplace add czlonkowski/n8n-skills

# Then browse available plugins
/plugin install
# Select "n8n-mcp-skills" from the list
```

--------------------------------

### Display Help for Fetcher Command

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/MEMORY_TEMPLATE_UPDATE.md

This command displays the help information for the `fetch:templates` script, showing all available options and their usage.

```bash
npm run fetch:templates -- --help
```

--------------------------------

### Install Claude Skills Manually (Method 3)

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/CLAUDE_CODE_SETUP.md

Manually install n8n-skills by cloning the repository and copying the skills to your Claude Code skills directory. This method provides more control over the installation process.

```bash
# 1. Clone the repository
git clone https://github.com/czlonkowski/n8n-skills.git

# 2. Copy skills to your Claude Code skills directory
cp -r n8n-skills/skills/* ~/.claude/skills/

# 3. Reload Claude Code
# Skills will activate automatically
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/README.md

Check if Docker is installed correctly by running the version command.

```bash
docker --version
```

--------------------------------

### Implement New Benchmarks with Vitest

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/BENCHMARKS.md

Example of how to write a new performance benchmark suite using Vitest. Configure iterations, warmup, and timing for accurate measurements.

```typescript
import { bench, describe } from 'vitest';

describe('My Performance Suite', () => {
  bench('operation name', async () => {
    // Code to benchmark
  }, {
    iterations: 100,
    warmupIterations: 10,
    warmupTime: 500,
    time: 3000
  });
});
```

--------------------------------

### Complete Multi-Tenant Backend Example

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/LIBRARY_USAGE.md

A full multi-tenant implementation using Express, including authentication, instance management, and MCP request processing with context validation. Ensure database and decryption functions are implemented.

```typescript
import express from 'express';
import { N8NMCPEngine, InstanceContext, validateInstanceContext } from 'n8n-mcp';

const app = express();
const mcpEngine = new N8NMCPEngine({
  sessionTimeout: 3600000, // 1 hour
  logLevel: 'info'
});

// Start MCP engine
await mcpEngine.start();

// Authentication middleware
const authenticate = async (req, res, next) => {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Verify token and attach user to request
  req.user = await getUserFromToken(token);
  next();
};

// Get instance configuration from database
const getInstanceConfig = async (instanceId: string, userId: string) => {
  // Your database logic here
  const instance = await db.instances.findOne({
    where: { id: instanceId, userId }
  });

  if (!instance) {
    throw new Error('Instance not found');
  }

  return {
    n8nApiUrl: instance.n8nUrl,
    n8nApiKey: await decryptApiKey(instance.encryptedApiKey),
    instanceId: instance.id
  };
};

// MCP endpoint with per-instance context
app.post('/api/instances/:instanceId/mcp', authenticate, async (req, res) => {
  try {
    // Get instance configuration
    const instance = await getInstanceConfig(req.params.instanceId, req.user.id);

    // Create instance context
    const context: InstanceContext = {
      n8nApiUrl: instance.n8nApiUrl,
      n8nApiKey: instance.n8nApiKey,
      instanceId: instance.instanceId,
      metadata: {
        userId: req.user.id,
        userAgent: req.headers['user-agent'],
        ip: req.ip
      }
    };

    // Validate context before processing
    const validation = validateInstanceContext(context);
    if (!validation.valid) {
      return res.status(400).json({
        error: 'Invalid instance configuration',
        details: validation.errors
      });
    }

    // Process request with instance context
    await mcpEngine.processRequest(req, res, context);

  } catch (error) {
    console.error('MCP request error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

// Health endpoint
app.get('/health', async (req, res) => {
  const health = await mcpEngine.healthCheck();
  res.status(health.status === 'healthy' ? 200 : 503).json(health);
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  await mcpEngine.shutdown();
  process.exit(0);
});

app.listen(3000);
```

--------------------------------

### Configure n8n Instance Credentials

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/local/integration-tests-phase1-summary.md

Set up your n8n instance URL and API key in the `.env` file. These are required for the integration tests to connect to your n8n instance.

```bash
N8N_API_URL=http://localhost:5678
N8N_API_KEY=<your-api-key>
```

--------------------------------

### Install Claude Skills Plugin (Method 1)

Source: https://github.com/evolv3ai/n8n-mcp/blob/main/docs/CLAUDE_CODE_SETUP.md

Install n8n-skills as a Claude Code plugin using the `/plugin install` command. This is the recommended method for easily adding specialized skills for n8n workflow building.

```bash
/plugin install czlonkowski/n8n-skills
```