# n8n Automation Plugin Design
> **Phase I: n8n Automation Plugin**
> **Priority**: High (Upgraded from Medium)
> **Estimated Tools**: 55-60
---
## Overview
The n8n plugin provides comprehensive automation workflow management through n8n's REST API. This enables AI assistants to create, manage, execute, and monitor automation workflows programmatically.
### Key Capabilities
- Complete workflow lifecycle management (CRUD + activate/deactivate/execute)
- Execution monitoring and history
- Credential management for third-party integrations
- Project and user management (Enterprise/Pro features)
- Environment variables management
- Security audit and source control integration
---
## Architecture
### Plugin Structure
```
plugins/n8n/
├── __init__.py
├── plugin.py # N8nPlugin class
├── client.py # N8nClient (REST API communication)
└── handlers/
├── __init__.py
├── workflows.py # Workflow management (14 tools)
├── executions.py # Execution monitoring (8 tools)
├── credentials.py # Credential management (8 tools)
├── tags.py # Tag management (6 tools)
├── users.py # User management (6 tools)
├── projects.py # Project management (8 tools)
├── variables.py # Variable management (6 tools)
└── system.py # Audit & Source Control (4 tools)
```
### Authentication
n8n uses API Key authentication via `X-N8N-API-KEY` header.
```python
# Environment Variables
N8N_SITE1_URL=https://n8n.example.com
N8N_SITE1_API_KEY=your-api-key
N8N_SITE1_ALIAS=myautomation # Optional friendly name
```
---
## Tool Specifications (55-60 Tools)
### 1. Workflows Handler (14 tools)
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_workflows` | GET | read | List all workflows with filters (active, tags, name) |
| `get_workflow` | GET | read | Get workflow details by ID |
| `create_workflow` | POST | write | Create new workflow from JSON definition |
| `update_workflow` | PUT | write | Update existing workflow |
| `delete_workflow` | DELETE | admin | Delete a workflow |
| `activate_workflow` | POST | write | Activate a workflow |
| `deactivate_workflow` | POST | write | Deactivate a workflow |
| `execute_workflow` | POST | write | Manually execute a workflow |
| `execute_workflow_with_data` | POST | write | Execute with custom input data |
| `duplicate_workflow` | POST | write | Duplicate an existing workflow |
| `export_workflow` | GET | read | Export workflow as JSON |
| `import_workflow` | POST | write | Import workflow from JSON |
| `get_workflow_tags` | GET | read | Get tags assigned to a workflow |
| `set_workflow_tags` | PUT | write | Assign tags to a workflow |
#### Tool Specification Example
```python
{
"name": "list_workflows",
"method_name": "list_workflows",
"description": "List all n8n workflows with optional filters. Returns workflow ID, name, active status, and metadata.",
"schema": {
"type": "object",
"properties": {
"active": {
"type": "boolean",
"description": "Filter by active/inactive status"
},
"tags": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Filter by tag name(s), comma-separated"
},
"name": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Filter by workflow name (partial match)"
},
"limit": {
"type": "integer",
"description": "Maximum workflows to return",
"default": 50,
"minimum": 1,
"maximum": 250
},
"cursor": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Pagination cursor for next page"
}
}
},
"scope": "read"
}
```
```python
{
"name": "execute_workflow",
"method_name": "execute_workflow",
"description": "Manually execute a workflow and return execution ID. Use get_execution to check status.",
"schema": {
"type": "object",
"properties": {
"workflow_id": {
"type": "string",
"description": "Workflow ID to execute",
"minLength": 1
},
"wait": {
"type": "boolean",
"description": "Wait for execution to complete (max 5 minutes)",
"default": False
}
},
"required": ["workflow_id"]
},
"scope": "write"
}
```
```python
{
"name": "execute_workflow_with_data",
"method_name": "execute_workflow_with_data",
"description": "Execute workflow with custom input data. Useful for workflows with webhook/manual triggers.",
"schema": {
"type": "object",
"properties": {
"workflow_id": {
"type": "string",
"description": "Workflow ID to execute",
"minLength": 1
},
"data": {
"type": "object",
"description": "Input data to pass to workflow trigger node"
},
"wait": {
"type": "boolean",
"description": "Wait for execution to complete",
"default": False
}
},
"required": ["workflow_id", "data"]
},
"scope": "write"
}
```
---
### 2. Executions Handler (8 tools)
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_executions` | GET | read | List workflow executions with filters |
| `get_execution` | GET | read | Get execution details and data |
| `delete_execution` | DELETE | write | Delete a single execution |
| `delete_executions` | DELETE | write | Bulk delete executions |
| `stop_execution` | POST | write | Stop a running execution |
| `retry_execution` | POST | write | Retry a failed execution |
| `get_execution_data` | GET | read | Get full execution data including node outputs |
| `wait_for_execution` | GET | read | Poll until execution completes |
#### Tool Specification Examples
```python
{
"name": "list_executions",
"method_name": "list_executions",
"description": "List workflow executions with filters by status, workflow, date range. Returns execution history.",
"schema": {
"type": "object",
"properties": {
"workflow_id": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Filter by workflow ID"
},
"status": {
"anyOf": [{"type": "string", "enum": ["success", "error", "waiting", "running", "new"]}, {"type": "null"}],
"description": "Filter by execution status"
},
"include_data": {
"type": "boolean",
"description": "Include full execution data",
"default": False
},
"limit": {
"type": "integer",
"description": "Maximum results",
"default": 20,
"minimum": 1,
"maximum": 250
},
"cursor": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Pagination cursor"
}
}
},
"scope": "read"
}
```
```python
{
"name": "get_execution",
"method_name": "get_execution",
"description": "Get detailed information about a specific execution including status, timing, and optionally full data.",
"schema": {
"type": "object",
"properties": {
"execution_id": {
"type": "string",
"description": "Execution ID",
"minLength": 1
},
"include_data": {
"type": "boolean",
"description": "Include full node execution data",
"default": True
}
},
"required": ["execution_id"]
},
"scope": "read"
}
```
---
### 3. Credentials Handler (8 tools)
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_credentials` | GET | read | List all credentials (without sensitive data) |
| `get_credential` | GET | read | Get credential metadata |
| `create_credential` | POST | admin | Create new credential |
| `update_credential` | PUT | admin | Update credential |
| `delete_credential` | DELETE | admin | Delete a credential |
| `get_credential_schema` | GET | read | Get schema for credential type |
| `list_credential_types` | GET | read | List available credential types |
| `transfer_credential` | POST | admin | Transfer credential to another project |
#### Tool Specification Examples
```python
{
"name": "list_credentials",
"method_name": "list_credentials",
"description": "List all stored credentials. Returns metadata only (no sensitive values).",
"schema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "Maximum results",
"default": 100,
"minimum": 1,
"maximum": 250
},
"cursor": {
"anyOf": [{"type": "string"}, {"type": "null"}],
"description": "Pagination cursor"
}
}
},
"scope": "read"
}
```
```python
{
"name": "create_credential",
"method_name": "create_credential",
"description": "Create a new credential for use in workflows. Use get_credential_schema to see required fields.",
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Credential display name",
"minLength": 1
},
"type": {
"type": "string",
"description": "Credential type (e.g., 'githubApi', 'slackApi')",
"minLength": 1
},
"data": {
"type": "object",
"description": "Credential data matching the schema for this type"
}
},
"required": ["name", "type", "data"]
},
"scope": "admin"
}
```
---
### 4. Tags Handler (6 tools)
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_tags` | GET | read | List all tags |
| `get_tag` | GET | read | Get tag details |
| `create_tag` | POST | write | Create a new tag |
| `update_tag` | PUT | write | Update tag name |
| `delete_tag` | DELETE | write | Delete a tag |
| `delete_tags` | DELETE | write | Bulk delete tags |
---
### 5. Users Handler (6 tools)
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_users` | GET | admin | List all users |
| `get_user` | GET | admin | Get user details |
| `create_user` | POST | admin | Invite/create new user |
| `delete_user` | DELETE | admin | Delete a user |
| `change_user_role` | PUT | admin | Change user's global role |
| `get_current_user` | GET | read | Get current authenticated user |
---
### 6. Projects Handler (8 tools) - Enterprise/Pro
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_projects` | GET | read | List all projects |
| `get_project` | GET | read | Get project details |
| `create_project` | POST | admin | Create a new project |
| `update_project` | PUT | admin | Update project metadata |
| `delete_project` | DELETE | admin | Delete a project |
| `add_project_users` | POST | admin | Add users to project with roles |
| `change_project_user_role` | PUT | admin | Change user's role in project |
| `remove_project_user` | DELETE | admin | Remove user from project |
---
### 7. Variables Handler (6 tools)
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `list_variables` | GET | read | List all environment variables |
| `get_variable` | GET | read | Get variable value by key |
| `create_variable` | POST | admin | Create new variable |
| `update_variable` | PUT | admin | Update variable value |
| `delete_variable` | DELETE | admin | Delete a variable |
| `set_variables` | POST | admin | Bulk set multiple variables |
---
### 8. System Handler (4 tools)
| Tool | Method | Scope | Description |
|------|--------|-------|-------------|
| `run_security_audit` | POST | admin | Run security audit on instance |
| `source_control_pull` | POST | admin | Pull workflows from Git repository |
| `get_instance_info` | GET | read | Get n8n instance version and status |
| `health_check` | GET | read | Check n8n instance health |
---
## API Client Design
### N8nClient Class
```python
class N8nClient:
"""
n8n REST API client for HTTP communication.
Handles authentication, request formatting, and error handling
for all n8n API endpoints.
"""
def __init__(self, site_url: str, api_key: str):
"""
Initialize n8n API client.
Args:
site_url: n8n instance URL (e.g., https://n8n.example.com)
api_key: n8n API key for authentication
"""
self.site_url = site_url.rstrip('/')
self.api_base = f"{self.site_url}/api/v1"
self.api_key = api_key
def _get_headers(self) -> Dict[str, str]:
"""Get request headers with API key authentication."""
return {
"Content-Type": "application/json",
"Accept": "application/json",
"X-N8N-API-KEY": self.api_key
}
async def request(
self,
method: str,
endpoint: str,
params: Optional[Dict] = None,
json_data: Optional[Dict] = None
) -> Any:
"""Make authenticated request to n8n REST API."""
# Implementation similar to GiteaClient
```
---
## Endpoint Reference
### Base URL
```
{N8N_URL}/api/v1
```
### Workflows
```
GET /workflows - List workflows
POST /workflows - Create workflow
GET /workflows/{id} - Get workflow
PUT /workflows/{id} - Update workflow
DELETE /workflows/{id} - Delete workflow
POST /workflows/{id}/activate - Activate workflow
POST /workflows/{id}/deactivate - Deactivate workflow
POST /workflows/{id}/run - Execute workflow
```
### Executions
```
GET /executions - List executions
GET /executions/{id} - Get execution
DELETE /executions/{id} - Delete execution
```
### Credentials
```
GET /credentials - List credentials
POST /credentials - Create credential
GET /credentials/{id} - Get credential
DELETE /credentials/{id} - Delete credential
GET /credentials/schema/{type} - Get credential schema
POST /credentials/{id}/transfer - Transfer credential
```
### Tags
```
GET /tags - List tags
POST /tags - Create tag
GET /tags/{id} - Get tag
PUT /tags/{id} - Update tag
DELETE /tags/{id} - Delete tag
```
### Users
```
GET /users - List users
POST /users - Create/invite user
GET /users/{id} - Get user
DELETE /users/{id} - Delete user
PATCH /users/{id}/role - Change user role
```
### Projects (Enterprise/Pro)
```
GET /projects - List projects
POST /projects - Create project
GET /projects/{id} - Get project
PUT /projects/{id} - Update project
DELETE /projects/{id} - Delete project
POST /projects/{id}/users - Add users to project
```
### Variables
```
GET /variables - List variables
POST /variables - Create variable
GET /variables/{key} - Get variable
PUT /variables/{key} - Update variable
DELETE /variables/{key} - Delete variable
```
### System
```
POST /audit - Run security audit
POST /source-control/pull - Pull from Git
GET /health - Health check
```
---
## Multi-Endpoint Integration
### Endpoint Configuration
```python
# core/endpoints/config.py
ENDPOINT_CONFIGS = {
# ... existing configs ...
"n8n": EndpointConfig(
path="/n8n/mcp",
name="n8n Automation",
plugin_types=["n8n"],
description="Workflow automation management",
tools_count=55
)
}
```
### Per-Project Endpoint
```
/project/{alias}/mcp - Site-specific n8n endpoint
/project/myautomation/mcp
```
---
## Environment Configuration
```bash
# Single n8n instance
N8N_SITE1_URL=https://n8n.example.com
N8N_SITE1_API_KEY=your-api-key-here
N8N_SITE1_ALIAS=automation
# Multiple instances
N8N_SITE2_URL=https://n8n-staging.example.com
N8N_SITE2_API_KEY=staging-api-key
N8N_SITE2_ALIAS=automation-staging
```
---
## Use Cases
### 1. Workflow Management
```
User: "Create a new workflow that sends Slack notifications when a GitHub issue is created"
AI Assistant:
1. create_workflow with workflow JSON definition
2. activate_workflow to enable it
3. list_credentials to verify Slack/GitHub credentials exist
```
### 2. Execution Monitoring
```
User: "Show me failed executions from the last 24 hours"
AI Assistant:
1. list_executions with status="error" filter
2. get_execution for each to see error details
3. Provide summary and suggestions
```
### 3. Credential Management
```
User: "Set up new API credentials for OpenAI"
AI Assistant:
1. get_credential_schema for "openAiApi" type
2. create_credential with required fields
3. Confirm credential is ready for use
```
### 4. Security Audit
```
User: "Run a security audit on our n8n instance"
AI Assistant:
1. run_security_audit
2. Parse and summarize findings
3. Provide recommendations
```
---
## Implementation Priority
### Phase 1 (Core - Must Have)
1. Workflows handler (14 tools)
2. Executions handler (8 tools)
3. Client implementation
4. Plugin class
### Phase 2 (Extended - Should Have)
1. Credentials handler (8 tools)
2. Tags handler (6 tools)
3. Variables handler (6 tools)
### Phase 3 (Advanced - Nice to Have)
1. Users handler (6 tools)
2. Projects handler (8 tools)
3. System handler (4 tools)
---
## Security Considerations
1. **API Key Protection**: Store API keys securely, never log them
2. **Credential Handling**: Never expose credential values in responses
3. **Scope Enforcement**: Admin-level tools require admin scope
4. **Rate Limiting**: Respect n8n API rate limits
5. **Audit Logging**: Log all write/admin operations
---
## Testing Strategy
1. **Unit Tests**: Test each handler function independently
2. **Integration Tests**: Test against a local n8n instance
3. **Mock Tests**: Use mocked API responses for CI/CD
---
## Documentation Links
- [n8n Public REST API](https://docs.n8n.io/api/)
- [n8n API Reference](https://docs.n8n.io/api/api-reference/)
- [n8n Authentication](https://docs.n8n.io/api/authentication/)
---
## Summary
| Category | Tools | Priority |
|----------|-------|----------|
| Workflows | 14 | Phase 1 |
| Executions | 8 | Phase 1 |
| Credentials | 8 | Phase 2 |
| Tags | 6 | Phase 2 |
| Variables | 6 | Phase 2 |
| Users | 6 | Phase 3 |
| Projects | 8 | Phase 3 |
| System | 4 | Phase 3 |
| **Total** | **60** | - |
---
**Created**: 2025-11-27
**Author**: AI Assistant
**Status**: Design Document - Awaiting Implementation
