hzhang/n8n-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit of n8n MCP Server

Browse Source 
A Model Context Protocol (MCP) server that integrates with n8n, providing tools for workflow and execution management via the n8n API.
This commit is contained in:
leonardsellem
2025-03-12 17:12:35 +01:00
commit 2cd565cfa6
79 changed files with 19654 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

250
docs/api/dynamic-resources.md Normal file
View File

@@ -0,0 +1,250 @@
# Dynamic Resources
This page documents the dynamic resources available in the n8n MCP Server.
## Overview
Dynamic resources are parameterized URIs that allow access to specific n8n data based on identifiers such as workflow IDs or execution IDs. These resources follow the URI template format defined in RFC 6570, with parameters enclosed in curly braces.
## Available Resource Templates
### n8n://workflow/{id}
Provides detailed information about a specific workflow.
**URI Template:** `n8n://workflow/{id}`
**Parameters:**
- `id` (required): The ID of the workflow to retrieve
**Description:** Returns comprehensive information about a specific workflow, including its nodes, connections, and settings.
**Example Usage:**
```javascript
const resource = await accessMcpResource('n8n-mcp-server', 'n8n://workflow/1234abc');
```
**Response:**
```javascript
{
"workflow": {
"id": "1234abc",
"name": "Email Processing Workflow",
"active": true,
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-02T14:30:00.000Z",
"nodes": [
{
"id": "node1",
"name": "Start",
"type": "n8n-nodes-base.start",
"position": [100, 200],
"parameters": {}
},
{
"id": "node2",
"name": "Email Trigger",
"type": "n8n-nodes-base.emailTrigger",
"position": [300, 200],
"parameters": {
"inbox": "support",
"domain": "example.com"
}
}
],
"connections": {
"node1": {
"main": [
[
{
"node": "node2",
"type": "main",
"index": 0
}
]
]
}
},
"settings": {
"saveExecutionProgress": true,
"saveManualExecutions": true,
"timezone": "America/New_York"
}
}
}
```
### n8n://executions/{workflowId}
Provides a list of executions for a specific workflow.
**URI Template:** `n8n://executions/{workflowId}`
**Parameters:**
- `workflowId` (required): The ID of the workflow whose executions to retrieve
**Description:** Returns a list of execution records for the specified workflow, sorted by most recent first.
**Example Usage:**
```javascript
const resource = await accessMcpResource('n8n-mcp-server', 'n8n://executions/1234abc');
```
**Response:**
```javascript
{
"executions": [
{
"id": "exec789",
"workflowId": "1234abc",
"status": "success",
"startedAt": "2025-03-12T16:30:00.000Z",
"finishedAt": "2025-03-12T16:30:05.000Z",
"mode": "manual"
},
{
"id": "exec456",
"workflowId": "1234abc",
"status": "error",
"startedAt": "2025-03-11T14:20:00.000Z",
"finishedAt": "2025-03-11T14:20:10.000Z",
"mode": "manual"
}
],
"count": 2,
"pagination": {
"hasMore": false
}
}
```
### n8n://execution/{id}
Provides detailed information about a specific execution.
**URI Template:** `n8n://execution/{id}`
**Parameters:**
- `id` (required): The ID of the execution to retrieve
**Description:** Returns comprehensive information about a specific execution, including its status, inputs, outputs, and execution path.
**Example Usage:**
```javascript
const resource = await accessMcpResource('n8n-mcp-server', 'n8n://execution/exec789');
```
**Response:**
```javascript
{
"execution": {
"id": "exec789",
"workflowId": "1234abc",
"workflowName": "Email Processing Workflow",
"status": "success",
"startedAt": "2025-03-12T16:30:00.000Z",
"finishedAt": "2025-03-12T16:30:05.000Z",
"mode": "manual",
"data": {
"resultData": {
"runData": {
"node1": [
{
"startTime": "2025-03-12T16:30:00.000Z",
"endTime": "2025-03-12T16:30:01.000Z",
"executionStatus": "success",
"data": {
"json": {
"started": true
}
}
}
],
"node2": [
{
"startTime": "2025-03-12T16:30:01.000Z",
"endTime": "2025-03-12T16:30:05.000Z",
"executionStatus": "success",
"data": {
"json": {
"subject": "Test Email",
"body": "This is a test",
"from": "sender@example.com"
}
}
}
]
}
},
"executionData": {
"nodeExecutionOrder": ["node1", "node2"],
"waitingNodes": [],
"waitingExecutionData": []
}
}
}
}
```
### n8n://workflow/{id}/active
Provides information about whether a specific workflow is active.
**URI Template:** `n8n://workflow/{id}/active`
**Parameters:**
- `id` (required): The ID of the workflow to check
**Description:** Returns the active status of a specific workflow.
**Example Usage:**
```javascript
const resource = await accessMcpResource('n8n-mcp-server', 'n8n://workflow/1234abc/active');
```
**Response:**
```javascript
{
"workflowId": "1234abc",
"active": true
}
```
## Content Types
All dynamic resources return JSON content with the MIME type `application/json`.
## Error Handling
Dynamic resources can return the following errors:
| HTTP Status | Description |
|-------------|-------------|
| 400 | Bad Request - Invalid parameter in URI |
| 401 | Unauthorized - Invalid or missing API key |
| 403 | Forbidden - API key does not have permission to access this resource |
| 404 | Not Found - The requested resource does not exist |
| 500 | Internal Server Error - An unexpected error occurred on the n8n server |
## Parameter Format
When using dynamic resources, parameters must be properly formatted:
1. **Workflow IDs**: Must be valid n8n workflow IDs (typically alphanumeric)
2. **Execution IDs**: Must be valid n8n execution IDs (typically alphanumeric)
## Best Practices
- Validate resource URIs before accessing them
- Handle possible 404 errors when accessing resources by ID
- Cache resource data when appropriate to reduce API calls
- Use specific resources (like `n8n://workflow/{id}/active`) for single properties when you don't need the entire resource
- Check workflow status before performing operations that require an active workflow

315
docs/api/execution-tools.md Normal file
View File

@@ -0,0 +1,315 @@
# Execution Tools
This page documents the tools available for managing n8n workflow executions.
## Overview
Execution tools allow AI assistants to execute n8n workflows and manage execution records. These tools provide a natural language interface to n8n's execution capabilities, allowing workflows to be run, monitored, and their results accessed.
## Available Tools
### execution_run
Executes a workflow with optional input data.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"workflowId": {
"type": "string",
"description": "ID of the workflow to execute"
},
"data": {
"type": "object",
"description": "Input data to pass to the workflow"
},
"waitForCompletion": {
"type": "boolean",
"description": "Whether to wait for the workflow to complete before returning",
"default": false
}
},
"required": ["workflowId"]
}
```
**Example Usage:**
```javascript
// Execute without waiting
const execution = await useExecutionRun({
workflowId: "1234abc"
});
// Execute with input data
const executionWithData = await useExecutionRun({
workflowId: "1234abc",
data: {
firstName: "John",
lastName: "Doe",
email: "john.doe@example.com"
}
});
// Execute and wait for completion
const completedExecution = await useExecutionRun({
workflowId: "1234abc",
waitForCompletion: true
});
```
**Response (when waitForCompletion: false):**
```javascript
{
"executionId": "exec789",
"status": "running",
"startedAt": "2025-03-12T16:30:00.000Z"
}
```
**Response (when waitForCompletion: true):**
```javascript
{
"executionId": "exec789",
"status": "success", // Or "error" if execution failed
"startedAt": "2025-03-12T16:30:00.000Z",
"finishedAt": "2025-03-12T16:30:05.000Z",
"data": {
// Output data from the workflow execution
}
}
```
### execution_get
Retrieves details of a specific execution.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"description": "ID of the execution to retrieve"
}
},
"required": ["executionId"]
}
```
**Example Usage:**
```javascript
const execution = await useExecutionGet({
executionId: "exec789"
});
```
**Response:**
```javascript
{
"id": "exec789",
"workflowId": "1234abc",
"workflowName": "Test Workflow 1",
"status": "success", // Or "error", "running", "waiting", etc.
"startedAt": "2025-03-12T16:30:00.000Z",
"finishedAt": "2025-03-12T16:30:05.000Z",
"mode": "manual",
"data": {
"resultData": {
// Output data from the workflow execution
},
"executionData": {
// Detailed execution data including node inputs/outputs
},
"metadata": {
// Execution metadata
}
}
}
```
### execution_list
Lists executions for a specific workflow.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"workflowId": {
"type": "string",
"description": "ID of the workflow to get executions for"
},
"limit": {
"type": "number",
"description": "Maximum number of executions to return",
"default": 20
},
"status": {
"type": "string",
"description": "Filter by execution status",
"enum": ["success", "error", "running", "waiting"]
}
},
"required": ["workflowId"]
}
```
**Example Usage:**
```javascript
// List all executions for a workflow
const executions = await useExecutionList({
workflowId: "1234abc"
});
// List with limit
const limitedExecutions = await useExecutionList({
workflowId: "1234abc",
limit: 5
});
// List only successful executions
const successfulExecutions = await useExecutionList({
workflowId: "1234abc",
status: "success"
});
```
**Response:**
```javascript
[
{
"id": "exec789",
"workflowId": "1234abc",
"status": "success",
"startedAt": "2025-03-12T16:30:00.000Z",
"finishedAt": "2025-03-12T16:30:05.000Z",
"mode": "manual"
},
{
"id": "exec456",
"workflowId": "1234abc",
"status": "error",
"startedAt": "2025-03-11T14:20:00.000Z",
"finishedAt": "2025-03-11T14:20:10.000Z",
"mode": "manual"
}
]
```
### execution_delete
Deletes an execution record.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"description": "ID of the execution to delete"
}
},
"required": ["executionId"]
}
```
**Example Usage:**
```javascript
await useExecutionDelete({
executionId: "exec789"
});
```
**Response:**
```javascript
{
"success": true
}
```
### execution_stop
Stops a running execution.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"description": "ID of the execution to stop"
}
},
"required": ["executionId"]
}
```
**Example Usage:**
```javascript
await useExecutionStop({
executionId: "exec789"
});
```
**Response:**
```javascript
{
"success": true,
"status": "cancelled",
"stoppedAt": "2025-03-12T16:32:00.000Z"
}
```
## Execution Status Codes
Executions can have the following status codes:
| Status | Description |
|--------|-------------|
| `running` | The execution is currently in progress |
| `success` | The execution completed successfully |
| `error` | The execution failed with an error |
| `waiting` | The execution is waiting for a webhook or other event |
| `cancelled` | The execution was manually stopped |
## Error Handling
All execution tools can return the following errors:
| Error | Description |
|-------|-------------|
| Authentication Error | The provided API key is invalid or missing |
| Not Found Error | The requested workflow or execution does not exist |
| Validation Error | The input parameters are invalid or incomplete |
| Permission Error | The API key does not have permission to perform the operation |
| Server Error | An unexpected error occurred on the n8n server |
## Best Practices
- Check if a workflow is active before attempting to execute it
- Use `waitForCompletion: true` for short-running workflows, but be cautious with long-running workflows
- Always handle potential errors when executing workflows
- Filter executions by status to find problematic runs
- Use execution IDs from `execution_run` responses to track workflow progress

74
docs/api/index.md Normal file
View File

@@ -0,0 +1,74 @@
# API Reference
This section provides a comprehensive reference for the n8n MCP Server API, including all available tools and resources.
## Overview
The n8n MCP Server implements the Model Context Protocol (MCP) to provide AI assistants with access to n8n workflows and executions. The API is divided into two main categories:
1. **Tools**: Executable functions that can perform operations on n8n, such as creating workflows or starting executions.
2. **Resources**: Data sources that provide information about workflows and executions.
## API Architecture
The n8n MCP Server follows a clean separation of concerns:
- **Client Layer**: Handles communication with the n8n API
- **Transport Layer**: Implements the MCP protocol for communication with AI assistants
- **Tools Layer**: Exposes executable operations to AI assistants
- **Resources Layer**: Provides data access through URI-based resources
All API interactions are authenticated using the n8n API key configured in your environment.
## Available Tools
The server provides tools for managing workflows and executions:
- [Workflow Tools](./workflow-tools.md): Create, list, update, and delete workflows
- [Execution Tools](./execution-tools.md): Execute workflows and manage workflow executions
## Available Resources
The server provides resources for accessing workflow and execution data:
- [Static Resources](./static-resources.md): Fixed resources like workflow listings or execution statistics
- [Dynamic Resources](./dynamic-resources.md): Parameterized resources for specific workflows or executions
## Understanding Input Schemas
Each tool has an input schema that defines the expected parameters. These schemas follow the JSON Schema format and are automatically provided to AI assistants to enable proper parameter validation and suggestion.
Example input schema for the `workflow_get` tool:
```json
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the workflow to retrieve"
}
},
"required": ["id"]
}
```
## Error Handling
All API operations can return errors in a standardized format. Common error scenarios include:
- Authentication failures (invalid or missing API key)
- Resource not found (workflow or execution doesn't exist)
- Permission issues (API key doesn't have required permissions)
- Input validation errors (missing or invalid parameters)
Error responses include detailed messages to help troubleshoot issues.
## Next Steps
Explore the detailed documentation for each category:
- [Workflow Tools](./workflow-tools.md)
- [Execution Tools](./execution-tools.md)
- [Static Resources](./static-resources.md)
- [Dynamic Resources](./dynamic-resources.md)

154
docs/api/static-resources.md Normal file
View File

@@ -0,0 +1,154 @@
# Static Resources
This page documents the static resources available in the n8n MCP Server.
## Overview
Static resources provide access to fixed n8n data sources without requiring parameters in the URI. These resources are ideal for retrieving collections of data or summary information.
## Available Resources
### n8n://workflows/list
Provides a list of all workflows in the n8n instance.
**URI:** `n8n://workflows/list`
**Description:** Returns a comprehensive list of all workflows with their basic metadata.
**Example Usage:**
```javascript
const resource = await accessMcpResource('n8n-mcp-server', 'n8n://workflows/list');
```
**Response:**
```javascript
{
"workflows": [
{
"id": "1234abc",
"name": "Email Processing Workflow",
"active": true,
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-02T14:30:00.000Z"
},
{
"id": "5678def",
"name": "Data Sync Workflow",
"active": false,
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-12T10:15:00.000Z"
}
],
"count": 2,
"pagination": {
"hasMore": false
}
}
```
### n8n://execution-stats
Provides aggregated statistics about workflow executions.
**URI:** `n8n://execution-stats`
**Description:** Returns summary statistics about workflow executions, including counts by status, average execution times, and recent trends.
**Example Usage:**
```javascript
const resource = await accessMcpResource('n8n-mcp-server', 'n8n://execution-stats');
```
**Response:**
```javascript
{
"totalExecutions": 1250,
"statusCounts": {
"success": 1050,
"error": 180,
"cancelled": 20
},
"averageExecutionTime": 3.5, // seconds
"recentActivity": {
"last24Hours": 125,
"last7Days": 450
},
"topWorkflows": [
{
"id": "1234abc",
"name": "Email Processing Workflow",
"executionCount": 256
},
{
"id": "5678def",
"name": "Data Sync Workflow",
"executionCount": 198
}
]
}
```
### n8n://health
Provides health information about the n8n instance.
**URI:** `n8n://health`
**Description:** Returns health status information about the n8n instance including connection status, version, and basic metrics.
**Example Usage:**
```javascript
const resource = await accessMcpResource('n8n-mcp-server', 'n8n://health');
```
**Response:**
```javascript
{
"status": "healthy",
"n8nVersion": "1.5.0",
"uptime": 259200, // seconds (3 days)
"databaseStatus": "connected",
"apiStatus": "operational",
"memoryUsage": {
"rss": "156MB",
"heapTotal": "85MB",
"heapUsed": "72MB"
}
}
```
## Content Types
All static resources return JSON content with the MIME type `application/json`.
## Authentication
Access to static resources requires the same authentication as tools, using the configured n8n API key. If authentication fails, the resource will return an error.
## Error Handling
Static resources can return the following errors:
| HTTP Status | Description |
|-------------|-------------|
| 401 | Unauthorized - Invalid or missing API key |
| 403 | Forbidden - API key does not have permission to access this resource |
| 500 | Internal Server Error - An unexpected error occurred on the n8n server |
## Pagination
Some resources that return large collections (like `n8n://workflows/list`) support pagination. The response includes a `pagination` object with information about whether more results are available.
## Best Practices
- Use static resources for getting an overview of what's available in the n8n instance
- Prefer static resources over tools when you only need to read data
- Check the health resource before performing operations to ensure the n8n instance is operational
- Use execution statistics to monitor the performance and reliability of your workflows

375
docs/api/workflow-tools.md Normal file
View File

@@ -0,0 +1,375 @@
# Workflow Tools
This page documents the tools available for managing n8n workflows.
## Overview
Workflow tools allow AI assistants to manage n8n workflows, including creating, retrieving, updating, deleting, activating, and deactivating workflows. These tools provide a natural language interface to n8n's workflow management capabilities.
## Available Tools
### workflow_list
Lists all workflows with optional filtering.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"active": {
"type": "boolean",
"description": "Filter workflows by active status"
}
},
"required": []
}
```
**Example Usage:**
```javascript
// List all workflows
const result = await useWorkflowList({});
// List only active workflows
const activeWorkflows = await useWorkflowList({ active: true });
// List only inactive workflows
const inactiveWorkflows = await useWorkflowList({ active: false });
```
**Response:**
```javascript
[
{
"id": "1234abc",
"name": "Test Workflow 1",
"active": true,
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-02T14:30:00.000Z"
},
{
"id": "5678def",
"name": "Test Workflow 2",
"active": false,
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-12T10:15:00.000Z"
}
]
```
### workflow_get
Retrieves a specific workflow by ID.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the workflow to retrieve"
}
},
"required": ["id"]
}
```
**Example Usage:**
```javascript
const workflow = await useWorkflowGet({ id: "1234abc" });
```
**Response:**
```javascript
{
"id": "1234abc",
"name": "Test Workflow 1",
"active": true,
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-02T14:30:00.000Z",
"nodes": [
// Detailed node configuration
],
"connections": {
// Connection configuration
},
"settings": {
// Workflow settings
}
}
```
### workflow_create
Creates a new workflow.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the workflow"
},
"nodes": {
"type": "array",
"description": "Array of node configurations"
},
"connections": {
"type": "object",
"description": "Connection configuration"
},
"active": {
"type": "boolean",
"description": "Whether the workflow should be active"
},
"settings": {
"type": "object",
"description": "Workflow settings"
}
},
"required": ["name"]
}
```
**Example Usage:**
```javascript
const newWorkflow = await useWorkflowCreate({
name: "New Workflow",
active: true,
nodes: [
{
"name": "Start",
"type": "n8n-nodes-base.start",
"position": [100, 200],
"parameters": {}
}
],
connections: {}
});
```
**Response:**
```javascript
{
"id": "new123",
"name": "New Workflow",
"active": true,
"createdAt": "2025-03-12T15:30:00.000Z",
"updatedAt": "2025-03-12T15:30:00.000Z",
"nodes": [
{
"name": "Start",
"type": "n8n-nodes-base.start",
"position": [100, 200],
"parameters": {}
}
],
"connections": {}
}
```
### workflow_update
Updates an existing workflow.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the workflow to update"
},
"name": {
"type": "string",
"description": "New name for the workflow"
},
"nodes": {
"type": "array",
"description": "Updated array of node configurations"
},
"connections": {
"type": "object",
"description": "Updated connection configuration"
},
"active": {
"type": "boolean",
"description": "Whether the workflow should be active"
},
"settings": {
"type": "object",
"description": "Updated workflow settings"
}
},
"required": ["id"]
}
```
**Example Usage:**
```javascript
const updatedWorkflow = await useWorkflowUpdate({
id: "1234abc",
name: "Updated Workflow Name",
active: false
});
```
**Response:**
```javascript
{
"id": "1234abc",
"name": "Updated Workflow Name",
"active": false,
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-12T15:45:00.000Z",
"nodes": [
// Existing node configuration
],
"connections": {
// Existing connection configuration
}
}
```
### workflow_delete
Deletes a workflow.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the workflow to delete"
}
},
"required": ["id"]
}
```
**Example Usage:**
```javascript
await useWorkflowDelete({ id: "1234abc" });
```
**Response:**
```javascript
{
"success": true
}
```
### workflow_activate
Activates a workflow.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the workflow to activate"
}
},
"required": ["id"]
}
```
**Example Usage:**
```javascript
const activatedWorkflow = await useWorkflowActivate({ id: "1234abc" });
```
**Response:**
```javascript
{
"id": "1234abc",
"name": "Test Workflow 1",
"active": true,
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-12T16:00:00.000Z"
}
```
### workflow_deactivate
Deactivates a workflow.
**Input Schema:**
```json
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the workflow to deactivate"
}
},
"required": ["id"]
}
```
**Example Usage:**
```javascript
const deactivatedWorkflow = await useWorkflowDeactivate({ id: "1234abc" });
```
**Response:**
```javascript
{
"id": "1234abc",
"name": "Test Workflow 1",
"active": false,
"createdAt": "2025-03-01T12:00:00.000Z",
"updatedAt": "2025-03-12T16:15:00.000Z"
}
```
## Error Handling
All workflow tools can return the following errors:
| Error | Description |
|-------|-------------|
| Authentication Error | The provided API key is invalid or missing |
| Not Found Error | The requested workflow does not exist |
| Validation Error | The input parameters are invalid or incomplete |
| Permission Error | The API key does not have permission to perform the operation |
| Server Error | An unexpected error occurred on the n8n server |
## Best Practices
- Use `workflow_list` to discover available workflows before performing operations
- Validate workflow IDs before attempting to update or delete workflows
- Check workflow status (active/inactive) before attempting activation/deactivation
- Include only the necessary fields when updating workflows to avoid unintended changes