N8N Process Automation Controller (PAC) Server

This component serves as a dedicated Model Context Protocol (MCP) endpoint, allowing conversational AI agents to programmatically interface with and command an n8n automation platform using vernacular instructions.

Conceptual Framework

This module establishes a communication bridge, empowering Large Language Models (LLMs) to exert control over n8n's operational capabilities, covering the full lifecycle of data pipelines and automated tasks via natural dialogue.

Deployment Instructions

Prerequisites

• Node.js environment, version 20 or newer.
• A functioning n8n installation configured with accessible API credentials.

Via npm Registry

Execute the following command for global installation:

bash npm install -g @leonardsellem/n8n-mcp-server

From Source Code

1. Clone Repository: bash git clone https://github.com/leonardsellem/n8n-mcp-server.git cd n8n-mcp-server

2. Dependency Installation: bash npm install

3. Compilation: bash npm run build

4. Optional Global Linkage: bash npm install -g .

Containerized Operation (Docker)

Utilize the pre-built image from Docker Hub:

bash

Fetch the latest image

docker pull leonardsellem/n8n-mcp-server

Initiate the container, injecting necessary n8n access parameters

docker run -e N8N_API_URL=http://your-n8n:5678/api/v1 \ -e N8N_API_KEY=your_n8n_api_key \ -e N8N_WEBHOOK_USERNAME=username \ -e N8N_WEBHOOK_PASSWORD=password \ leonardsellem/n8n-mcp-server

Maintenance and Upgrades

The procedure for refreshing the server depends on the initial deployment method.

1. Global npm Installation

Update to the newest release via the terminal:

bash npm install -g @leonardsellem/n8n-mcp-server@latest

Remember to relaunch any background processes for the update to become active.

2. Source Code Deployment

Navigate to the root of the cloned directory and perform these steps:

1. (Optional) Preserve local code modifications: bash git stash

2. Synchronize with the upstream repository (main branch assumed): bash git pull origin main

3. Update dependencies: bash npm install

4. Recompile the application bundle: bash npm run build

5. If globally linked (npm install -g .), re-link: bash npm install -g .

6. Restart the server service.

3. Docker Image Refresh

1. Acquire the latest image tag: bash docker pull leonardsellem/n8n-mcp-server:latest

2. Terminate and eliminate the prior running container instance (use docker ps to identify): bash docker stop docker rm

3. Deploy a new container using your previous docker run parameters, ensuring the :latest tag is referenced.

Configuration Parameters

Configuration is managed via environment variables, typically specified in a .env file created by copying .env.example.

Parameter	Purpose	Sample Value
N8N_API_URL	The fully qualified endpoint for the n8n API, including the version suffix.	http://host:port/api/v1
N8N_API_KEY	Confidential token for API authorization.	n8n_sec_key_xyz
N8N_WEBHOOK_USERNAME	Required credential for Basic Auth on webhook triggers.	user
N8N_WEBHOOK_PASSWORD	Required credential for Basic Auth on webhook triggers.	pass
DEBUG	Toggles verbose logging output.	true / false

API Key Acquisition

1. Access the n8n web interface.
2. Navigate to Settings -> API Key Management.
3. Generate a new access token with the necessary permissions.
4. Populate this token into the N8N_API_KEY variable in your configuration file.

Operational Guide

Server Initiation

Start the server process from its root location:

bash n8n-mcp-server

AI Assistant Integration Schema

Once compiled (npm run build), the server must be referenced within your AI assistant's configuration (e.g., VS Code/Claude settings JSON).

Configuration Snippet Example:

{ "mcpServers": { "n8n-automation-hub": { "command": "node", "args": [ "/absolute/path/to/n8n-mcp-server/build/index.js" ], "env": { "N8N_API_URL": "http://your-n8n:5678/api/v1", "N8N_API_KEY": "YOUR_SECURE_KEY" }, "disabled": false, "autoApprove": [] } } }

Critical Considerations:

• Replace the placeholder path with the actual directory where the built JavaScript file resides.
• Use platform-appropriate path delimiters (/ for Unix-like systems, \\ for Windows paths).
• Verify the correctness of the API URL endpoint and the secret key.
• The assistant can only interact after the server has been successfully built.

Exposed Toolkit Functions

The server makes the following capabilities available to the AI agent:

Webhook Execution Mechanism

This mechanism permits the invocation of n8n workflows designed to be initiated via HTTP requests (webhooks).

1. Design an n8n workflow triggered by a webhook event.
2. Configure Basic Authentication credentials on that webhook trigger node.
3. Employ the run_webhook utility, providing the target workflow name.

Example API Call: javascript const executionResult = await useRunWebhook({ workflowName: "data_sync_trigger", data: { message: "System initiated task" } });

The necessary webhook credentials (N8N_WEBHOOK_USERNAME, N8N_WEBHOOK_PASSWORD) are automatically secured from the environment variables.

Workflow Lifecycle Operations

• workflow_list: Enumerates all available workflows.
• workflow_get: Retrieves configuration details for a selected workflow.
• workflow_create: Provisions a brand new workflow definition.
• workflow_update: Modifies an existing workflow's structure.
• workflow_delete: Permanently removes a specified workflow.
• workflow_activate: Enables a previously disabled workflow for execution.
• workflow_deactivate: Halts future triggering of a specific workflow.

Execution State Control

• execution_run: Manually initiates a workflow run via the direct n8n API.
• run_webhook: Triggers a workflow via its dedicated webhook endpoint.
• execution_get: Fetches the detailed status and logs of a specific job run.
• execution_list: Retrieves a history of runs associated with a particular workflow ID.
• execution_stop: Sends a command to terminate an execution currently in progress.

Accessible Data Endpoints (Resources)

The underlying data structure exposed via REST-like URIs:

• n8n://workflows/list: Collection of all defined workflow metadata.
• n8n://workflow/{id}: Detailed configuration schema for workflow ID {id}.
• n8n://executions/{workflowId}: Chronological record of runs for the specified workflow ID.
• n8n://execution/{id}: Comprehensive report for execution instance ID {id}.

Future Development Trajectory (Roadmap)

The evolution of the N8N PAC Server is inherently collaborative, driven by community input and demonstrated requirements. The immediate focus remains adaptive and responsive to user needs.

We actively solicit input to guide future enhancements:

• Feature Proposals: Suggest new operational tools or data retrieval endpoints.
• Priority Setting: Engage in discussions about which functionality should be prioritized.

Submit all feature suggestions and enhancement requests via the GitHub Issues portal. Let us collaboratively architect a superior tool for AI-driven process orchestration!

Developer Utilities

Compilation

bash npm run build

Debug Mode Execution

bash npm run dev

Automated Validation

bash npm test

Style Enforcement

bash npm run lint

Contribution Guidelines

We warmly invite external developers to submit improvements to the N8N PAC Server. All forms of contribution—from documentation fixes to complex feature additions—are highly valued.

Reporting Defects

If a fault is found, please document it on the GitHub Issues page and include:

• A succinct, descriptive title.
• Step-by-step reproduction instructions.
• Your operational environment context (Node version, server version, OS).
• Any relevant error logs or visual artifacts.

Suggesting Enhancements

For new functionalities, open an issue detailing:

• A clear title for the proposed improvement.
• A thorough justification of the enhancement and its perceived value.
• Illustrative examples or potential use cases.

Submitting Code Changes (Pull Requests)

To integrate your code changes, follow this standard workflow:

1. Fork: Create a personal copy of the repository.
2. Branch: Establish a dedicated branch for your work (e.g., git checkout -b feat/new-metric-retrieval).
3. Modify: Implement your changes, ensuring adherence to the existing coding conventions (run npm run lint to verify formatting).
4. Test: Write and pass relevant automated tests (npm test).
5. Commit: Use clear, descriptive commit messages.
6. Push: Upload your committed changes to your fork.
7. PR: Open a Pull Request against the upstream main branch, clearly articulating the scope of the changes and referencing associated issues.

We commit to reviewing submissions promptly.

Licensing

MIT

📣 Seeking Dedicated Co-Maintainers!

This specialized tool, essential for bridging advanced AI interactions with n8n orchestration, is currently maintained primarily by an enthusiastic, non-expert individual on an intermittent schedule. Given the project's utility and growing user base, we are actively seeking dedicated co-maintainers to ensure its sustained viability, responsiveness, and technical advancement.

Benefits of Joining

• Skill Development: Enhance expertise in TypeScript/Node.js development, API interaction patterns, and AI tooling infrastructure.
• Community Engagement: Collaborate with a network of developers and automation specialists.
• Direct Impact: Influence the feature set and technical direction of this valuable open-source asset.

Key Areas for Support

We welcome assistance across numerous domains:

• Defect Resolution: Stabilizing the platform by resolving reported issues.
• Feature Implementation: Developing and integrating new required functionalities.
• Documentation Refinement: Enhancing clarity in guides and API specifications.
• Test Suite Expansion: Strengthening unit and integration testing coverage.
• Pipeline Optimization: Streamlining CI/CD processes.
• Peer Review: Providing constructive code critiques on incoming PRs.
• User Assistance: Supporting the community via issue triage and discussion management.

How to Express Interest

If you are passionate about the nexus of artificial intelligence and automated business processes and seek a meaningful open-source role, please engage:

1. Explore existing tasks on the GitHub Issues tracker.
2. Submit an issue titled "Co-maintainer Application" or begin contributing to open items.
3. Feel free to reach out directly to the current maintainer for preliminary discussions.

Let's advance AI-driven workflow management collectively! 🙌

Gratitude to all community supporters!