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

docs: comprehensive documentation update for production deployment

Browse Source 
- Updated README.md with clear setup instructions and recent updates
- Simplified Claude Desktop setup guide with troubleshooting
- Enhanced HTTP deployment guide for production use
- Streamlined troubleshooting guide with quick fixes
- Added mcp-http-client.js for Node.js 16 compatibility
- Fixed stdio mode console output corruption

Key improvements:
- Clear distinction between local and remote deployment
- Node.js 18+ requirement for mcp-remote clearly documented
- USE_FIXED_HTTP=true prominently featured for v2.3.2
- Production deployment best practices
- Multi-user service considerations

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
2025-06-15 01:11:02 +02:00
parent 63ef011aec
commit 149b59a541
6 changed files with 1014 additions and 1117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

649
docs/HTTP_DEPLOYMENT.md
View File

@@ -1,124 +1,112 @@
# HTTP Deployment Guide
# HTTP Deployment Guide for n8n-MCP
This guide explains how to deploy n8n-MCP as a private HTTP server for remote access.
Deploy n8n-MCP as a remote HTTP server to provide n8n knowledge to Claude from anywhere.
## Overview
## 🎯 Overview
The HTTP mode allows you to run n8n-MCP on a remote server and connect to it from Claude Desktop using the mcp-remote adapter. This is designed for single-user private deployments.
n8n-MCP HTTP mode enables:
- ☁️ Cloud deployment (VPS, Docker, Kubernetes)
- 🌐 Remote access from any Claude Desktop client
- 🔒 Token-based authentication
- ⚡ Production-ready performance (~12ms response time)
- 🔧 Fixed implementation (v2.3.2) for stability
## Deployment Options
## 📋 Prerequisites
### Option 1: Docker Deployment (Recommended) 🐳
**Server Requirements:**
- Node.js 16+ or Docker
- 512MB RAM minimum
- Public IP or domain name
- (Recommended) SSL certificate for HTTPS
The easiest way to deploy n8n-MCP is using Docker:
**Client Requirements:**
- Claude Desktop
- Node.js 18+ (for mcp-remote)
- Or Claude Pro/Team (for native remote MCP)
## 🚀 Quick Start
### Option 1: Docker Deployment (Recommended)
#### Quick Start
```bash
# 1. Create configuration
# 1. Create environment file
cat > .env << EOF
AUTH_TOKEN=$(openssl rand -base64 32)
USE_FIXED_HTTP=true
EOF
# 2. Start with Docker Compose
docker compose up -d
# 3. Check health
curl http://localhost:3000/health
```
#### Production Deployment
```bash
# 1. Clone repository
git clone https://github.com/yourusername/n8n-mcp.git
cd n8n-mcp
# 2. Create production .env
cat > .env << EOF
AUTH_TOKEN=$(openssl rand -base64 32)
USE_FIXED_HTTP=true
NODE_ENV=production
LOG_LEVEL=info
MCP_MODE=http
PORT=3000
EOF
# 3. Deploy with Docker Compose
docker compose up -d
# 2. Deploy with Docker
docker run -d \
--name n8n-mcp \
--restart unless-stopped \
--env-file .env \
-p 3000:3000 \
ghcr.io/czlonkowski/n8n-mcp:latest
# 4. Check logs
docker compose logs -f
```
#### Using Pre-built Images
```yaml
# docker-compose.yml
version: '3.8'
services:
n8n-mcp:
image: ghcr.io/czlonkowski/n8n-mcp:latest
environment:
MCP_MODE: http
AUTH_TOKEN: ${AUTH_TOKEN:?Required}
ports:
- "3000:3000"
volumes:
- n8n-mcp-data:/app/data
restart: unless-stopped
volumes:
n8n-mcp-data:
# 3. Verify deployment
curl http://localhost:3000/health
```
### Option 2: Manual Installation
If you prefer not to use Docker:
#### 1. Clone and Build
```bash
git clone https://github.com/yourusername/n8n-mcp.git
# 1. Clone and setup
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
npm run rebuild
# 2. Configure environment
export MCP_MODE=http
export USE_FIXED_HTTP=true # Important: Use fixed implementation
export AUTH_TOKEN=$(openssl rand -base64 32)
export PORT=3000
# 3. Start server
npm run start:http
```
#### 2. Configure Environment
💡 **Save your AUTH_TOKEN** - clients will need it to connect!
## ⚙️ Configuration
### Required Environment Variables
| Variable | Description | Example |
|----------|-------------|------|
| `MCP_MODE` | Must be set to `http` | `http` |
| `USE_FIXED_HTTP` | **Important**: Set to `true` for v2.3.2 fixes | `true` |
| `AUTH_TOKEN` | Secure token (32+ characters) | `generated-token` |
### Optional Settings
| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | `3000` |
| `HOST` | Bind address | `0.0.0.0` |
| `LOG_LEVEL` | Log verbosity | `info` |
| `NODE_ENV` | Environment | `production` |
## 🔐 Security Setup
### Authentication
All requests require Bearer token authentication:
```bash
cp .env.example .env
# Test authentication
curl -H "Authorization: Bearer $AUTH_TOKEN" \
https://your-server.com/health
```
Edit `.env`:
```env
# HTTP mode configuration
MCP_MODE=http
USE_FIXED_HTTP=true # Important: Use the fixed implementation (v2.3.2+)
PORT=3000
HOST=0.0.0.0
### SSL/HTTPS (Strongly Recommended)
# Generate secure token
AUTH_TOKEN=your-secure-token-here
# Other settings
NODE_DB_PATH=./data/nodes.db
MCP_LOG_LEVEL=info
NODE_ENV=production
```
#### 3. Start the Server
```bash
# Using the deployment script
./scripts/deploy-http.sh
# Or manually
MCP_MODE=http npm start
```
The server will start on `http://0.0.0.0:3000`
### 4. Setup HTTPS Proxy (Recommended)
#### Using nginx:
Use a reverse proxy for SSL termination:
**Nginx example:**
```nginx
server {
listen 443 ssl;
@@ -127,56 +115,26 @@ server {
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
location /mcp {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
proxy_set_header Authorization $http_authorization;
}
}
```
#### Using Caddy:
```caddyfile
**Caddy example (automatic HTTPS):**
```caddy
your-domain.com {
reverse_proxy localhost:3000
reverse_proxy /mcp localhost:3000
}
```
## Client Setup
## 💻 Client Configuration
### 1. Install mcp-remote
### For All Claude Desktop Users
```bash
npm install -g mcp-remote
```
**Requirements**: Node.js 18+ installed locally
### 2. Configure Claude Desktop
Edit Claude Desktop config:
**Option 1: Using global mcp-remote installation**
```json
{
"mcpServers": {
"n8n-remote": {
"command": "mcp-remote",
"args": [
"connect",
"https://your-domain.com/mcp"
],
"env": {
"MCP_AUTH_TOKEN": "your-secure-token-here"
}
}
}
}
```
**Option 2: Using npx (no installation required)**
```json
{
"mcpServers": {
@@ -184,213 +142,290 @@ Edit Claude Desktop config:
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/mcp-remote@latest",
"connect",
"https://your-domain.com/mcp"
"mcp-remote",
"https://your-server.com/mcp",
"--header",
"Authorization: Bearer ${AUTH_TOKEN}"
],
"env": {
"MCP_AUTH_TOKEN": "your-secure-token-here"
"AUTH_TOKEN": "your-auth-token-here"
}
}
}
}
```
**Option 3: Using custom headers (if needed)**
```json
{
"mcpServers": {
"n8n-remote": {
"command": "mcp-remote",
"args": [
"connect",
"https://your-domain.com/mcp",
"--header",
"Authorization: Bearer your-secure-token-here"
]
}
}
}
### For Claude Pro/Team Users
Use native remote MCP support:
1. Go to Settings > Integrations
2. Add your MCP server URL
3. Complete OAuth flow (if implemented)
⚠️ **Note**: Direct config file entries won't work for remote servers in Pro/Team.
## 🌐 Production Deployment
### Docker Compose Setup
```yaml
version: '3.8'
services:
n8n-mcp:
image: ghcr.io/czlonkowski/n8n-mcp:latest
container_name: n8n-mcp
restart: unless-stopped
environment:
MCP_MODE: http
USE_FIXED_HTTP: true
AUTH_TOKEN: ${AUTH_TOKEN:?AUTH_TOKEN required}
NODE_ENV: production
LOG_LEVEL: info
ports:
- "127.0.0.1:3000:3000" # Bind to localhost only
volumes:
- n8n-mcp-data:/app/data
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 10s
retries: 3
deploy:
resources:
limits:
memory: 512M
reservations:
memory: 256M
volumes:
n8n-mcp-data:
```
### 3. Test Connection
1. Restart Claude Desktop
2. The MCP tools should be available
3. Test with: "List all n8n nodes"
## Security Considerations
1. **Always use HTTPS** in production
2. **Keep AUTH_TOKEN secret** - treat it like a password
3. **Firewall rules** - Only expose necessary ports
4. **Regular updates** - Keep dependencies updated
5. **Monitor logs** - Check for unauthorized access attempts
## Health Monitoring
Check server health:
```bash
curl https://your-domain.com/health
```
Expected response:
```json
{
"status": "ok",
"mode": "http",
"version": "2.3.0"
}
```
## Testing
Use the included test script to verify your HTTP server:
```bash
# Test local server
./scripts/test-http.sh
# Test remote server
./scripts/test-http.sh https://your-domain.com
# Test with custom token
AUTH_TOKEN=your-token ./scripts/test-http.sh
# Verbose output
VERBOSE=1 ./scripts/test-http.sh
```
The test script checks:
- Health endpoint
- CORS preflight
- Authentication
- Valid MCP requests
- Error handling
- Request size limits
## Troubleshooting
### Docker-specific Issues
#### Container won't start
```bash
# Check logs
docker compose logs n8n-mcp
# Check if port is already in use
lsof -i :3000
# Rebuild and restart
docker compose down
docker compose up -d --build
```
#### Database initialization fails
```bash
# Copy existing database
docker cp data/nodes.db n8n-mcp:/app/data/
# Or rebuild inside container
docker compose exec n8n-mcp npm run rebuild
```
#### Permission issues
```bash
# Fix volume permissions
docker compose exec n8n-mcp chown -R nodejs:nodejs /app/data
```
### General Issues
#### Connection Refused
- Check firewall rules
- Verify server is running
- Check nginx/proxy configuration
- Run the test script to diagnose
- For Docker: ensure ports are mapped correctly
#### Authentication Failed
- Verify AUTH_TOKEN matches in both server and client
- Check Authorization header format
- Token should be at least 32 characters
- Docker: check .env file is loaded
#### MCP Tools Not Available
- Restart Claude Desktop
- Check mcp-remote installation
- Verify server logs for errors
- Ensure CORS headers are working
- Docker: check container health status
## Performance Tips
1. Use a VPS with good network connectivity
2. Enable gzip compression in your proxy
3. For Docker deployments:
- Use `--restart unless-stopped` for reliability
- Monitor with `docker stats n8n-mcp`
- Set memory limits in docker-compose.yml
4. For manual deployments, use PM2:
```bash
pm2 start npm --name "n8n-mcp" -- run start:http
```
## Production Deployment Examples
### Using Docker with Systemd
Create `/etc/systemd/system/n8n-mcp-docker.service`:
```ini
[Unit]
Description=n8n MCP Docker Container
After=docker.service
Requires=docker.service
[Service]
Type=simple
WorkingDirectory=/opt/n8n-mcp
ExecStart=/usr/bin/docker compose up
ExecStop=/usr/bin/docker compose down
Restart=on-failure
[Install]
WantedBy=multi-user.target
```
### Manual Installation with Systemd
### Systemd Service (Linux)
Create `/etc/systemd/system/n8n-mcp.service`:
```ini
[Unit]
Description=n8n MCP HTTP Server
Description=n8n-MCP HTTP Server
After=network.target
[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/n8n-mcp
ExecStart=/usr/bin/npm run start:http
Restart=on-failure
Environment=NODE_ENV=production
User=n8n-mcp
WorkingDirectory=/opt/n8n-mcp
ExecStart=/usr/bin/node dist/mcp/index.js
Restart=always
RestartSec=10
# Environment
Environment="MCP_MODE=http"
Environment="USE_FIXED_HTTP=true"
Environment="NODE_ENV=production"
EnvironmentFile=/opt/n8n-mcp/.env
# Security
NoNewPrivileges=true
PrivateTmp=true
[Install]
WantedBy=multi-user.target
```
Enable and start:
Enable:
```bash
sudo systemctl enable n8n-mcp
sudo systemctl start n8n-mcp
```
## Limitations
## 📡 Monitoring & Maintenance
- Single-user design (no multi-tenancy)
- Stateless (no session persistence)
- No built-in rate limiting
- Basic token authentication only
### Health Checks
For multi-user deployments, consider implementing a proper API gateway with user management.
```bash
# Basic health check
curl https://your-server.com/health
# Response:
{
"status": "ok",
"mode": "http-fixed",
"version": "2.3.2",
"uptime": 3600,
"memory": {
"used": 45,
"total": 512,
"unit": "MB"
}
}
```
### Monitoring with Prometheus
```yaml
# prometheus.yml
scrape_configs:
- job_name: 'n8n-mcp'
static_configs:
- targets: ['localhost:3000']
metrics_path: '/health'
bearer_token: 'your-auth-token'
```
### Log Management
```bash
# Docker logs
docker logs -f n8n-mcp --tail 100
# Systemd logs
journalctl -u n8n-mcp -f
# Log rotation (Docker)
docker run -d \
--log-driver json-file \
--log-opt max-size=10m \
--log-opt max-file=3 \
n8n-mcp
```
## 🔒 Security Best Practices
### 1. Token Management
```bash
# Generate strong tokens
openssl rand -base64 32
# Rotate tokens regularly
AUTH_TOKEN_NEW=$(openssl rand -base64 32)
docker exec n8n-mcp env AUTH_TOKEN=$AUTH_TOKEN_NEW
```
### 2. Network Security
- ✅ **Always use HTTPS** in production
- ✅ **Firewall rules** to limit access
- ✅ **VPN** for internal deployments
- ✅ **Rate limiting** at proxy level
### 3. Container Security
```bash
# Run as non-root user (already configured)
# Read-only filesystem
docker run --read-only \
--tmpfs /tmp \
-v n8n-mcp-data:/app/data \
n8n-mcp
# Security scanning
docker scan ghcr.io/czlonkowski/n8n-mcp:latest
```
## 🔍 Troubleshooting
### Common Issues
**"Stream is not readable" error:**
- ✅ Solution: Ensure `USE_FIXED_HTTP=true` is set
- This is fixed in v2.3.2
**"TransformStream is not defined" (client-side):**
- 🔄 Update Node.js to v18+ on client machine
- Or use Docker stdio mode instead
**Connection refused:**
```bash
# Check server is running
curl http://localhost:3000/health
# Check Docker status
docker ps
docker logs n8n-mcp
# Check firewall
sudo ufw status
```
**Authentication failed:**
- Verify AUTH_TOKEN matches exactly
- Check for extra spaces or quotes
- Test with curl first
### Debug Mode
```bash
# Enable debug logging
LOG_LEVEL=debug docker run ...
# Test MCP endpoint directly
curl -X POST https://your-server.com/mcp \
-H "Authorization: Bearer $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"list_nodes","params":{"limit":5},"id":1}'
```
## 🚀 Scaling & Performance
### Performance Metrics
- Average response time: **~12ms**
- Memory usage: **~50-100MB**
- Concurrent connections: **100+**
- Database queries: **<5ms** with FTS5
### Horizontal Scaling
The server is stateless - scale easily:
```yaml
# Docker Swarm example
deploy:
replicas: 3
update_config:
parallelism: 1
delay: 10s
restart_policy:
condition: on-failure
```
### Optimization Tips
1. **Use Docker** for consistent performance
2. **Enable HTTP/2** in your reverse proxy
3. **Set up CDN** for static assets
4. **Monitor memory** usage over time
## 👥 Multi-User Service Considerations
While n8n-MCP is designed for single-user deployments, you can build a multi-user service:
1. **Use this as a core engine** with your own auth layer
2. **Deploy multiple instances** with different tokens
3. **Add user management** in your proxy layer
4. **Implement rate limiting** per user
See [Architecture Guide](./ARCHITECTURE.md) for building multi-user services.
## 📦 Updates & Maintenance
```bash
# Update to latest version
docker pull ghcr.io/czlonkowski/n8n-mcp:latest
docker compose up -d
# Backup database
docker cp n8n-mcp:/app/data/nodes.db ./backup-$(date +%Y%m%d).db
# Restore database
docker cp ./backup.db n8n-mcp:/app/data/nodes.db
docker restart n8n-mcp
```
## 🆘 Getting Help
- 📚 [Full Documentation](https://github.com/czlonkowski/n8n-mcp)
- 🐛 [Report Issues](https://github.com/czlonkowski/n8n-mcp/issues)
- 💬 [Discussions](https://github.com/czlonkowski/n8n-mcp/discussions)

236
docs/README_CLAUDE_SETUP.md
View File

@@ -1,57 +1,26 @@
# Claude Desktop Configuration for n8n-MCP
## Setup Options
This guide helps you connect n8n-MCP to Claude Desktop, giving Claude comprehensive knowledge about n8n's 450+ workflow automation nodes.
You can set up n8n-MCP with Claude Desktop in three ways:
## 🎯 Prerequisites
### Option 1: Docker (Recommended) 🐳
- Claude Desktop installed
- For remote connections: Node.js 18+ on your local machine
- For Docker: Docker Desktop or Docker Engine
The easiest way to get started is using Docker:
## 🛠️ Configuration Methods
#### 1a. Docker with HTTP Mode (Remote Access)
```json
{
"mcpServers": {
"n8n-remote": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/mcp-remote@latest",
"connect",
"http://localhost:3000/mcp"
],
"env": {
"MCP_AUTH_TOKEN": "your-auth-token-here"
}
}
}
}
```
### Method 1: Docker (Simplest) 🐳
**Setup steps:**
1. Create a `.env` file:
```bash
cat > .env << EOF
AUTH_TOKEN=$(openssl rand -base64 32)
USE_FIXED_HTTP=true
EOF
```
2. Start the server:
```bash
docker compose up -d
```
3. Copy the AUTH_TOKEN to your Claude config
No installation needed - runs directly from Docker:
#### 1b. Docker with stdio Mode (Direct)
```json
{
"mcpServers": {
"n8n-docker": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"run", "--rm", "-i",
"-e", "MCP_MODE=stdio",
"-v", "n8n-mcp-data:/app/data",
"ghcr.io/czlonkowski/n8n-mcp:latest"
@@ -61,25 +30,26 @@ The easiest way to get started is using Docker:
}
```
### Option 2: Local Installation
✨ **Benefits**: No setup required, always up-to-date, isolated environment.
1. **Build the project first:**
### Method 2: Local Installation
1. **Install and build:**
```bash
cd /path/to/n8n-mcp
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
npm run rebuild
```
2. **Add to Claude Desktop config:**
2. **Configure Claude Desktop:**
```json
{
"mcpServers": {
"n8n-documentation": {
"command": "node",
"args": [
"/path/to/n8n-mcp/dist/mcp/index.js"
],
"args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"],
"env": {
"NODE_ENV": "production"
}
@@ -88,119 +58,117 @@ The easiest way to get started is using Docker:
}
```
### Option 3: NPM Global Install (Coming Soon)
⚠️ **Important**: Use absolute paths, not relative paths.
### Method 3: Remote Server Connection
**Requirements**: Node.js 18+ installed locally
```json
{
"mcpServers": {
"n8n-documentation": {
"n8n-remote": {
"command": "npx",
"args": [
"-y",
"n8n-mcp@latest"
]
"mcp-remote",
"https://your-server.com/mcp",
"--header",
"Authorization: Bearer ${AUTH_TOKEN}"
],
"env": {
"AUTH_TOKEN": "your-auth-token"
}
}
}
}
```
## Configuration File Locations
📝 **Note**: Remote MCP is also natively supported in Claude Pro/Team/Enterprise via Settings > Integrations.
## 📁 Configuration File Locations
Find your `claude_desktop_config.json` file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
After updating the config, **restart Claude Desktop** to load the new configuration.
🔄 **Important**: After editing, restart Claude Desktop (Cmd/Ctrl+R or quit and reopen).
## Available Tools
## ✅ Verify Installation
Once configured, you'll have access to these tools in Claude:
After restarting Claude Desktop:
- **`list_nodes`** - List and filter n8n nodes
```
list_nodes({ package: "n8n-nodes-base", limit: 10 })
1. Look for "n8n-docker" or "n8n-documentation" in the MCP servers list
2. Try asking Claude: "What n8n nodes are available for working with Slack?"
3. Or use a tool directly: "Use the list_nodes tool to show me trigger nodes"
## 🔧 Available Tools
Once connected, you can ask Claude to:
- **List nodes**: "Show me all n8n nodes for working with databases"
- **Get node details**: "How do I use the HTTP Request node?"
- **Search documentation**: "Find n8n nodes that support OAuth"
- **Find AI tools**: "What AI-capable nodes are available?"
- **View statistics**: "Show me n8n-MCP database statistics"
Claude will automatically use the appropriate tools:
- `list_nodes` - Filter and list nodes
- `get_node_info` - Get detailed node information
- `search_nodes` - Full-text search
- `list_ai_tools` - Find AI-capable nodes
- `get_node_documentation` - Get official docs
- `get_database_statistics` - View coverage metrics
## 🔍 Troubleshooting
### Server Not Appearing in Claude
1. **Check JSON syntax**:
```bash
# Validate your config file
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .
```
2. **Verify paths are absolute** (not relative)
3. **Restart Claude Desktop completely** (quit and reopen)
### Remote Connection Issues
**"TransformStream is not defined" error:**
- Cause: Node.js version < 18
- Fix: Update Node.js to v18 or newer
```bash
node --version # Should be v18.0.0 or higher
```
- **`get_node_info`** - Get detailed information about a specific node
```
get_node_info({ nodeType: "httpRequest" })
```
- **`search_nodes`** - Search across all node documentation
```
search_nodes({ query: "webhook", limit: 20 })
```
- **`list_ai_tools`** - List nodes that can be used as AI Agent tools
```
list_ai_tools({})
```
- **`get_node_documentation`** - Get full documentation for a node
```
get_node_documentation({ nodeType: "slack" })
```
- **`get_database_statistics`** - Get statistics about the node database
```
get_database_statistics({})
```
## Troubleshooting
**"Server disconnected" error:**
- Check AUTH_TOKEN matches between server and client
- Verify server is running: `curl https://your-server.com/health`
- Check for VPN interference
### Docker Issues
1. **Container fails to start:**
```bash
# Check logs
docker compose logs -f
# Check if port is in use
lsof -i :3000
```
**"Cannot find image" error:**
```bash
# Pull the latest image
docker pull ghcr.io/czlonkowski/n8n-mcp:latest
```
2. **Authentication errors:**
- Ensure AUTH_TOKEN matches in .env and Claude config
- Token should be at least 32 characters
- Check quotes in JSON config
**Permission denied:**
```bash
# Ensure Docker is running
docker ps
```
3. **Database not found:**
- The container will auto-initialize on first run
- To rebuild: `docker compose exec n8n-mcp npm run rebuild`
### Quick Fixes
### Local Installation Issues
- 🔄 **Always restart Claude** after config changes
- 📋 **Copy example configs exactly** (watch for typos)
- 📂 **Use absolute paths** (/Users/... not ~/...)
- 🔍 **Check logs**: View > Developer > Logs in Claude Desktop
1. **If the server doesn't appear in Claude:**
- Check that the path in `args` is absolute and correct
- Ensure you've run `npm run build` and `npm run rebuild`
- Verify Node.js version compatibility
2. **If tools return errors:**
- Ensure the database exists: `data/nodes.db`
- Run `npm run validate` to check the database
- Rebuild if necessary: `npm run rebuild`
3. **For development/testing:**
```json
{
"mcpServers": {
"n8n-documentation": {
"command": "node",
"args": [
"/path/to/your/n8n-mcp/dist/mcp/index.js"
],
"env": {
"NODE_ENV": "development",
"LOG_LEVEL": "debug"
}
}
}
}
```
### Common Solutions
- **Restart Claude Desktop** after config changes
- **Check file permissions** on Unix systems
- **Use absolute paths** in configuration
- **Verify JSON syntax** in claude_desktop_config.json
For more help, see [Troubleshooting Guide](./TROUBLESHOOTING.md)

608
docs/TROUBLESHOOTING.md
View File

@@ -1,470 +1,262 @@
# Troubleshooting Guide
This guide helps resolve common issues with n8n-MCP.
Quick solutions for common n8n-MCP issues.
## Table of Contents
## 🎯 Quick Fixes
- [HTTP Server Issues](#http-server-issues)
- [Docker Issues](#docker-issues)
- [Installation Issues](#installation-issues)
- [Runtime Errors](#runtime-errors)
- [Claude Desktop Issues](#claude-desktop-issues)
- [Database Problems](#database-problems)
- [Network and Authentication](#network-and-authentication)
- [Performance Issues](#performance-issues)
| Issue | Solution |
|-------|----------|
| "Stream is not readable" | Set `USE_FIXED_HTTP=true` (fixed in v2.3.2) |
| "TransformStream is not defined" | Update to Node.js 18+ on client |
| Server not appearing in Claude | Restart Claude Desktop completely |
| Authentication failed | Check AUTH_TOKEN matches exactly |
| Database not found | Run `npm run rebuild` or `docker compose exec n8n-mcp npm run rebuild` |
## HTTP Server Issues
## 🌐 HTTP Server Issues
### "Stream is not readable" Error
#### Symptoms
- Error: `InternalServerError: stream is not readable`
- HTTP 400 Bad Request responses
- Server works locally but fails in HTTP mode
#### Solution (v2.3.2+)
This issue has been fixed in v2.3.2. Ensure you're using the fixed implementation:
**✅ Fixed in v2.3.2** - Set `USE_FIXED_HTTP=true`
```bash
# Set the environment variable
export USE_FIXED_HTTP=true
# Docker
docker run -e USE_FIXED_HTTP=true ...
# Or in your .env file
USE_FIXED_HTTP=true
# Local
export USE_FIXED_HTTP=true
npm run start:http
```
#### Technical Details
- **Cause**: Express.json() middleware was consuming the request stream
- **Fix**: Removed body parsing middleware for MCP endpoints
- **See**: [HTTP Server Fix Documentation](./HTTP_SERVER_FINAL_FIX.md)
### "TransformStream is not defined" (Client)
### "Server not initialized" Error
#### Symptoms
- Error: `Bad Request: Server not initialized`
- Error code: -32000
- Occurs when using StreamableHTTPServerTransport
#### Solution
Use the fixed HTTP implementation (v2.3.2+):
**Cause**: Node.js < 18 on client machine
**Fix**: Update Node.js
```bash
# Use the fixed server
MCP_MODE=http USE_FIXED_HTTP=true npm start
# Check version
node --version # Must be v18.0.0+
# Or with Docker
docker run -e MCP_MODE=http -e USE_FIXED_HTTP=true ...
# Update via nvm
nvm install 18
nvm use 18
```
### Authentication Failed
#### Symptoms
- 401 Unauthorized responses
- "Authentication failed" in logs
#### Solutions
1. **Check AUTH_TOKEN format:**
**Check these:**
1. Token length: `echo -n "$AUTH_TOKEN" | wc -c` (32+ chars)
2. No extra quotes in .env file
3. Exact match between server and client
4. Test with curl:
```bash
# Should be at least 32 characters
echo -n "$AUTH_TOKEN" | wc -c
curl -H "Authorization: Bearer $AUTH_TOKEN" \
http://localhost:3000/health
```
2. **Verify token in requests:**
```bash
curl -H "Authorization: Bearer $AUTH_TOKEN" ...
```
3. **Check .env file:**
```bash
# No quotes needed in .env
AUTH_TOKEN=your-token-here
```
## Docker Issues
## 🐳 Docker Issues
### Container Won't Start
#### Symptoms
- `docker compose up` fails
- Container exits immediately
- No logs available
#### Solutions
1. **Check if port is in use:**
```bash
lsof -i :3000
# or
netstat -tulpn | grep 3000
```
2. **View detailed logs:**
```bash
docker compose logs -f --tail 100
```
3. **Check Docker resources:**
```bash
docker system df
docker system prune -a # Clean up unused resources
```
4. **Verify image download:**
```bash
docker compose pull
```
### Database Initialization Fails in Docker
#### Symptoms
- Error: `ENOENT: no such file or directory, open '/app/src/database/schema.sql'`
- Database not found errors
#### Solutions
1. **Rebuild the image with latest Dockerfile:**
```bash
docker compose build --no-cache
docker compose up -d
```
2. **Copy existing database:**
```bash
# From host to container
docker cp data/nodes.db n8n-mcp:/app/data/
# Restart container
docker compose restart
```
3. **Initialize inside container:**
```bash
docker compose exec n8n-mcp npm run rebuild
```
### Permission Denied in Docker
#### Symptoms
- Cannot write to /app/data
- Permission denied errors in logs
#### Solutions
```bash
# Fix permissions
docker compose exec n8n-mcp chown -R nodejs:nodejs /app/data
# 1. Check port availability
lsof -i :3000
# Or run as root temporarily
docker compose exec -u root n8n-mcp chown -R nodejs:nodejs /app
# 2. View logs
docker compose logs -f
# 3. Clean and retry
docker compose down
docker system prune -f
docker compose up -d
```
### Docker Compose Variables Not Loading
#### Symptoms
- AUTH_TOKEN not recognized
- Environment variables missing
#### Solutions
1. **Check .env file location:**
```bash
ls -la .env
cat .env
```
2. **Verify compose file:**
```bash
docker compose config
```
3. **Set variables explicitly:**
```bash
AUTH_TOKEN=mytoken docker compose up -d
```
## Installation Issues
### npm install Fails
#### Symptoms
- Dependency errors
- Node version mismatch
- Native module compilation fails
#### Solutions
1. **Clear npm cache:**
```bash
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
```
2. **Check Node version:**
```bash
node --version # Should be v16+
npm --version # Should be v7+
```
3. **Use fallback for better-sqlite3:**
The project automatically falls back to sql.js if native modules fail.
### Build Errors
#### Symptoms
- TypeScript compilation errors
- Missing type definitions
#### Solutions
### Database Issues
```bash
# Clean build
rm -rf dist
npm run build
# Rebuild database inside container
docker compose exec n8n-mcp npm run rebuild
# Check TypeScript version
npx tsc --version
# Install missing types
npm install --save-dev @types/node
```
## Runtime Errors
### MCP Tools Not Available
#### Symptoms
- Tools don't appear in Claude Desktop
- "Unknown tool" errors
#### Solutions
1. **Verify server is running:**
```bash
# For Docker
docker compose ps
docker compose logs
# For local
ps aux | grep node
```
2. **Check database:**
```bash
npm run validate
npm run test-nodes
```
3. **Restart Claude Desktop** after configuration changes
### Stream Not Readable Error
#### Symptoms
- Error: "InternalServerError: stream is not readable"
- MCP endpoint returns errors
#### Solutions
1. **Check database initialization:**
```bash
ls -la data/nodes.db
npm run validate
```
2. **Verify HTTP headers:**
```bash
curl -H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $AUTH_TOKEN" \
http://localhost:3000/mcp
```
## Claude Desktop Issues
### Server Not Appearing
#### Solutions
1. **Verify config file location:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
2. **Check JSON syntax:**
```bash
# Validate JSON
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .
```
3. **Use absolute paths:**
```json
{
"mcpServers": {
"n8n-documentation": {
"command": "node",
"args": [
"/absolute/path/to/n8n-mcp/dist/mcp/index.js"
]
}
}
}
```
### Authentication Errors with Claude
#### Solutions
1. **Match tokens exactly:**
```bash
# In .env
AUTH_TOKEN=your-token-here
# In Claude config
"MCP_AUTH_TOKEN": "your-token-here"
```
2. **Check for special characters:**
- Avoid quotes in token values
- Use base64 encoding for safety
## Database Problems
### Database Corruption
#### Symptoms
- SQLite errors
- Unexpected results
- Missing nodes
#### Solutions
1. **Rebuild database:**
```bash
# Backup first
cp data/nodes.db data/nodes.db.bak
# Rebuild
npm run rebuild
```
2. **Validate after rebuild:**
```bash
npm run validate
npm run test-nodes
```
### Database Locked
#### Symptoms
- SQLITE_BUSY errors
- Cannot write to database
#### Solutions
```bash
# Find processes using the database
lsof data/nodes.db
# For Docker
# Or copy from host
docker cp data/nodes.db n8n-mcp:/app/data/
docker compose restart
```
## Network and Authentication
### Environment Variables Not Loading
### CORS Errors
```bash
# Verify .env file
cat .env
#### Symptoms
- Browser console shows CORS errors
- Preflight requests fail
# Check loaded config
docker compose config
#### Solutions
# Force reload
docker compose down
docker compose --env-file .env up -d
```
1. **Check server CORS settings:**
- Verify MCP_MODE=http
- Check proxy configuration
## 📦 Installation Issues
2. **Test with curl:**
### npm install Fails
```bash
# Clean install
rm -rf node_modules package-lock.json
npm cache clean --force
npm install
```
**Note**: The project automatically falls back to sql.js if better-sqlite3 fails.
### Build Errors
```bash
# Clean rebuild
rm -rf dist
npm run build
# If TypeScript errors
npm install --save-dev @types/node
npm run typecheck
```
## ⚡ Runtime Errors
### MCP Tools Not Available in Claude
1. **Restart Claude Desktop** (Cmd/Ctrl+R)
2. **Check server status:**
```bash
curl -X OPTIONS http://localhost:3000/mcp \
-H "Origin: http://localhost" \
-H "Access-Control-Request-Method: POST"
# Docker
docker compose ps
# Local
curl http://localhost:3000/health
```
3. **Verify configuration path** is absolute
4. **Check Claude logs**: View > Developer > Logs
### SSL/HTTPS Issues
## 🖥️ Claude Desktop Issues
#### Solutions
### Server Not Appearing
1. **For development, use HTTP:**
```json
"connect", "http://localhost:3000/mcp"
```
**Checklist:**
- ✅ Used absolute paths (not ~/)
- ✅ Valid JSON syntax
- ✅ Restarted Claude completely
- ✅ Server is running
2. **For production, use reverse proxy:**
- See nginx/Caddy examples in HTTP_DEPLOYMENT.md
```bash
# Validate config
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .
```
## Performance Issues
### Remote Connection Issues
**"TransformStream is not defined":**
- Update to Node.js 18+
- Or use Docker stdio mode instead
**"Server disconnected":**
- Check AUTH_TOKEN matches
- Verify server is accessible
- Check for VPN interference
## 🗄️ Database Problems
### Quick Fixes
```bash
# Rebuild database
npm run rebuild
# Validate
npm run validate
npm run test-nodes
# For Docker
docker compose exec n8n-mcp npm run rebuild
```
### Database Locked
```bash
# Find lock
lsof data/nodes.db
# Force restart
killall node
npm start
```
## 🌐 Network Issues
### Connection Refused
```bash
# Check server
curl http://localhost:3000/health
# Check firewall
sudo ufw status
# Test from outside
curl https://your-server.com/health
```
### SSL Certificate Issues
- Use HTTP for local development
- Use reverse proxy (nginx/Caddy) for HTTPS
- See [HTTP Deployment Guide](./HTTP_DEPLOYMENT.md)
## 🚀 Performance Issues
### Slow Response Times
#### Solutions
```bash
# Check memory
docker stats n8n-mcp
1. **Check resource usage:**
```bash
# Docker
docker stats n8n-mcp
# System
top
htop
```
# Increase limits
# docker-compose.yml
deploy:
resources:
limits:
memory: 1G
```
2. **Increase memory limits:**
```yaml
# docker-compose.yml
deploy:
resources:
limits:
memory: 1G
```
**Expected performance:**
- Response time: ~12ms
- Memory usage: 50-100MB
- Database queries: <5ms
3. **Enable query logging:**
```bash
LOG_LEVEL=debug npm start
```
## 🆘 Still Need Help?
### High Memory Usage
### Debug Mode
#### Solutions
```bash
# Enable verbose logging
LOG_LEVEL=debug npm start
1. **Monitor with Docker:**
```bash
docker compose exec n8n-mcp ps aux
```
# Docker debug
docker compose logs -f --tail 100
```
2. **Restart periodically:**
```bash
# Add to crontab
0 */6 * * * docker compose restart
```
### Get Support
## Getting More Help
1. **Check existing issues**: [GitHub Issues](https://github.com/czlonkowski/n8n-mcp/issues)
2. **Ask questions**: [GitHub Discussions](https://github.com/czlonkowski/n8n-mcp/discussions)
3. **Report bugs**: Include:
- Error messages
- Steps to reproduce
- Environment details
- Logs with `LOG_LEVEL=debug`
1. **Enable debug logging:**
```bash
LOG_LEVEL=debug docker compose up
```
### Common Solutions Summary
2. **Collect diagnostic info:**
```bash
# System info
uname -a
node --version
docker --version
# Project info
git rev-parse HEAD
npm list
```
3. **Report issues:**
- GitHub: https://github.com/czlonkowski/n8n-mcp/issues
- Include logs, environment, and steps to reproduce
1. 🔄 **Always restart Claude** after config changes
2. 📋 **Use exact configuration** from examples
3. 🔍 **Check logs** for specific errors
4. 🆙 **Update Node.js** to v18+ for remote connections
5. 🔒 **Verify AUTH_TOKEN** matches exactly