# Configuration Setup Guide
This guide explains how to configure the n8n MCP Workflow Builder to connect to your n8n instance(s).
---
## Overview
The MCP server supports two configuration methods:
| Method | Use Case | Configuration File |
|--------|----------|-------------------|
| **Single-Instance** | One n8n environment, personal projects | `.env` file |
| **Multi-Instance** | Multiple environments (prod, staging, dev) | `.config.json` file |
**Configuration Priority:** `.config.json` → `.env` → Environment Variables
---
## Getting n8n Credentials
Before configuring the MCP server, you'll need:
1. **n8n Host URL** - The base URL of your n8n instance
2. **n8n API Key** - Authentication key for API access
### Finding Your n8n Host URL
The format depends on your n8n deployment type:
=== "n8n Cloud"
**Format:** `https://<instance-name>.app.n8n.cloud`
**Example:** `https://my-company.app.n8n.cloud`
**How to find:**
1. Log into your n8n Cloud instance
2. Look at the browser URL bar
3. Copy everything up to `.cloud` (do not include `/workflow/` or other paths)
!!! warning "Important"
Use only the base URL - do **NOT** include `/api/v1` at the end. The server adds this automatically.
=== "Self-Hosted"
**Format:** `https://your-domain.com` or `http://localhost:5678`
**Examples:**
- Production: `https://n8n.mycompany.com`
- Development: `http://localhost:5678`
- Docker: `http://n8n:5678` (internal network)
**How to find:**
1. Check your n8n deployment configuration
2. Use the base URL you configured during installation
3. For local development, typically `http://localhost:5678`
**URL Normalization:**
The MCP server automatically appends `/api/v1` to your base URL:
```
Your Config: https://n8n.example.com
Actual API URL: https://n8n.example.com/api/v1
```
---
### Generating n8n API Key
Follow these steps to create an API key in n8n:
#### Step 1: Access n8n Settings
1. Log into your n8n instance
2. Click on your profile icon (bottom left)
3. Select **Settings** from the menu
#### Step 2: Navigate to API Section
1. In Settings, find the **API** tab
2. Click on **API** to open API settings
#### Step 3: Create API Key
1. Click **Create API Key** button
2. Enter a descriptive name (e.g., "MCP Server - Production")
3. Click **Create**
#### Step 4: Copy and Secure the Key
1. **Copy the API key immediately** - it will only be shown once
2. Store it securely (password manager recommended)
3. Never commit API keys to version control
!!! danger "Security Warning"
- API keys grant full access to your n8n instance
- Treat them like passwords
- Rotate keys regularly
- Use separate keys for different environments
**API Key Format:**
n8n API keys typically look like:
```
n8n_api_1234567890abcdefghijklmnopqrstuvwxyz
```
---
## Single-Instance Configuration
Use this method if you're connecting to just one n8n instance.
### When to Use
- ✅ Personal projects
- ✅ Single environment (only production or only development)
- ✅ Simple use cases
- ✅ Quick testing and prototyping
### Setup Instructions
#### Option 1: Using .env File (Recommended)
Create a `.env` file in your project root:
```bash
# Create .env file
cat > .env << 'EOF'
# n8n Connection Settings
N8N_HOST=https://your-instance.app.n8n.cloud
N8N_API_KEY=your_api_key_here
# MCP Server Settings (Optional)
MCP_PORT=3456
DEBUG=false
EOF
```
**Configuration Variables:**
| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `N8N_HOST` | ✅ Yes | n8n base URL (without `/api/v1`) | `https://n8n.example.com` |
| `N8N_API_KEY` | ✅ Yes | n8n API key | `n8n_api_abc123...` |
| `MCP_PORT` | ⬜ No | MCP server port (default: 3456) | `3456` or `58921` |
| `DEBUG` | ⬜ No | Enable debug logging (default: false) | `true` or `false` |
**Example .env File:**
```bash
# n8n Cloud Instance
N8N_HOST=https://my-company.app.n8n.cloud
N8N_API_KEY=n8n_api_1234567890abcdefghijklmnopqrstuvwxyz
# Custom port (optional)
MCP_PORT=58921
# Enable debug mode (optional)
DEBUG=true
```
#### Option 2: System Environment Variables
Alternatively, export environment variables in your shell:
```bash
# Export variables (current shell session only)
export N8N_HOST=https://your-instance.app.n8n.cloud
export N8N_API_KEY=your_api_key_here
export MCP_PORT=3456
export DEBUG=false
# Run MCP server
npx @kernel.salacoste/n8n-workflow-builder
```
**Persistent Environment Variables:**
Add to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.):
```bash
# Add to ~/.bashrc or ~/.zshrc
echo 'export N8N_HOST=https://your-instance.app.n8n.cloud' >> ~/.bashrc
echo 'export N8N_API_KEY=your_api_key_here' >> ~/.bashrc
# Reload shell configuration
source ~/.bashrc
```
---
## Multi-Instance Configuration
Use this method to manage multiple n8n environments from a single MCP server.
### When to Use
- ✅ Multiple environments (production, staging, development)
- ✅ Team collaboration with different instances
- ✅ Testing workflows across environments
- ✅ Environment-specific configurations
### Setup Instructions
Create a `.config.json` file in your project root:
```json
{
"environments": {
"production": {
"n8n_host": "https://prod.app.n8n.cloud",
"n8n_api_key": "prod_key_here"
},
"staging": {
"n8n_host": "https://staging.app.n8n.cloud",
"n8n_api_key": "staging_key_here"
},
"development": {
"n8n_host": "http://localhost:5678",
"n8n_api_key": "dev_key_here"
}
},
"defaultEnv": "development"
}
```
### Configuration Structure
**Top-Level Properties:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `environments` | Object | ✅ Yes | Collection of n8n instances |
| `defaultEnv` | String | ✅ Yes | Default environment identifier |
**Environment Properties:**
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `n8n_host` | String | ✅ Yes | n8n base URL |
| `n8n_api_key` | String | ✅ Yes | n8n API key |
### Example Configurations
#### Example 1: Production + Development
```json
{
"environments": {
"production": {
"n8n_host": "https://n8n.mycompany.com",
"n8n_api_key": "n8n_api_prod_xyz789"
},
"development": {
"n8n_host": "http://localhost:5678",
"n8n_api_key": "n8n_api_dev_abc123"
}
},
"defaultEnv": "development"
}
```
#### Example 2: Full Environment Stack
```json
{
"environments": {
"production": {
"n8n_host": "https://prod.n8n.mycompany.com",
"n8n_api_key": "n8n_api_prod_xyz789"
},
"staging": {
"n8n_host": "https://staging.n8n.mycompany.com",
"n8n_api_key": "n8n_api_staging_def456"
},
"qa": {
"n8n_host": "https://qa.n8n.mycompany.com",
"n8n_api_key": "n8n_api_qa_ghi789"
},
"development": {
"n8n_host": "http://localhost:5678",
"n8n_api_key": "n8n_api_dev_abc123"
}
},
"defaultEnv": "development"
}
```
### Using Multi-Instance Configuration
When using Claude AI or Cursor IDE, you can specify which instance to use:
**Default Instance (no parameter):**
```
Create a workflow in my default n8n instance
```
**Specific Instance:**
```
Create a workflow in production instance
List workflows from staging
```
All MCP tools accept an optional `instance` parameter to target specific environments.
---
## Advanced Configuration
### Custom MCP Port
If port 3456 is already in use, specify a different port:
=== ".env File"
```bash
MCP_PORT=58921
```
=== "Environment Variable"
```bash
export MCP_PORT=58921
npx @kernel.salacoste/n8n-workflow-builder
```
=== "Command Line"
```bash
MCP_PORT=58921 npx @kernel.salacoste/n8n-workflow-builder
```
**Recommended Ports:** 49152-65535 (dynamic/private port range)
---
### Debug Mode
Enable detailed logging for troubleshooting:
=== ".env File"
```bash
DEBUG=true
```
=== "Environment Variable"
```bash
DEBUG=true npx @kernel.salacoste/n8n-workflow-builder
```
**Debug Output Example:**
```
[DEBUG] ConfigLoader: Loading configuration...
[DEBUG] ConfigLoader: .config.json found
[DEBUG] ConfigLoader: 3 environments loaded
[DEBUG] EnvironmentManager: Default environment: development
[DEBUG] N8NApiWrapper: Connecting to http://localhost:5678/api/v1
[DEBUG] MCP Server: Listening on port 3456
```
---
## Configuration Validation
After configuring, verify your setup:
### Step 1: Start the MCP Server
```bash
npx @kernel.salacoste/n8n-workflow-builder
```
**Expected Output:**
```
[MCP Server] Starting n8n Workflow Builder MCP Server v0.9.1...
[MCP Server] Configuration loaded: 1 environment(s)
[MCP Server] Default environment: development
[MCP Server] Listening on stdio (MCP Protocol)
[MCP Server] Ready to accept requests
```
### Step 2: Verify Connection (Optional)
If running in HTTP mode, test the health endpoint:
```bash
curl http://localhost:3456/health
```
**Expected Response:**
```json
{
"status": "ok",
"version": "0.9.1",
"timestamp": "2025-12-27T12:00:00.000Z"
}
```
### Step 3: Test with Claude AI
Integrate with Claude Desktop and try a simple command:
```
List my n8n workflows
```
---
## Troubleshooting
### Connection Failed
**Symptom:**
```
Error: connect ECONNREFUSED
```
**Solutions:**
1. **Verify n8n is running:**
```bash
curl https://your-n8n-instance.com
```
2. **Check URL format:**
- ✅ Correct: `https://n8n.example.com`
- ❌ Wrong: `https://n8n.example.com/api/v1`
3. **Test API connectivity:**
```bash
curl -H "X-N8N-API-KEY: your_key" \
https://your-n8n-instance.com/api/v1/workflows
```
---
### Invalid API Key
**Symptom:**
```
Error: 401 Unauthorized
```
**Solutions:**
1. **Regenerate API key** in n8n Settings → API
2. **Check for whitespace** in `.env` or `.config.json`:
```bash
# Wrong (has quotes and whitespace)
N8N_API_KEY=" your_key "
# Correct (no quotes, no whitespace)
N8N_API_KEY=your_key
```
3. **Verify key format** - should start with `n8n_api_`
---
### Wrong Instance Selected
**Symptom:**
```
Workflows from wrong environment appear
```
**Solutions:**
1. **Check `defaultEnv` in `.config.json`**
2. **Explicitly specify instance** in commands:
```
List workflows from production
```
3. **Verify environment names** match your `.config.json`
---
### Configuration Not Loaded
**Symptom:**
```
Error: No configuration found
```
**Solutions:**
1. **Check file location** - must be in project root:
```bash
ls -la .env .config.json
```
2. **Check file permissions:**
```bash
chmod 600 .env .config.json
```
3. **Validate JSON syntax** in `.config.json`:
```bash
cat .config.json | python -m json.tool
```
---
## Security Best Practices
### Protecting API Keys
1. **Never commit credentials** to version control:
```bash
# Add to .gitignore
echo ".env" >> .gitignore
echo ".config.json" >> .gitignore
```
2. **Use separate keys per environment**
3. **Rotate API keys regularly** (every 90 days recommended)
4. **Use password managers** to store keys securely
### File Permissions
Restrict access to configuration files:
```bash
# Make files readable only by owner
chmod 600 .env .config.json
# Verify permissions
ls -la .env .config.json
# Should show: -rw------- (600)
```
### Environment Variables in CI/CD
For CI/CD pipelines, use encrypted secrets:
=== "GitHub Actions"
```yaml
env:
N8N_HOST: ${{ secrets.N8N_HOST }}
N8N_API_KEY: ${{ secrets.N8N_API_KEY }}
```
=== "GitLab CI"
```yaml
variables:
N8N_HOST: ${N8N_HOST}
N8N_API_KEY: ${N8N_API_KEY}
```
---
## Next Steps
After successful configuration:
1. **[Claude Desktop Integration](../quick-start/claude-desktop.md)** - Connect with Claude AI
2. **[First Workflow Tutorial](../quick-start/first-workflow.md)** - Create your first workflow
3. **[Verification & Testing](../quick-start/verification.md)** - Test your setup
---
## Configuration Reference
### Complete .env Example
```bash
# n8n Connection (Required)
N8N_HOST=https://your-instance.app.n8n.cloud
N8N_API_KEY=n8n_api_1234567890abcdefghijklmnopqrstuvwxyz
# MCP Server Settings (Optional)
MCP_PORT=3456
DEBUG=false
# Additional Options (Optional)
# N8N_TIMEOUT=30000
```
### Complete .config.json Example
```json
{
"environments": {
"production": {
"n8n_host": "https://prod.app.n8n.cloud",
"n8n_api_key": "n8n_api_prod_xyz789"
},
"staging": {
"n8n_host": "https://staging.app.n8n.cloud",
"n8n_api_key": "n8n_api_staging_def456"
},
"development": {
"n8n_host": "http://localhost:5678",
"n8n_api_key": "n8n_api_dev_abc123"
}
},
"defaultEnv": "development"
}
```
---
!!! question "Need Help?"
- [Troubleshooting Guide](../../troubleshooting/error-reference.md)
- [GitHub Issues](https://github.com/salacoste/mcp-n8n-workflow-builder/issues)
- [Multi-Instance Documentation](../../multi-instance/configuration.md)
