Initial commit of n8n MCP Server
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
111
docs/setup/configuration.md
Normal file
111
docs/setup/configuration.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# Configuration Guide
|
||||
|
||||
This guide provides detailed information on configuring the n8n MCP Server.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
The n8n MCP Server is configured using environment variables, which can be set in a `.env` file or directly in your environment.
|
||||
|
||||
### Required Variables
|
||||
|
||||
| Variable | Description | Example |
|
||||
|----------|-------------|---------|
|
||||
| `N8N_API_URL` | URL of the n8n API | `http://localhost:5678/api/v1` |
|
||||
| `N8N_API_KEY` | API key for authenticating with n8n | `n8n_api_...` |
|
||||
|
||||
### Optional Variables
|
||||
|
||||
| Variable | Description | Default | Example |
|
||||
|----------|-------------|---------|---------|
|
||||
| `DEBUG` | Enable debug logging | `false` | `true` or `false` |
|
||||
|
||||
## Creating a .env File
|
||||
|
||||
The simplest way to configure the server is to create a `.env` file in the directory where you'll run the server:
|
||||
|
||||
```bash
|
||||
# Copy the example .env file
|
||||
cp .env.example .env
|
||||
|
||||
# Edit the .env file with your settings
|
||||
nano .env # or use any text editor
|
||||
```
|
||||
|
||||
Example `.env` file:
|
||||
|
||||
```env
|
||||
# n8n MCP Server Environment Variables
|
||||
|
||||
# Required: URL of the n8n API
|
||||
N8N_API_URL=http://localhost:5678/api/v1
|
||||
|
||||
# Required: API key for authenticating with n8n
|
||||
N8N_API_KEY=your_n8n_api_key_here
|
||||
|
||||
# Optional: Set to 'true' to enable debug logging
|
||||
DEBUG=false
|
||||
```
|
||||
|
||||
## Generating an n8n API Key
|
||||
|
||||
To use the n8n MCP Server, you need an API key from your n8n instance:
|
||||
|
||||
1. Open your n8n instance in a browser
|
||||
2. Go to **Settings** > **API** > **API Keys**
|
||||
3. Click **Create** to create a new API key
|
||||
4. Set appropriate **Scope** (recommended: `workflow:read workflow:write workflow:execute`)
|
||||
5. Copy the key to your `.env` file
|
||||
|
||||
|
||||
|
||||
## Server Connection Options
|
||||
|
||||
By default, the n8n MCP Server listens on `stdin` and `stdout` for Model Context Protocol communications. This is the format expected by AI assistants using the MCP protocol.
|
||||
|
||||
## Configuring AI Assistants
|
||||
|
||||
To use the n8n MCP Server with AI assistants, you need to register it with your AI assistant platform. The exact method depends on the platform you're using.
|
||||
|
||||
### Using the MCP Installer
|
||||
|
||||
If you're using Claude or another assistant that supports the MCP Installer, you can register the server with:
|
||||
|
||||
```bash
|
||||
# Install the MCP Installer
|
||||
npx @anaisbetts/mcp-installer
|
||||
|
||||
# Register the server (if installed globally)
|
||||
install_repo_mcp_server n8n-mcp-server
|
||||
|
||||
# Or register from a local installation
|
||||
install_local_mcp_server path/to/n8n-mcp-server
|
||||
```
|
||||
|
||||
### Manual Configuration
|
||||
|
||||
For platforms without an installer, you'll need to configure the connection according to the platform's documentation. Typically, this involves:
|
||||
|
||||
1. Specifying the path to the executable
|
||||
2. Setting environment variables for the server
|
||||
3. Configuring response formatting
|
||||
|
||||
## Verifying Configuration
|
||||
|
||||
To verify your configuration:
|
||||
|
||||
1. Start the server
|
||||
2. Open your AI assistant
|
||||
3. Try a simple command like "List all workflows in n8n"
|
||||
|
||||
If configured correctly, the assistant should be able to retrieve and display your workflows.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you encounter issues with your configuration, check:
|
||||
|
||||
- The `.env` file is in the correct location
|
||||
- The n8n API URL is accessible from where the server is running
|
||||
- The API key has the correct permissions
|
||||
- Any firewalls or network restrictions that might block connections
|
||||
|
||||
For more specific issues, see the [Troubleshooting](./troubleshooting.md) guide.
|
||||
18
docs/setup/index.md
Normal file
18
docs/setup/index.md
Normal file
@@ -0,0 +1,18 @@
|
||||
# Setup and Configuration
|
||||
|
||||
This section covers everything you need to know to set up and configure the n8n MCP Server.
|
||||
|
||||
## Topics
|
||||
|
||||
- [Installation](./installation.md): Instructions for installing the n8n MCP Server from npm or from source.
|
||||
- [Configuration](./configuration.md): Information on configuring the server, including environment variables and n8n API setup.
|
||||
- [Troubleshooting](./troubleshooting.md): Solutions to common issues you might encounter.
|
||||
|
||||
## Quick Start
|
||||
|
||||
For a quick start, follow these steps:
|
||||
|
||||
1. Install the server: `npm install -g n8n-mcp-server`
|
||||
2. Create a `.env` file with your n8n API URL and API key
|
||||
3. Run the server: `n8n-mcp-server`
|
||||
4. Register the server with your AI assistant platform
|
||||
83
docs/setup/installation.md
Normal file
83
docs/setup/installation.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# Installation Guide
|
||||
|
||||
This guide covers the installation process for the n8n MCP Server.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before installing the n8n MCP Server, ensure you have:
|
||||
|
||||
- Node.js 18 or later installed
|
||||
- An n8n instance running and accessible via HTTP/HTTPS
|
||||
- API access enabled on your n8n instance
|
||||
- An API key with appropriate permissions (see [Configuration](./configuration.md))
|
||||
|
||||
## Option 1: Install from npm (Recommended)
|
||||
|
||||
The easiest way to install the n8n MCP Server is from npm:
|
||||
|
||||
```bash
|
||||
npm install -g n8n-mcp-server
|
||||
```
|
||||
|
||||
This will install the server globally, making the `n8n-mcp-server` command available in your terminal.
|
||||
|
||||
## Option 2: Install from Source
|
||||
|
||||
For development purposes or to use the latest features, you can install from source:
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/yourusername/n8n-mcp-server.git
|
||||
cd n8n-mcp-server
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Build the project
|
||||
npm run build
|
||||
|
||||
# Optional: Install globally
|
||||
npm install -g .
|
||||
```
|
||||
|
||||
## Verifying Installation
|
||||
|
||||
Once installed, you can verify the installation by running:
|
||||
|
||||
```bash
|
||||
n8n-mcp-server --version
|
||||
```
|
||||
|
||||
This should display the version number of the installed n8n MCP Server.
|
||||
|
||||
## Next Steps
|
||||
|
||||
After installation, you'll need to:
|
||||
|
||||
1. [Configure the server](./configuration.md) by setting up environment variables
|
||||
2. Run the server
|
||||
3. Register the server with your AI assistant platform
|
||||
|
||||
## Upgrading
|
||||
|
||||
To upgrade a global installation from npm:
|
||||
|
||||
```bash
|
||||
npm update -g n8n-mcp-server
|
||||
```
|
||||
|
||||
To upgrade a source installation:
|
||||
|
||||
```bash
|
||||
# Navigate to the repository directory
|
||||
cd n8n-mcp-server
|
||||
|
||||
# Pull the latest changes
|
||||
git pull
|
||||
|
||||
# Install dependencies and rebuild
|
||||
npm install
|
||||
npm run build
|
||||
|
||||
# If installed globally, reinstall
|
||||
npm install -g .
|
||||
149
docs/setup/troubleshooting.md
Normal file
149
docs/setup/troubleshooting.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
This guide addresses common issues you might encounter when setting up and using the n8n MCP Server.
|
||||
|
||||
## Connection Issues
|
||||
|
||||
### Cannot Connect to n8n API
|
||||
|
||||
**Symptoms:**
|
||||
- Error messages mentioning "Connection refused" or "Cannot connect to n8n API"
|
||||
- Timeout errors when trying to use MCP tools
|
||||
|
||||
**Possible Solutions:**
|
||||
1. **Verify n8n is running:**
|
||||
- Ensure your n8n instance is running and accessible
|
||||
- Try accessing the n8n URL in a browser
|
||||
|
||||
2. **Check n8n API URL:**
|
||||
- Verify the `N8N_API_URL` in your `.env` file
|
||||
- Make sure it includes the full path (e.g., `http://localhost:5678/api/v1`)
|
||||
- Check for typos or incorrect protocol (http vs https)
|
||||
|
||||
3. **Network Configuration:**
|
||||
- If running on a different machine, ensure there are no firewall rules blocking access
|
||||
- Check if n8n is configured to allow remote connections
|
||||
|
||||
4. **HTTPS/SSL Issues:**
|
||||
- If using HTTPS, ensure certificates are valid
|
||||
- For self-signed certificates, you may need to set up additional configuration
|
||||
|
||||
### Authentication Failures
|
||||
|
||||
**Symptoms:**
|
||||
- "Authentication failed" or "Invalid API key" messages
|
||||
- 401 or 403 HTTP status codes
|
||||
|
||||
**Possible Solutions:**
|
||||
1. **Verify API Key:**
|
||||
- Check that the `N8N_API_KEY` in your `.env` file matches the one in n8n
|
||||
- Create a new API key if necessary
|
||||
|
||||
2. **Check API Key Permissions:**
|
||||
- Ensure the API key has appropriate scopes/permissions
|
||||
- Required scopes: `workflow:read workflow:write workflow:execute`
|
||||
|
||||
3. **n8n API Settings:**
|
||||
- Verify that API access is enabled in n8n settings
|
||||
- Check if there are IP restrictions on API access
|
||||
|
||||
## MCP Server Issues
|
||||
|
||||
### Server Crashes or Exits Unexpectedly
|
||||
|
||||
**Symptoms:**
|
||||
- The MCP server stops running unexpectedly
|
||||
- Error messages in logs or console output
|
||||
|
||||
**Possible Solutions:**
|
||||
1. **Check Node.js Version:**
|
||||
- Ensure you're using Node.js 18 or later
|
||||
- Check with `node --version`
|
||||
|
||||
2. **Check Environment Variables:**
|
||||
- Ensure all required environment variables are set
|
||||
- Verify the format of the environment variables
|
||||
|
||||
3. **View Debug Logs:**
|
||||
- Set `DEBUG=true` in your `.env` file
|
||||
- Check the console output for detailed error messages
|
||||
|
||||
4. **Memory Issues:**
|
||||
- If running on a system with limited memory, increase available memory
|
||||
- Check for memory leaks or high consumption patterns
|
||||
|
||||
### AI Assistant Cannot Communicate with MCP Server
|
||||
|
||||
**Symptoms:**
|
||||
- AI assistant reports it cannot connect to the MCP server
|
||||
- Tools are not available in the assistant interface
|
||||
|
||||
**Possible Solutions:**
|
||||
1. **Verify Server Registration:**
|
||||
- Ensure the server is properly registered with your AI assistant platform
|
||||
- Check the configuration settings for the MCP server in your assistant
|
||||
|
||||
2. **Server Running Check:**
|
||||
- Verify the MCP server is running
|
||||
- Check that it was started with the correct environment
|
||||
|
||||
3. **Restart Components:**
|
||||
- Restart the MCP server
|
||||
- Refresh the AI assistant interface
|
||||
- If using a managed AI assistant, check platform status
|
||||
|
||||
## Tool-Specific Issues
|
||||
|
||||
### Workflow Operations Fail
|
||||
|
||||
**Symptoms:**
|
||||
- Cannot list, create, or update workflows
|
||||
- Error messages about missing permissions
|
||||
|
||||
**Possible Solutions:**
|
||||
1. **API Key Scope:**
|
||||
- Ensure your API key has `workflow:read` and `workflow:write` permissions
|
||||
- Create a new key with appropriate permissions if needed
|
||||
|
||||
2. **n8n Version:**
|
||||
- Check if your n8n version supports all the API endpoints being used
|
||||
- Update n8n to the latest version if possible
|
||||
|
||||
3. **Workflow Complexity:**
|
||||
- Complex workflows with custom nodes may not work correctly
|
||||
- Try with simpler workflows to isolate the issue
|
||||
|
||||
### Execution Operations Fail
|
||||
|
||||
**Symptoms:**
|
||||
- Cannot execute workflows or retrieve execution data
|
||||
- Execution starts but fails to complete
|
||||
|
||||
**Possible Solutions:**
|
||||
1. **API Key Scope:**
|
||||
- Ensure your API key has the `workflow:execute` permission
|
||||
- Create a new key with appropriate permissions if needed
|
||||
|
||||
2. **Workflow Status:**
|
||||
- Check if the target workflow is active
|
||||
- Verify the workflow executes correctly in the n8n interface
|
||||
|
||||
3. **Workflow Inputs:**
|
||||
- Ensure all required inputs for workflow execution are provided
|
||||
- Check the format of input data
|
||||
|
||||
## Getting More Help
|
||||
|
||||
If you're still experiencing issues after trying these troubleshooting steps:
|
||||
|
||||
1. **Check GitHub Issues:**
|
||||
- Look for similar issues in the [GitHub repository](https://github.com/yourusername/n8n-mcp-server/issues)
|
||||
- Create a new issue with detailed information about your problem
|
||||
|
||||
2. **Submit Logs:**
|
||||
- Enable debug logging with `DEBUG=true`
|
||||
- Include relevant logs when seeking help
|
||||
|
||||
3. **Community Support:**
|
||||
- Ask in the n8n community forums
|
||||
- Check MCP-related discussion groups
|
||||
Reference in New Issue
Block a user