n8n Local Control

Turn natural-language requests into configured n8n workflows and safely operate a local n8n Docker stack from compatible AI agents.

This repository is dual packaged:

• plugin.json and mcp.json implement the portable Agent Plugins 1.0 format.
• .codex-plugin/plugin.json and .mcp.json retain native Codex packaging.
• skills/ contains portable Agent Skills.

Capabilities

• Search n8n nodes and templates, construct workflows, validate nodes and complete workflows, inspect executions, and manage credentials through pinned n8n-mcp@2.68.0.
• Discover and call the live n8n Public API with exact OpenAPI allowlisting.
• Use expiring two-phase confirmation tokens for API writes and stack mutations.
• Inspect health and logs; start, stop, restart, back up, restore, and upgrade the exact Docker Compose deployment discovered from container labels.
• Create consistent stopped-volume backups with SHA-256 metadata and restore/upgrade rollback.

Requirements

• Node.js 18 or newer.
• n8n available at http://localhost:5678 by default.
• For full Windows stack control: PowerShell and Docker Desktop with an n8n Compose deployment.
• An n8n API key is optional for documentation and static validation, but required for workflow/API management.

Agent Plugins installation

Clone the repository and load its directory with an Agent Plugins 1.0-compatible client. The portable MCP entries use ${PLUGIN_ROOT} and ${PLUGIN_DATA} exactly as defined by the specification.

git clone https://github.com/RobertIonutF/n8n-local-control.git

The package is Windows-first for DPAPI and Docker administration. On other platforms the portable skills and MCP workflow engine can still load, but API-key storage must be supplied by the client or process environment and Windows stack tools are unavailable.

One-time Windows setup

1. In n8n, open Settings -> n8n API and create an API key with only the scopes you want the agent to use.

2. Run:

   & '.\scripts\setup.ps1'
   

3. Paste the key into the hidden terminal prompt. The script validates it and stores only a Windows DPAPI-encrypted value.

The setup script discovers the compose project, service, compose file, and n8n data volume from Docker labels. Override discovery only when needed:

& '.\scripts\setup.ps1' -Container n8n -BaseUrl 'http://localhost:5678' -ComposeFile 'D:\path\to\docker-compose.yml'

When an Agent Plugins client supplies PLUGIN_DATA, run setup from a terminal with that environment value or pass -StateDirectory explicitly so the launcher and setup helper share the same state directory. Codex falls back to %LOCALAPPDATA%\Codex\n8n-local-control.

Never paste the n8n API key or third-party credential secrets into chat.

Safety model

Read-only inspection, workflow design, inactive creation, and static validation can run autonomously. Activation, publication, side-effectful execution, deletion, credential changes, users/security, community packages, service interruption, restore, and upgrade require explicit confirmation. The local MCP server also requires an expiring prepared-operation token before mutations.

Validation

python .\scripts\validate_agent_plugin.py
node .\tests\server.test.mjs
node .\tests\mcp-handshake.test.mjs
powershell -NoProfile -ExecutionPolicy Bypass -File .\tests\dpapi.test.ps1

Codex plugin authors can additionally run the plugin-creator validator from their local Codex installation.

Live Docker tests are intentionally separate because they briefly stop n8n or create disposable Docker resources.

Privacy

The plugin does not embed credentials. The upstream n8n-MCP telemetry is disabled by the launcher. Sensitive API response fields are redacted, and Docker/API targets are restricted before execution.

License

MIT. See LICENSE.