n8n + Claude Code MCP: Workflow Documentation

The fastest way to document an existing n8n workflow library is to export each workflow as JSON and feed it to Claude Code with a documentation prompt. Claude reads the node graph, understands the data flow, and generates structured documentation including purpose, trigger conditions, node-by-node breakdown, error handling, and environment variables. For ongoing access, you can also connect n8n via MCP server for direct workflow inspection.

Step 1: Export Your Workflows

In n8n, go to each workflow, click the three-dot menu, and select Export. You get a JSON file with every node, connection, and credential reference. For bulk export, use the n8n CLI.

# Export all workflows from n8n CLI
n8n export:workflow --all --output=./workflows/

# Or export a single workflow by ID
n8n export:workflow --id=1234 --output=./workflows/lead-enrichment.json

# List available workflows first
n8n list:workflow

Step 2: The Documentation Prompt Template

This prompt template works well with Claude Code. Save it as a file and reference it when processing each workflow.

Document this n8n workflow JSON. Produce:

## Overview
One paragraph: what the workflow does, when it triggers, what it outputs.

## Trigger
What starts this workflow (webhook, cron, manual, event).

## Node-by-Node Breakdown
For each node in execution order:
- Node name and type
- What it does in plain English
- Key configuration (URLs, filters, expressions)
- Error handling (if configured)

## Data Flow
Describe what data enters, how it transforms at each stage, what exits.

## Environment Variables / Credentials
List every credential reference and environment variable used.

## Failure Modes
What happens if each external service is down or returns errors.

## Estimated Execution Cost
If the workflow calls paid APIs, estimate per-run cost.

Step 3: Run Claude Code on Each Workflow

# Process a single workflow
claude -p "$(cat doc-prompt.md)" < workflows/lead-enrichment.json > docs/lead-enrichment.md

# Batch process all workflows
for f in workflows/*.json; do
  name=$(basename "$f" .json)
  claude -p "$(cat doc-prompt.md)" < "$f" > "docs/$name.md"
  echo "Documented: $name"
done

Using n8n MCP Server for Direct Access

Instead of exporting JSON files, you can connect Claude Code directly to n8n via the n8n MCP server. This gives Claude live access to read workflows, executions, and credentials metadata.

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@anthropic/n8n-mcp-server"],
      "env": {
        "N8N_HOST": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-n8n-api-key"
      }
    }
  }
}

With the MCP server connected, you can ask Claude Code to list all workflows, inspect a specific one, check recent execution logs, and generate documentation without manual export. The MCP approach is better for ongoing documentation maintenance because Claude always sees the latest workflow version.

Adding Search Context for Better Documentation

Some workflows use third-party services that Claude may not fully understand from the JSON alone. Adding web search as an MCP tool lets Claude look up API documentation for unfamiliar nodes.

{
  "mcpServers": {
    "n8n": {
      "command": "npx",
      "args": ["-y", "@anthropic/n8n-mcp-server"],
      "env": {
        "N8N_HOST": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-n8n-api-key"
      }
    },
    "scavio": {
      "url": "https://mcp.scavio.dev/mcp",
      "headers": {
        "x-api-key": "your-scavio-api-key"
      }
    }
  }
}

What Good Workflow Documentation Looks Like

The output from Claude typically covers what would take a developer 30-60 minutes per workflow to write manually. For a 20-workflow library, that is 10-20 hours of documentation work reduced to about 30 minutes of batch processing. The quality depends on workflow complexity: simple webhook-to-database flows get nearly perfect documentation. Complex flows with multiple branches, error paths, and conditional logic may need manual review and corrections.

• Simple linear workflows (5-10 nodes): documentation is usually accurate as-is
• Branching workflows with IF/Switch nodes: Claude correctly maps branches but may miss edge cases in complex expressions
• Workflows with custom code nodes: Claude documents what the code does but cannot verify it runs correctly
• Workflows referencing other workflows (sub-workflow calls): Claude notes the reference but cannot follow it without access to the sub-workflow

Keeping Documentation Current

Documentation drifts the moment someone edits a workflow. Set up a weekly cron (n8n itself can do this) that exports all workflows, runs the documentation pipeline, and commits the updated docs to your repo. A diff in the PR shows exactly what changed in the workflow and its documentation simultaneously.