Skip to content

oarslan/N8Net.Mcp

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
N8Net.Client
N8Net.Client
 
 
N8Net.Mcp
N8Net.Mcp
 
 
N8Net.Tests
N8Net.Tests
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
N8Net.Mcp.sln
N8Net.Mcp.sln
 
 
README.md
README.md
 
 

Repository files navigation

N8Net.Mcp

Model Context Protocol (MCP) server for n8n workflow automation

N8Net.Mcp is a .NET 8.0 MCP server that provides seamless integration between Claude Desktop and n8n workflow automation platform. This enables you to manage n8n workflows and executions directly through natural language conversations with Claude.

Features

  • Workflow Management: Create, retrieve, activate, deactivate, and delete n8n workflows
  • Execution Monitoring: View and manage workflow executions with advanced filtering
  • Dynamic Node Support: Automatically uses the latest n8n node versions
  • Flexible Triggers: Support for webhook, manual, schedule, and various integration triggers (Slack, Telegram, GitHub, Discord, etc.)
  • Natural Language Interface: Interact with n8n through conversational commands in Claude Desktop

Supported MCP Operations

N8Net.Mcp currently supports the following n8n API operations through MCP tools:

Workflow Operations

  • GetConfiguration - View current n8n configuration and connection status
  • GetActiveWorkflowsAsync - List all active workflows with pagination
  • GetWorkflowByIdAsync - Get detailed information about a specific workflow
  • CreateWorkflowAsync - Create new workflows with custom nodes and triggers
  • DeleteWorkflowAsync - Delete a workflow by ID
  • ActivateWorkflowAsync - Activate a workflow to enable automatic execution
  • DeactivateWorkflowAsync - Deactivate a workflow to prevent automatic execution

Execution Operations

  • GetExecutionsAsync - List workflow executions with filtering (status, workflow ID, project ID)
  • GetExecutionByIdAsync - Get detailed execution information including data
  • DeleteExecutionAsync - Delete a specific execution record

Prerequisites

  • .NET 8.0 SDK
  • n8n instance (local or remote) - tested with n8n v1.122.4
  • n8n API key
  • Claude Desktop application

Installation

1. Build the Project

cd path/to/N8Net.Mcp
dotnet build -c Release

2. Configure Claude Desktop

Add the following configuration to your Claude Desktop config file:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "n8net": {
      "command": "/usr/local/share/dotnet/dotnet",
      "args": [
        "/absolute/path/to/N8Net.Mcp/N8Net.Mcp/bin/Release/net8.0/N8Net.Mcp.dll"
      ],
      "env": {
        "N8n__ServiceUrl": "http://localhost:5678/api/v1/",
        "N8n__ApiKey": "your-n8n-api-key-here",
        "ASPNETCORE_ENVIRONMENT": "Production"
      }
    }
  }
}

Important:

  • Use the absolute path to your dotnet executable (find it with which dotnet)
  • Update the DLL path to match your project location
  • Replace your-n8n-api-key-here with your actual n8n API key
  • Ensure the N8n__ServiceUrl matches your n8n instance URL

3. Restart Claude Desktop

After saving the configuration, restart Claude Desktop to load the MCP server.

Available Tools

Workflow Management

1. GetConfiguration

Retrieves the current n8n configuration (service URL and API key status).

Example: "Show me my n8n configuration"

2. GetActiveWorkflowsAsync

Lists active workflows from your n8n instance.

Parameters:

  • limit (optional, default: 10): Number of workflows to retrieve
Example: "Show me my active workflows"
Example: "Get the first 20 active workflows"

3. GetWorkflowByIdAsync

Retrieves detailed information about a specific workflow.

Parameters:

  • workflowId (required): The ID of the workflow
Example: "Get workflow details for workflow ID abc123"

4. CreateWorkflowAsync

Creates a new workflow in n8n with automatic node configuration.

Parameters:

  • workflowName (required): Name of the workflow
  • description (required): Description of what the workflow does
  • triggerType (optional, default: "webhook"): Type of trigger to use
    • Common triggers: webhook, manual, schedule, slack, telegram, github, discord, gmail, notion, etc.
  • nodes (optional): Nodes to add to the workflow
    • Format: "3 slack, 1 gmail, 2 notion"
    • Supported nodes: slack, gmail, notion, http, code, set, if, switch, webhook, discord, telegram, and many more
Example: "Create a workflow called 'Slack Notifications' that sends messages to Slack"
Example: "Create a workflow with 2 slack nodes and 1 gmail node called 'Email to Slack'"
Example: "Create a manual trigger workflow for data processing"

Note: Workflows with webhook triggers can be activated/deactivated. Use manual trigger for workflows that need to be executed manually.

5. DeleteWorkflowAsync

Deletes a workflow from n8n.

Parameters:

  • workflowId (required): The ID of the workflow to delete
Example: "Delete workflow xyz789"

6. ActivateWorkflowAsync

Activates a workflow, enabling it to run automatically based on its trigger.

Parameters:

  • workflowId (required): The ID of the workflow to activate
Example: "Activate workflow abc123"

7. DeactivateWorkflowAsync

Deactivates a workflow, preventing it from running automatically.

Parameters:

  • workflowId (required): The ID of the workflow to deactivate
Example: "Deactivate workflow abc123"

Execution Management

8. GetExecutionsAsync

Retrieves a list of workflow executions with advanced filtering options.

Parameters:

  • limit (optional, default: 5): Number of executions to retrieve
  • includeData (optional, default: false): Include execution data in response
  • status (optional): Filter by execution status
    • Values: error, success, waiting
  • workflowId (optional): Filter by specific workflow ID
  • projectId (optional): Filter by project ID
Example: "Show me the last 10 executions"
Example: "Get failed executions"
Example: "Show executions for workflow abc123"
Example: "Get all successful executions with data"

9. GetExecutionByIdAsync

Retrieves detailed information about a specific execution.

Parameters:

  • executionId (required): The ID of the execution
  • includeData (optional, default: false): Include execution data in response
Example: "Get execution details for exec_456"
Example: "Show execution exec_789 with data"

10. DeleteExecutionAsync

Deletes a specific execution from n8n.

Parameters:

  • executionId (required): The ID of the execution to delete
Example: "Delete execution exec_456"

Usage Examples

Creating a Simple Webhook Workflow

"Create a workflow called 'Process Orders' with a webhook trigger that processes incoming orders"

This creates an activatable workflow that can receive webhook requests.

Creating a Scheduled Workflow

"Create a schedule trigger workflow called 'Daily Report' that runs every day at 9 AM"

Creating a Workflow with Multiple Nodes

"Create a workflow called 'Slack to Gmail' with description 'Forward Slack messages to Gmail' using webhook trigger with 2 slack nodes and 1 gmail node"

Monitoring Failed Executions

"Show me all failed executions from the last 20 runs"

Managing Workflows

"Show me my active workflows, then activate workflow abc123"

Technical Details

Dynamic Node Versioning

N8Net.Mcp does not hardcode node type versions. Instead, it allows n8n to automatically use the latest available version of each node type. This ensures compatibility when n8n releases updates and prevents breaking changes.

API Authentication

All requests to the n8n API include the X-N8N-API-KEY header for authentication. The API key is configured through environment variables in the Claude Desktop configuration.

MCP Integration

The project uses the Model Context Protocol SDK (ModelContextProtocol v0.4.1-preview.1) to expose n8n functionality as tools that Claude can use. Each tool is marked with the [McpServerTool] attribute and includes detailed descriptions for natural language understanding.

Configuration

appsettings.json

{
  "N8n": {
    "ServiceUrl": "http://localhost:5678/api/v1/",
    "ApiKey": "your-n8n-api-key"
  }
}

Environment Variables (Recommended for Claude Desktop)

  • N8n__ServiceUrl: Your n8n instance API URL
  • N8n__ApiKey: Your n8n API key

Environment variables override appsettings.json values and are the recommended approach for Claude Desktop integration.

Architecture

N8Net.Mcp/
├── N8Net/                          # Main MCP server project
│   ├── Services/
│   │   ├── IN8nService.cs         # Service interface
│   │   ├── N8nService.cs          # MCP tools implementation
│   │   ├── IWorkflowBuilder.cs    # Workflow builder interface
│   │   └── WorkflowBuilder.cs     # Workflow JSON builder
│   ├── Models/
│   │   ├── N8nConfiguration.cs    # Configuration model
│   │   └── Workflow/              # Workflow domain models
│   ├── Extensions/
│   │   └── ServiceCollectionExtensions.cs  # DI setup
│   └── Program.cs                 # Application entry point
├── N8Net.Tests/                   # Unit tests
│   ├── Services/
│   │   └── N8nServiceTests.cs     # Service tests
│   ├── Extensions/
│   │   └── ServiceCollectionExtensionsTests.cs
│   └── Models/
│       └── N8nConfigurationTests.cs
└── N8Net.Client/                  # Future: Client library

Debugging and Logs

Log File Location

N8Net.Mcp writes detailed logs to help with debugging and monitoring:

Log Path: ~/.n8net/logs/n8net-YYYYMMDD.log

Example: ~/.n8net/logs/n8net-20251216.log

Log Contents

The log file includes:

  • Service initialization and configuration
  • All n8n API calls and responses
  • Errors with full stack traces
  • MCP tool invocations
  • Debug information for troubleshooting

Viewing Logs

# View today's log
cat ~/.n8net/logs/n8net-$(date +%Y%m%d).log

# Follow log in real-time
tail -f ~/.n8net/logs/n8net-$(date +%Y%m%d).log

# View last 50 lines
tail -50 ~/.n8net/logs/n8net-$(date +%Y%m%d).log

Log Retention

Logs are automatically rotated daily and kept for 7 days.

Troubleshooting

MCP Server Not Responding

  1. Check the logs: cat ~/.n8net/logs/n8net-$(date +%Y%m%d).log
  2. Look for initialization errors in the log file
  3. Verify configuration: Ensure API key and service URL are correct
  4. Check n8n is running: curl http://localhost:5678/api/v1/workflows?limit=1 -H "X-N8N-API-KEY: your-key"

"spawn dotnet ENOENT" Error

Use the absolute path to dotnet in your Claude Desktop config. Find it with:

which dotnet

"Building... is not valid JSON" Error

Make sure you're running the pre-built DLL directly, not using dotnet run. Always build first:

dotnet build -c Release

Workflow Creation Fails with "active is read-only"

This has been fixed in the current version. The server no longer sends read-only fields like active, versionId, id, meta, or tags during workflow creation.

Connection Refused

Verify that:

  1. Your n8n instance is running
  2. The N8n__ServiceUrl is correct
  3. The API endpoint is accessible

Testing

The project includes comprehensive unit tests. See N8Net.Tests/README.md for details.

Run tests:

dotnet test

Run tests with custom configuration:

N8n__ServiceUrl="http://localhost:5678/api/v1/" \
N8n__ApiKey="your-api-key" \
dotnet test

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

This project is licensed under the MIT License.

About

Model Context Protocol (MCP) server for n8n workflow automation

Topics

dotnet mcp workflow-automation n8n claude-desktop model-context-protocol

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages