Caipher MCP is an intelligent bridge between n8n workflow automation and AI models. It provides AI assistants with rich, structured access to n8n node documentation, properties, and operations, enabling you to explore, validate, and assemble complex workflows with confidence. Deploy quickly in hosted or self-hosted environments and connect from Claude, Claude Code, VS Code, or your preferred AI-enabled IDEs.

How to use

You use Caipher MCP by connecting an MCP client to a running MCP server. Once connected, your AI assistant can search for n8n nodes, fetch detailed node information, request documentation, validate configurations, and manage workflows in your n8n instance. Start from a catalog of 1,084 nodes (core and community), browse templates, and let the AI guide you through building robust automations.

Practical usage patterns include:

• Discovering relevant nodes by task or metadata and inspecting their essential properties.
• Validating node configurations before deployment to catch misconfigurations early.
• Exploring templates to quickly assemble end-to-end workflows and then adapting them to your needs.
• Managing workflows in your n8n instance when API credentials are provided, or simply using documentation and validation tools for safe development.

How to install

Follow these concrete steps to run Caipher MCP locally or in Docker. Pick the self-hosted option that fits your environment.

Prerequisites:

• Node.js installed on your system (for local setup)
• Docker installed (for containerized setup) if you choose the Docker route
• Optional: an active n8n instance if you want to manage real workflows via API keys

Option A: npx (Quick Local Setup) – run in minutes

# Run directly with npx (no installation needed!)
npx n8n-mcp

Add to Claude Desktop config:

Required for Claude Desktop: MCP_MODE must be stdio to ensure JSON-RPC messages are sent correctly.

Basic configuration (documentation tools only):

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

Full configuration (with n8n management tools):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "npx",
      "args": ["n8n-mcp"],
      "env": {
        "MCP_MODE": "stdio",
        "LOG_LEVEL": "error",
        "DISABLE_CONSOLE_OUTPUT": "true",
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

Note: npx will download and run the latest version automatically. The package includes a pre-built database with all n8n node information.

Configuration file locations:

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

Restart Claude Desktop after updating configuration

Option B: Docker (Isolated & Reproducible)

Prerequisites: Docker installed on your system

Pull the Docker image (approximately 280MB, no n8n dependencies)

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

Add to Claude Desktop config:

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ],
      "env": {}
    }
  }
}

Full configuration (with n8n management tools):

{
  "mcpServers": {
    "n8n-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e", "MCP_MODE=stdio",
        "-e", "LOG_LEVEL=error",
        "-e", "DISABLE_CONSOLE_OUTPUT=true",
        "-e", "N8N_API_URL=https://your-n8n-instance.com",
        "-e", "N8N_API_KEY=your-api-key",
        "ghcr.io/czlonkowski/n8n-mcp:latest"
      ],
      "env": {
        "N8N_API_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

Tip: If you run a local n8n instance on the same machine, use http://host.docker.internal:5678 as the N8N_API_URL.

Note: The n8n API credentials are optional. Without them, you access all documentation and validation tools. With them, you gain workflow management capabilities (create, update, execute workflows).

Option C: Local n8n Instance Configuration

{ "mcpServers": { "n8n-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "--init", "-e", "MCP_MODE=stdio", "-e", "LOG_LEVEL=error", "-e", "DISABLE_CONSOLE_OUTPUT=true", "-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" ] } } }

> Important: Set WEBHOOK_SECURITY_MODE=moderate to allow webhooks to your local n8n instance.

**Note**: The -i flag is required for stdio communication.

Option D: Railway Cloud Deployment is available for one-click hosting with zero configuration. The deployment guide provides the exact steps after you sign in and deploy, and you will obtain a deployment URL to connect from Claude Desktop. The deployment URL is used to configure your MCP client in Claude.

Additional configuration notes and safety

Security and safety: never edit production workflows directly with AI. Always make a copy, test in development, and export backups. Validate changes before deploying. Opt out of telemetry if desired by setting the appropriate environment variable in your deployment configuration.

Privacy and telemetry: anonymous usage statistics are collected to improve the tool. You can disable telemetry via the provided commands or environment variables in your deployment. Ensure you provide API keys only to trusted environments.

Configuration and environment overview

The MCP server supports standard environment configurations shown in the example blocks. When you use stdio, provide MCP_MODE=stdio to ensure proper JSON-RPC messaging. When using Docker, pass related environment variables as shown in the blocks above.

If you want to connect to a remote n8n instance, provide N8N_API_URL and N8N_API_KEY in the MCP server environment. You can also enable or tune logs with LOG_LEVEL and disable console output with DISABLE_CONSOLE_OUTPUT.

n8n integration and templates

Caipher MCP includes access to a large catalog of templates and node documentation. You can explore templates by different discovery modes, fetch full workflow representations, and validate configurations before running them in your n8n instance.

Troubleshooting tips

If you encounter issues with Docker, verify that the container has network access to your n8n instance and that the environment variables are set correctly. If you see JSON parsing errors in Claude Desktop, ensure MCP_MODE is set to stdio and that the CLI client is configured to send JSON-RPC messages to stdout.

Notes on usage in Claude projects

When you integrate with Claude Projects, you can enable enhanced system instructions to guide the AI through a safe, efficient workflow-building process. Follow the project setup guidance to maximize template usage, parallel execution, and validation steps.

Available tools

tools_documentation

Get documentation for MCP tools and endpoints to guide your workflow building.

search_nodes

Full-text search across n8n nodes with optional examples and source filtering.

get_node

Unified node information tool with multiple modes to fetch properties, docs, or versions.

validate_node

Validate node configurations quickly or comprehensively before deployment.

validate_workflow

Validate entire workflows for correctness and AI readiness.

search_templates

Search workflow templates with smart filtering by metadata, task, or nodes.

get_template

Retrieve complete workflow templates for construction.

n8n_create_workflow

Create new workflows in your n8n instance.

n8n_get_workflow

Retrieve workflows from n8n with flexible detail levels.

n8n_update_full_workflow

Replace an entire workflow in n8n.

n8n_update_partial_workflow

Update a workflow using diff-based operations.

n8n_delete_workflow

Permanently delete a workflow from n8n.

n8n_list_workflows

List workflows with filtering and pagination.

n8n_validate_workflow

Validate a workflow in n8n by its ID.

n8n_autofix_workflow

Automatically fix common workflow issues.

n8n_workflow_versions

Manage version history and rollback for workflows.

n8n_deploy_template

Deploy templates from n8n.io to your instance with auto-fix.

n8n_test_workflow

Test and trigger workflows with automatic trigger type detection.

n8n_executions

Unified execution management for workflows.

n8n_health_check

Check connectivity and feature availability of n8n API.