n8n Documentation Guide: Build AI-Powered Workflows and Connect Claude, Codex, and More

What Is n8n?

n8n (pronounced "n-eight-n") is a fair-code licensed workflow automation tool that combines AI capabilities with business process automation. Unlike fully proprietary platforms, n8n's fair-code model gives you the transparency of open source with the sustainability of a commercial product — you can self-host it, inspect the source, and extend it, while the vendor continues to invest in development.

If you're an AI freelancer, automation consultant, or operations engineer, n8n sits in a sweet spot: it's technical enough to handle complex data transformations and HTTP integrations, yet visual enough to prototype an AI agent in an afternoon. This guide walks through the official documentation structure so you can move from installation to production-grade automation efficiently.

Key takeaway: n8n's documentation is organized as a progressive learning path — setup, first workflow, examples, core concepts, then advanced integrations like the Model Context Protocol (MCP) server for Claude and Codex.

Getting Started: Installation and Setup Options

The n8n docs offer three primary paths to get running. Choose based on your infrastructure and comfort level.

Option 1: n8n Cloud (Fastest Path)

The quickest way to try n8n is the hosted cloud offering. You can start free, then choose a paid plan as your usage grows. This is ideal for freelancers who want to validate an automation idea before committing to infrastructure.

Best for: Rapid prototyping, client demos, and teams without dedicated DevOps resources.

Option 2: Self-Hosting with Docker Compose

For full control over data residency and costs, the documentation provides a one-line setup and a Docker Compose installation guide. Docker Compose is the recommended self-hosted approach because it bundles n8n with a database (typically PostgreSQL) in a reproducible configuration.

Practical tip: Always pin your n8n image to a specific version tag in production (e.g., n8nio/n8n:1.x.x) rather than latest. This prevents surprise breaking changes during automatic pulls and makes rollbacks trivial.

Option 3: Cloud Provider Deployment

n8n can also be deployed via major cloud providers. This suits organizations that need n8n inside an existing VPC, with managed databases and IAM-based access control.

Build Your First Workflow

The documentation's "Build your first workflow" tutorial is the canonical starting point. A workflow in n8n is a canvas of connected nodes — each node performs one action: trigger, transform, request, or branch.

A Simple Example: Daily AI News Digest

Imagine you want a workflow that every morning:

1. Triggers on a schedule (e.g., 7:00 AM).
2. Fetches RSS feeds from three industry blogs via an HTTP Request node.
3. Summarizes the combined articles using an AI node (e.g., an LLM chain).
4. Posts the digest to a Slack channel.

This single workflow demonstrates the core value proposition: connecting disparate services — RSS, an LLM, and Slack — without writing a backend.

Why Start Here?

The first-workflow tutorial teaches node configuration, data flow between nodes, and how to inspect execution results. These three skills underpin everything else in n8n.

Inspiration: What to Automate

The docs include a curated set of example workflows to spark ideas. Notable examples include:

Creating an API Endpoint

n8n can expose a webhook that behaves like a lightweight API endpoint. This is powerful for AI freelancers building custom integrations for clients — you can receive a POST request, enrich the payload with data from a CRM, run it through an AI model, and return a structured JSON response.

Use case: A lead-scoring endpoint that accepts a form submission, enriches it with company data, and returns a score plus a recommended next action.

AI Agent Chat

One of the most in-demand examples is an AI agent chat workflow. Here, an LLM node is given access to tools (other n8n nodes) and can decide which to call based on the user's message. This is the foundation of retrieval-augmented generation (RAG) assistants and internal copilots.

Scrape and Summarize Web Pages with AI

This example combines an HTTP Request node (to fetch a page), a parsing step, and an AI summarization node. It's a practical pattern for competitive research, content curation, and market monitoring.

Joining Different Datasets

The "joining datasets" example demonstrates how to merge data from two sources — for instance, matching CRM contacts with support tickets — using n8n's merge and code nodes.

Actionable tip: When joining datasets, always normalize your join keys (trim whitespace, lowercase emails) before the merge. Silent mismatches are the most common cause of "missing" rows in automation workflows.

Understand Key Concepts

Before scaling to complex automations, the documentation recommends mastering four foundational concepts.

Expressions for Data Transformation

Expressions let you reference and manipulate data from previous nodes using JavaScript-like syntax. For example, {{ $json.email }} pulls the email field from the current item. Expressions unlock dynamic configuration — you're not hardcoding values, you're computing them.

Flow Logic

Flow logic covers branching (IF nodes, Switch nodes), looping (Split In Batches), and error handling. This is where simple automations become robust systems.

Best practice: Design for failure. Every external API call can time out. Use n8n's error workflow feature to catch failures and notify you via Slack or email, rather than discovering a broken pipeline days later.

Understand Executions

Every workflow run is an execution, and n8n logs each one with full input/output data per node. The Executions view is your debugging cockpit — you can replay failed runs, inspect the exact payload that caused an error, and pin data for testing.

Data Structure and Items

n8n passes data as an array of items, each item being a JSON object. Understanding this model is essential: a node processes each item individually unless it's an aggregating node. Misunderstanding item flow is the #1 source of confusion for newcomers.

Connecting AI Assistants via the n8n MCP Server

The most significant recent addition to n8n's documentation is the Model Context Protocol (MCP) server, which allows AI coding assistants and desktop clients to interact with your n8n instance directly. This turns your automation platform into a tool that AI agents can call.

Anthropic Claude Desktop

The docs provide a dedicated guide for connecting Claude Desktop to the n8n MCP server. Once configured, Claude Desktop can query your workflows, trigger executions, and assist with automation design — all through natural language.

Why this matters: Instead of switching between your browser and Claude, you can ask Claude to "list my active workflows" or "trigger the lead-scoring workflow for this contact." The MCP server bridges the gap between conversational AI and operational automation.

Anthropic Claude Code

For developers working in the terminal, connecting Claude Code to the n8n MCP server uses a single command:

claude mcp add --transport http n8n-mcp https://<your-instance>/mcp-server/http

This registers n8n as an MCP server over HTTP transport. Replace <your-instance> with your n8n host. After running this, Claude Code can invoke n8n tools as part of its coding workflow.

Practical example: While building a client's integration, you could ask Claude Code to "create an n8n workflow that polls this API every hour and posts new records to Airtable" — and have it scaffold the workflow via the MCP connection.

OpenAI Codex CLI

Similarly, connecting Codex CLI to the n8n MCP server uses:

codex mcp add n8n-mcp --url https://<your-instance>/mcp-server/http

This makes n8n available as a tool within Codex CLI sessions, enabling the same natural-language automation control from OpenAI's terminal agent.

Comparison of MCP Connection Methods

Security note: The MCP server exposes control over your n8n instance. Always secure it behind authentication and HTTPS. Never expose an unauthenticated MCP endpoint to the public internet — treat it with the same care as an admin API key.

Documentation Format and Accessibility

The n8n documentation is available in multiple formats to suit different workflows:

• Complete documentation index: Available via llms.txt, a convention that helps large language models discover and consume documentation efficiently.
• Markdown version: Every page is available as Markdown, making it easy to copy into your own notes, wikis, or AI assistants.

The llms.txt file is worth highlighting. As AI-assisted development becomes standard, publishing a machine-readable index lets tools like Claude and Codex retrieve accurate, up-to-date documentation rather than hallucinating API details. If you maintain documentation for your own product, adopting llms.txt is a forward-looking best practice.

Practical Workflow Automation Examples

To make these concepts concrete, here are three end-to-end scenarios that combine the features above.

Example 1: AI-Powered Inbox Triage

• Trigger: New email via IMAP node.
• Logic: AI node classifies the email (urgent / FYI / spam).
• Action: IF node routes urgent emails to Slack; others are logged to a Google Sheet.
• Enhancement: Use an MCP-connected Claude session to review misclassifications weekly and refine your prompts.

Example 2: Client Reporting Automation for Freelancers

• Trigger: Schedule node (weekly).
• Logic: Pull analytics from three platforms via HTTP Request nodes; merge datasets.
• Transform: Use expressions to calculate week-over-week deltas.
• Action: Generate a PDF and email it to the client.

Example 3: Content Research Pipeline

• Trigger: Webhook from a bookmarking tool.
• Logic: Scrape the saved URL, summarize with AI, extract keywords.
• Action: Append to a Notion database with tags.
• Enhancement: Connect Codex CLI to your n8n MCP server and ask it to build variations of this workflow for different content types.

Best Practices for n8n Automation

1. Version control your workflows. Export workflows as JSON and store them in Git. n8n's UI is great for building, but Git is better for tracking changes and collaborating.
2. Use credentials, never hardcode secrets. n8n's credential store encrypts sensitive values. Expressions referencing credentials keep your workflows portable and safe.
3. Name nodes descriptively. "HTTP Request" becomes "Fetch Stripe Charges" — future you will be grateful.
4. Test with pinned data. Pin sample data on a node to iterate on downstream logic without re-running expensive API calls.
5. Monitor executions. Set up an error workflow that alerts you on failures. Silent failures erode trust in automation faster than anything else.
6. Document your MCP connections. If you connect Claude Desktop, Claude Code, or Codex CLI, note which instance and credentials each uses — this prevents confusion in multi-environment setups.

Frequently Asked Questions

Is n8n free?

n8n is fair-code licensed. You can self-host it under the fair-code terms, and the cloud version offers a free tier before paid plans. Review the license for commercial use specifics.

Can I use n8n with Claude or ChatGPT?

Yes. The n8n MCP server enables connections to Anthropic Claude Desktop, Claude Code, and OpenAI Codex CLI via HTTP transport. This lets those AI tools interact with your n8n instance.

What's the difference between n8n and Zapier or Make?

n8n is source-available and self-hostable, with a strong emphasis on code-level control (expressions, custom code nodes) and AI agent workflows. This appeals to technical users and AI freelancers who need flexibility beyond no-code platforms.

How do I learn n8n quickly?

Follow the official path: install (Cloud or Docker Compose), build your first workflow, explore the example library, then study expressions, flow logic, and executions. The MCP integrations are a natural next step once you're comfortable with core concepts.

Conclusion

The n8n documentation is more than a reference manual — it's a structured curriculum for modern automation. From one-line Docker Compose setup to connecting Claude Desktop, Claude Code, and Codex CLI through the MCP server, the platform bridges visual workflow building with AI-native tooling.

For AI freelancers and automation professionals, the combination of fair-code licensing, self-hosting flexibility, and MCP connectivity makes n8n a compelling foundation for client work. Start with a single workflow, master expressions and executions, then layer in AI agents and MCP connections as your confidence grows.

The documentation is updated regularly (the MCP integration pages were recently refreshed), so bookmark the official site and check the llms.txt index for the latest additions.