n8n MCP Server

The server exposes two primary ways for an AI assistant to interact with n8n:

MCP Tools

Tools are executable operations located in src/tools/. They follow a pattern of a definition (name, description, input schema) and a handler function.

• Workflow tools: Operations like create, list, update, delete, activate, and deactivate workflows.
• Execution tools: Operations like run, list, and manage workflow executions.

MCP Resources

Resources provide data access through URI-based templates located in src/resources/.

• Static Resources (src/resources/static/): Fixed resources, such as general workflow listings.
• Dynamic Resources (src/resources/dynamic/): Parameterized resources, such as specific workflow details retrieved via a unique ID.

When extending the n8n MCP Server, adhere to these principles:

• Follow Existing Patterns: Match the established architectural patterns in the codebase.
• Type Safety: Use TypeScript interfaces for all new data structures.
• Error Handling: Implement comprehensive error handling (e.g., using this.handleApiError in clients or returning isError: true in tools).
• Testing: Write thorough unit tests for all new functionality.
• Documentation: Use JSDoc comments for all new public methods.
• Backward Compatibility: Ensure new extensions do not break existing functionality.

Every tool provided by the server includes a JSON Schema that defines its required and optional parameters. These schemas are passed to the AI assistant to enable automatic parameter validation and suggestions. For example, a tool designed to retrieve a workflow will require an id property of type string.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of the workflow to retrieve"
    }
  },
  "required": ["id"]
}

To maintain clean tests, use the tests/mocks/ directory for shared resources:

• Axios Mocking: Use axios-mock-adapter to simulate HTTP responses. A helper resetAxiosMock() should be used to clear the adapter between tests.
• API Fixtures: Store common n8n API response objects (like mockWorkflows or mockExecutions) in a shared file to avoid duplication.
• Global Setup: Use tests/test-setup.ts to perform global actions like jest.clearAllMocks() and resetting the Axios mock before each test.

// tests/test-setup.ts
import { jest } from '@jest/globals';
import { resetAxiosMock } from './mocks/axios-mock';

beforeEach(() => {
  jest.clearAllMocks();
  resetAxiosMock();
});

The n8n MCP Server uses a layered architecture to separate communication, logic, and data access. This design ensures that the server can handle requests from AI assistants via the Model Context Protocol (MCP) while interacting with the n8n API through a dedicated client layer.

Architectural Layers

1. Transport Layer: Manages communication with AI assistants (typically via stdio).
2. API Client Layer: Encapsulates all communication with the n8n API using N8nClient.
3. Tools Layer: Implements executable operations (e.g., creating or running workflows) as MCP tools.
4. Resources Layer: Provides read-only data access via URI-based templates (Static or Dynamic).
5. Configuration Layer: Manages and validates environment variables via the Environment class.
6. Error Handling Layer: Translates n8n API errors into standardized MCP error codes.

The n8n MCP Server implements the Model Context Protocol (MCP) to bridge AI assistants with n8n. The API is organized into two primary functional categories:

1. Tools: Executable functions that allow an AI assistant to perform actions, such as creating workflows or triggering executions.
2. Resources: Data sources that allow an AI assistant to read information about workflows and executions via URI-based access.

The architecture separates the Client Layer (n8n API communication), Transport Layer (MCP protocol implementation), Tools Layer (executable operations), and Resources Layer (data access). All interactions require an n8n API key configured in your environment.

The codebase is organized into several functional modules:

• src/api/: Contains the API client used to communicate with n8n.
• src/config/: Handles configuration and environment settings.
• src/errors/: Centralized error handling logic.
• src/resources/: Implementation of MCP resources, split into static/ and dynamic/ (parameterized) subdirectories.
• src/tools/: Implementation of MCP tools, categorized into workflow/ (workflow management) and execution/ (execution management).
• src/types/: TypeScript type definitions.
• src/utils/: Shared utility functions.
• tests/: Test suites including unit/, integration/, and e2e/.
• build/: The directory containing compiled JavaScript output.

The n8n MCP Server employs a three-tier testing strategy to ensure reliability:

1. Unit Tests (tests/unit/): These test individual components in isolation. The directory structure mirrors the src/ directory (e.g., src/api/client.ts is tested in tests/unit/api/client.test.ts).
2. Integration Tests (tests/integration/): These verify interactions between components, such as ensuring tools correctly utilize the API client or that resources format API data correctly.
3. End-to-End Tests (tests/e2e/): These test the entire system as a whole, from the transport layer through to the API client and back.

Shared fixtures and mocks are located in tests/mocks/.

Tests are automatically executed in CI environments during pull requests and commits to the main branch. To successfully merge code, the following requirements must be met:

• All tests must pass: No failing test suites are permitted.
• Test coverage must not decrease: New code must maintain or improve existing coverage levels.
• Linting checks must pass: Code must adhere to the project's linting rules.

To compile the TypeScript source code into JavaScript for production or distribution, run the build command. This generates the compiled output in the build/ directory and prepares the executable script files.

npm run build