FAQ

General Questions

What is n8n-MCP?

n8n-MCP is a Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. It serves as a bridge between n8n’s workflow automation platform and AI models like Claude.With n8n-MCP, AI assistants can:

Search and explore 1,084 n8n nodes (537 core + 547 community)
Validate workflow configurations before deployment
Access 2,709 workflow templates
Create, update, and manage n8n workflows (with API configuration)

What are the available deployment options?

n8n-MCP offers multiple deployment options:

Hosted Service (Easiest): dashboard.n8n-mcp.com - Free tier with 100 tool calls/day
npx (Quick Local): Run directly with npx n8n-mcp
Docker (Isolated): Pull and run with Docker
Railway Cloud (One-Click): Deploy to Railway platform
Local Installation (Development): Clone and build from source

Choose based on your needs: hosted for instant access, local for privacy, Docker for isolation.

Is n8n API required?

No, the n8n API is optional.Without n8n API:

✅ Search and explore all n8n nodes
✅ Access node documentation and properties
✅ Validate workflow configurations
✅ Browse 2,709 workflow templates
✅ Get real-world configuration examples

With n8n API:

✅ All the above, plus:
✅ Create workflows in your n8n instance
✅ Update and manage existing workflows
✅ Test workflow execution
✅ Monitor execution history
✅ Deploy templates directly to n8n

How much does it cost?

n8n-MCP is 100% free and open source (MIT License).

Self-hosted: Completely free, no limitations
Hosted service: Free tier with 100 tool calls/day (paid tiers available)
No hidden fees: All features available in the open source version

The project accepts GitHub Sponsors to support development.

Setup & Configuration

Why do I see 'Unexpected token...' errors in Claude Desktop?

This is caused by missing the MCP_MODE: "stdio" environment variable.Solution:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",  // Required!
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true"
      }
    }
  }
}

This ensures only JSON-RPC messages are sent to stdout, preventing debug logs from interfering with the protocol.

How do I connect to my local n8n instance?

For local n8n instances (e.g., http://localhost:5678), you need to:

Use the correct URL: http://host.docker.internal:5678 (for Docker)
Allow localhost webhooks:
```
"-e", "WEBHOOK_SECURITY_MODE=moderate"
```

Example configuration:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        "-e", "N8N_API_URL=http://host.docker.internal:5678",
        "-e", "N8N_API_KEY=your-api-key",
        "-e", "WEBHOOK_SECURITY_MODE=moderate",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ]
    }
  }
}

Only use WEBHOOK_SECURITY_MODE=moderate for local development. Never in production.

How do I disable telemetry?

Telemetry can be disabled in multiple ways:npx:

npx n8n-mcp telemetry disable

Docker:

"-e", "N8N_MCP_TELEMETRY_DISABLED=true"

docker-compose:

environment:
  N8N_MCP_TELEMETRY_DISABLED: "true"

See the Privacy Policy for more details.

Where is the Claude Desktop config file located?

macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.jsonLinux: ~/.config/Claude/claude_desktop_config.json

After updating the config, restart Claude Desktop for changes to take effect.

Usage & Features

How many n8n nodes are available?

n8n-MCP provides access to 1,084 nodes:

537 core nodes from n8n-nodes-base
547 community nodes from verified packages
265 AI-capable tool variants (LangChain)
99% property coverage
87% documentation coverage

Can I search community nodes?

Yes! Use the source filter in search_nodes:

// Search all community nodes
search_nodes({ query: "scraping", source: "community" })

// Search verified community nodes only
search_nodes({ query: "pdf", source: "verified" })

// Search core nodes only
search_nodes({ query: "webhook", source: "core" })

What are workflow templates?

n8n-MCP includes 2,709 workflow templates from n8n.io/workflows.Search by task:

search_templates({ searchMode: "by_task", task: "webhook_processing" })

Filter by complexity:

search_templates({
  searchMode: "by_metadata",
  complexity: "simple",
  maxSetupMinutes: 30
})

All templates include:

Full attribution to original creator
Direct link to n8n.io
Complete workflow JSON
Metadata (complexity, setup time, required services)

How do I validate workflows before deployment?

Use the multi-level validation approach:Level 1 - Quick Check:

validate_node({ nodeType, config, mode: "minimal" })

Level 2 - Comprehensive:

validate_node({ nodeType, config, mode: "full", profile: "runtime" })

Level 3 - Complete Workflow:

validate_workflow(workflow)

Level 4 - Post-Deployment:

n8n_validate_workflow({ id: "workflow-id" })
n8n_autofix_workflow({ id: "workflow-id" })

Troubleshooting

Docker image fails to start

Common issues:

Missing -i flag: Required for MCP stdio communication

docker run -i --rm ghcr.io/czlonkowski/n8n-mcp:latest

Port conflicts: Check if port is already in use (HTTP mode)
```
lsof -i :3000
```

Memory issues: Increase Docker memory limit

docker update --memory 512m container-id

See the Docker Troubleshooting Guide for more details.

Memory usage seems high

n8n-MCP uses SQLite for node documentation. Two adapters are available:better-sqlite3 (Default):

Native C++ bindings
Memory usage: ~100-120 MB
Direct disk writes

sql.js (Fallback):

Pure JavaScript
Memory usage: ~150-200 MB
In-memory database

To optimize sql.js memory:

SQLJS_SAVE_INTERVAL_MS=10000  # Increase save interval

How do I update to the latest version?

npx: Automatically uses the latest version

npx n8n-mcp  # Always latest

Docker: Pull the latest image

docker pull ghcr.io/czlonkowski/n8n-mcp:latest

Local installation: Update and rebuild

git pull origin main
npm install
npm run build
npm run rebuild

Can I use n8n-MCP with other AI assistants?

Yes! n8n-MCP implements the Model Context Protocol (MCP), which is supported by:

Claude Desktop (official)
Claude Code
VS Code with MCP extensions
Cursor IDE
Windsurf
Codex
Antigravity
Any MCP-compatible client

See the IDE setup guides in the documentation.

Safety & Best Practices

Is it safe to use AI to edit workflows?

NEVER edit production workflows directly with AI!

Always follow these safety practices:

Make a copy of your workflow before using AI tools
Test in development environment first
Export backups of important workflows
Validate changes before deploying to production
Review AI-generated code before execution

AI results can be unpredictable. Protect your work!

What are the security best practices?

Key security practices:

Never commit credentials: Use environment variables
Strong API tokens: Generate with openssl rand -base64 32
Rotate keys regularly: Especially after exposure
Use HTTPS in production: Always encrypt traffic
Enable telemetry opt-out: Respect user privacy

See the Security Policy for complete details.

What data is collected by telemetry?

Collected (anonymized):

Tool usage metrics
Error categories (no error messages)
System information (platform, version)
Workflow patterns (sanitized)

Never collected:

API keys or credentials
URLs or endpoints
Personal information
Actual workflow data

See the Privacy Policy for complete details.

Contributing & Support

How can I contribute?

Contributions are welcome! You can:

Report bugs: Open an issue on GitHub
Submit PRs: Fix bugs or add features
Improve docs: Fix typos, add examples
Add tests: Improve test coverage

See the Contributing Guide for details.

How do I get help?

Several support channels:

Documentation: Browse the full docs
GitHub Issues: Ask questions, report bugs
GitHub Discussions: Community support
Email: Contact maintainer directly

Before asking, check the FAQ and search existing issues.

Can I use n8n-MCP commercially?

Yes! n8n-MCP is MIT licensed:

✅ Use in commercial projects
✅ Modify and distribute
✅ Private use
✅ No attribution required (but appreciated!)

See the LICENSE for details.

How can I support the project?

Several ways to support:

⭐ Star the repository on GitHub
💖 Sponsor the project via GitHub Sponsors
📢 Share with others who might find it useful
🤝 Contribute code, docs, or tests
💬 Report issues to help improve quality

Become a sponsor →

GitHub Issues

Ask questions, report bugs

Documentation

Browse the full documentation

Claude Interview

Real-world impact of n8n-MCP

Changelog

Version history and updates

Resources

Examples

General Questions

Setup & Configuration

Usage & Features

Troubleshooting

Safety & Best Practices

Contributing & Support

More Questions?

GitHub Issues

Documentation

Claude Interview

Changelog

Build docs developers (and LLMs) love

Resources

Examples

​General Questions

​Setup & Configuration

​Usage & Features

​Troubleshooting

​Safety & Best Practices

​Contributing & Support

​More Questions?

GitHub Issues

Documentation

Claude Interview

Changelog

Build docs developers (and LLMs) love

General Questions

Setup & Configuration

Usage & Features

Troubleshooting

Safety & Best Practices

Contributing & Support

More Questions?