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

docs: reorganize documentation files and update Docker build process

Browse Source
This commit is contained in:
czlonkowski
2025-06-13 17:20:31 +02:00
parent 12bef3d98e
commit d6f38dc1c4
18 changed files with 1201 additions and 2480 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
docs/CHANGELOG.md Normal file
View File

@@ -0,0 +1,176 @@
# Changelog
All notable changes to this project will be documented in this file.
## [2.3.0] - 2024-12-06
### Added
- **HTTP Remote Deployment**: Single-user HTTP server for remote access
- Stateless architecture for simple deployments
- Bearer token authentication
- Compatible with mcp-remote adapter for Claude Desktop
- New HTTP mode scripts and deployment helper
- **Universal Node.js Compatibility**: Automatic database adapter fallback system
- Primary adapter: `better-sqlite3` for optimal performance
- Fallback adapter: `sql.js` (pure JavaScript) for version mismatches
- Automatic detection and switching between adapters
- No manual configuration required
- Database adapter abstraction layer (`src/database/database-adapter.ts`)
- Version detection and logging for troubleshooting
- sql.js dependency for pure JavaScript SQLite implementation
- HTTP server implementation (`src/http-server.ts`)
- Deployment documentation and scripts
### Changed
- Updated all database operations to use the adapter interface
- Removed Node.js v20.17.0 requirement - now works with ANY version
- Simplified Claude Desktop setup - no wrapper scripts needed
- Enhanced error messages for database initialization
- Made all MCP tool handlers async for proper initialization
### Fixed
- NODE_MODULE_VERSION mismatch errors with Claude Desktop
- Native module compilation issues in restricted environments
- Compatibility issues when running with different Node.js versions
- Database initialization race conditions in HTTP mode
### Technical Details
- Better-sqlite3: ~10-50x faster (when compatible)
- sql.js: ~2-5x slower but universally compatible
- Both adapters maintain identical API and functionality
- Automatic persistence for sql.js with 100ms debounced saves
- HTTP server uses StreamableHTTPServerTransport for MCP compatibility
## [2.2.0] - 2024-12-06
### Added
- PropertyExtractor class for dedicated property/operation extraction
- NodeRepository for proper JSON serialization/deserialization
- Support for @n8n/n8n-nodes-langchain package (59 AI nodes)
- AI tool detection (35 tools with usableAsTool property)
- Test suite for critical node validation
- Comprehensive documentation (README, SETUP, CHANGELOG)
- Example configuration files for Claude Desktop
- Node.js v20.17.0 wrapper scripts for compatibility
### Fixed
- Empty properties/operations arrays (now 98.7% nodes have properties)
- Versioned node detection (HTTPRequest, Code properly identified)
- Documentation mapping for nodes with directory-based docs
- Critical node validation (httpRequest, slack, code all pass)
### Changed
- Refactored parser to handle instance-level properties
- Updated MCP server to use NodeRepository
- Improved rebuild script with validation
- Enhanced database schema with proper typing
### Metrics
- 458 total nodes (100% success rate)
- 452 nodes with properties (98.7%)
- 265 nodes with operations (57.9%)
- 406 nodes with documentation (88.6%)
- 35 AI-capable tools detected
- All critical nodes validated
## [2.1.0] - 2025-01-08
### Added
- Remote deployment capabilities via HTTP/JSON-RPC transport
- Domain configuration through environment variables (`MCP_DOMAIN`)
- Bearer token authentication for remote access
- Comprehensive remote deployment documentation
- PM2 and Nginx configuration examples
- HTTP server mode (`npm run start:http`)
### Enhanced
- Support for both local (stdio) and remote (HTTP) deployment modes
- Production deployment guide for VM/cloud environments
- Claude Desktop configuration for remote servers
## [2.0.0] - 2025-01-08
### Major Refactoring
- **BREAKING CHANGE**: Refocused project to serve only n8n node documentation
- Removed all workflow execution and management features
- Removed bidirectional n8n-MCP integration
- Simplified to be a read-only documentation server
### Added
- SQLite database with full-text search (FTS5) for node documentation
- Integration with n8n-docs repository for official documentation
- Automatic example workflow generation for each node type
- Comprehensive node information including:
- Source code
- Official documentation
- Usage examples
- Properties schema
- Credential definitions
### New MCP Tools
- `list_nodes` - List available nodes with filtering
- `get_node_info` - Get complete node information
- `search_nodes` - Full-text search across nodes
- `get_node_example` - Get example workflow for a node
- `get_node_source_code` - Get only source code
- `get_node_documentation` - Get only documentation
- `rebuild_database` - Rebuild entire node database
- `get_database_statistics` - Database statistics
### Infrastructure
- New database schema optimized for documentation storage
- `DocumentationFetcher` for n8n-docs repository integration
- `ExampleGenerator` for creating node usage examples
- `NodeDocumentationService` for database management
## [1.1.0] - 2024-01-07
### Added
- Node source code extraction capability via `get_node_source_code` tool
- List available nodes functionality with `list_available_nodes` tool
- `NodeSourceExtractor` utility for file system access to n8n nodes
- Resource endpoint `nodes://source/{nodeType}` for accessing node source code
- Docker test environment with mounted n8n node_modules
- Comprehensive test suite for AI Agent node extraction
- Test documentation in `docs/AI_AGENT_EXTRACTION_TEST.md`
### Enhanced
- MCP server can now access and extract n8n node implementations
- Support for extracting credential definitions alongside node code
- Package metadata included in extraction results
## [1.0.0] - 2024-01-07
### Initial Release
- Complete n8n-MCP integration implementation
- MCP server exposing n8n workflows as tools, resources, and prompts
- Custom n8n node for connecting to MCP servers
- Bidirectional data format conversion bridge
- Token-based authentication system
- Comprehensive error handling and logging
- Full test coverage for core components
- Docker support with production and development configurations
- Installation scripts for n8n custom node deployment
### MCP Tools
- `execute_workflow` - Execute n8n workflows
- `list_workflows` - List available workflows
- `get_workflow` - Get workflow details
- `create_workflow` - Create new workflows
- `update_workflow` - Update existing workflows
- `delete_workflow` - Delete workflows
- `get_executions` - Get execution history
- `get_execution_data` - Get execution details
### MCP Resources
- `workflow://active` - Active workflows
- `workflow://all` - All workflows
- `execution://recent` - Recent executions
- `credentials://types` - Credential types
- `nodes://available` - Available nodes
### MCP Prompts
- `create_workflow_prompt` - Workflow creation
- `debug_workflow_prompt` - Workflow debugging
- `optimize_workflow_prompt` - Workflow optimization
- `explain_workflow_prompt` - Workflow explanation

62
docs/DOCKER_BUILD_FIX.md Normal file
View File

@@ -0,0 +1,62 @@
# Docker Build Fix
## Issue
The Docker build was failing with the error:
```
ERROR: failed to solve: failed to compute cache key: failed to calculate checksum of ref: "/data/nodes.db": not found
```
## Root Cause
The Dockerfile contained an invalid COPY command that tried to use shell operators:
```dockerfile
# This doesn't work in Docker
COPY --from=builder /app/data/nodes.db ./data/nodes.db 2>/dev/null || true
```
Docker's COPY command doesn't support shell operators like `2>/dev/null || true`.
## Solution
1. Removed the problematic COPY command
2. Created the data directory with RUN instead
3. Removed database pre-initialization from build stage
4. Database is now initialized at runtime by the entrypoint script
## Changes Made
### Dockerfile
```diff
- # Pre-initialize database during build
- RUN mkdir -p /app/data && npm run rebuild || echo "Database will be initialized at runtime"
+ # Build TypeScript only
+ RUN npm run build
- # Copy pre-built database if it exists
- COPY --from=builder /app/data/nodes.db ./data/nodes.db 2>/dev/null || true
+ # Create data directory
+ RUN mkdir -p /app/data
```
### GitHub Actions Workflow
Added conditional login to prevent failures on pull requests:
```diff
- name: Log in to GitHub Container Registry
+ if: github.event_name != 'pull_request'
uses: docker/login-action@v3
```
## Result
✅ Docker build now succeeds
✅ Database initialization happens at container startup
✅ GitHub Actions workflow will work properly
✅ No manual intervention required
## Testing
```bash
# Build locally
docker build -t n8n-mcp:test .
# Run and verify
docker run -d --name test -e MCP_MODE=http -e AUTH_TOKEN=test -p 3000:3000 n8n-mcp:test
docker logs test
curl http://localhost:3000/health
```

325
docs/DOCKER_README.md Normal file
View File

@@ -0,0 +1,325 @@
# Docker Deployment Guide for n8n-MCP
This guide provides comprehensive instructions for deploying n8n-MCP using Docker.
## Table of Contents
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Deployment Options](#deployment-options)
- [Development Setup](#development-setup)
- [Production Deployment](#production-deployment)
- [Troubleshooting](#troubleshooting)
## Quick Start
### Using Pre-built Images
The fastest way to get started is using our pre-built Docker images from GitHub Container Registry:
```bash
# 1. Create a .env file with your authentication token
echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
# 2. Start the container
docker compose up -d
# 3. Check it's running
docker compose ps
docker compose logs
```
### Building Locally
To build the image yourself:
```bash
# Build the image
docker build -t n8n-mcp:local .
# Run with docker compose (update image in docker-compose.yml first)
docker compose up -d
```
## Configuration
### Environment Variables
Create a `.env` file in the project root:
```bash
# Required for HTTP mode
AUTH_TOKEN=your-secure-token-here
# Server configuration
PORT=3000
NODE_ENV=production
LOG_LEVEL=info
# MCP mode (stdio or http)
MCP_MODE=http
# Database
NODE_DB_PATH=/app/data/nodes.db
REBUILD_ON_START=false
```
### Docker Compose Options
The project includes several Docker Compose configurations:
- `docker-compose.yml` - Production HTTP server
- `docker-compose.override.yml.example` - Development overrides template
- `docker-compose.nginx.yml` - HTTPS with nginx (Phase 2)
## Deployment Options
### Option 1: HTTP Server Mode
Best for remote access and integration with Claude Desktop via mcp-remote:
```bash
# Start the server
docker compose up -d
# Test the health endpoint
curl http://localhost:3000/health
# Test with authentication
curl -H "Authorization: Bearer $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
http://localhost:3000/mcp
```
Configure Claude Desktop:
```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"
}
}
}
}
```
### Option 2: stdio Mode (Direct)
For local-only usage without network exposure:
```json
{
"mcpServers": {
"n8n-docker": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "MCP_MODE=stdio",
"-v", "n8n-mcp-data:/app/data",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}
```
### Option 3: HTTPS with nginx (Coming Soon)
For production deployments with SSL/TLS:
```bash
# Use the nginx-enhanced compose file
docker compose -f docker-compose.nginx.yml up -d
```
## Development Setup
### Local Development with Docker
1. Copy the override template:
```bash
cp docker-compose.override.yml.example docker-compose.override.yml
```
2. Customize for your needs:
```yaml
# docker-compose.override.yml
version: '3.8'
services:
n8n-mcp:
build: . # Build locally instead of using pre-built
environment:
NODE_ENV: development
LOG_LEVEL: debug
REBUILD_ON_START: "true"
volumes:
# Mount source for development
- ./src:/app/src:ro
- ./scripts:/app/scripts:ro
- ./dist:/app/dist:rw
```
3. Start in development mode:
```bash
docker compose up --build
```
### Testing Docker Builds
Run the test script to validate your Docker setup:
```bash
./scripts/test-docker.sh
```
This script will:
- Build the Docker image
- Test stdio mode functionality
- Test HTTP mode with authentication
- Verify volume persistence
- Check health endpoints
## Production Deployment
### Security Considerations
1. **Authentication**: Always set a strong `AUTH_TOKEN`:
```bash
openssl rand -base64 32
```
2. **Network Security**: Consider using a reverse proxy (nginx, Traefik) for:
- SSL/TLS termination
- Rate limiting
- Access control
3. **Resource Limits**: The compose file includes memory limits:
```yaml
deploy:
resources:
limits:
memory: 512M
reservations:
memory: 256M
```
### Deployment Checklist
- [ ] Generate secure AUTH_TOKEN
- [ ] Configure environment variables
- [ ] Set up volume backups for `/app/data`
- [ ] Configure monitoring/logging
- [ ] Set up SSL/TLS (if exposing publicly)
- [ ] Test health endpoints
- [ ] Verify Claude Desktop connectivity
### Multi-Architecture Support
The images support both amd64 and arm64 architectures:
```bash
# The correct architecture is automatically selected
docker pull ghcr.io/czlonkowski/n8n-mcp:latest
```
## Troubleshooting
### Common Issues
#### Container fails to start
```bash
# Check logs
docker compose logs -f
# Verify environment variables
docker compose config
# Check file permissions
docker compose exec n8n-mcp ls -la /app/data
```
#### Database initialization fails
```bash
# Manually initialize
docker compose exec n8n-mcp node dist/scripts/rebuild.js
# Check database file
docker compose exec n8n-mcp ls -la /app/data/nodes.db
```
#### Authentication errors
```bash
# Verify token is set
echo $AUTH_TOKEN
# Test with curl
curl -v -H "Authorization: Bearer $AUTH_TOKEN" http://localhost:3000/health
```
### Debug Mode
Enable debug logging:
```bash
LOG_LEVEL=debug docker compose up
```
### Volume Management
```bash
# List volumes
docker volume ls | grep n8n-mcp
# Inspect volume
docker volume inspect n8n-mcp-data
# Remove volume (WARNING: deletes data)
docker compose down -v
```
## Advanced Configuration
### Custom Certificates (Phase 2)
For the nginx-enhanced version:
```yaml
volumes:
- ./certs/server.crt:/app/certs/server.crt:ro
- ./certs/server.key:/app/certs/server.key:ro
```
### Database Persistence
The SQLite database is stored in a named volume for persistence:
```yaml
volumes:
n8n-mcp-data:
driver: local
```
To backup:
```bash
docker run --rm -v n8n-mcp-data:/data -v $(pwd):/backup alpine \
tar czf /backup/n8n-mcp-backup.tar.gz -C /data .
```
## Next Steps
- Check [GitHub Releases](https://github.com/czlonkowski/n8n-mcp/releases) for updates
- Report issues at [GitHub Issues](https://github.com/czlonkowski/n8n-mcp/issues)
- Join discussions in [GitHub Discussions](https://github.com/czlonkowski/n8n-mcp/discussions)
## License
This project uses the Sustainable Use License. See [LICENSE](./LICENSE) for details.

9
docs/DOCKER_TESTING_RESULTS.md
View File

@@ -74,10 +74,11 @@
### 🔧 Recommended Fixes
1. **Immediate (Phase 1)**
- Include schema.sql in Docker image
- Add scripts directory for rebuild functionality
- Test database initialization in clean environment
1. **Immediate (Phase 1)** ✅ FIXED
- ✅ Include schema.sql in Docker image
- ✅ Add scripts directory for rebuild functionality
- ✅ Removed invalid COPY syntax that caused build errors
- ✅ Database initialization happens at runtime, not build time
2. **Future Improvements (Phase 2)**
- Optimize image size with multi-stage pruning

150
docs/HTTP_DEPLOYMENT.md
View File

@@ -6,17 +6,70 @@ This guide explains how to deploy n8n-MCP as a private HTTP server for remote ac
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.
## Requirements
## Deployment Options
- Node.js v16+ on the server
- A server with a public IP or domain
- HTTPS proxy (nginx/caddy) for secure connections
- mcp-remote installed on the client
### Option 1: Docker Deployment (Recommended) 🐳
## Server Setup
The easiest way to deploy n8n-MCP is using Docker:
### 1. Clone and Build
#### Quick Start
```bash
# 1. Create configuration
echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
# 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)
NODE_ENV=production
LOG_LEVEL=info
PORT=3000
EOF
# 3. Deploy with Docker Compose
docker compose up -d
# 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:
```
### 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
cd n8n-mcp
@@ -25,8 +78,7 @@ npm run build
npm run rebuild
```
### 2. Configure Environment
#### 2. Configure Environment
```bash
cp .env.example .env
```
@@ -47,13 +99,7 @@ MCP_LOG_LEVEL=info
NODE_ENV=production
```
Generate a secure token:
```bash
openssl rand -base64 32
```
### 3. Start the Server
#### 3. Start the Server
```bash
# Using the deployment script
./scripts/deploy-http.sh
@@ -220,33 +266,95 @@ The test script checks:
## Troubleshooting
### Connection Refused
### 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
#### 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
#### 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. Consider using PM2 for process management:
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
```
## Example Systemd Service
## 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
Create `/etc/systemd/system/n8n-mcp.service`:

331
docs/INSTALLATION.md Normal file
View File

@@ -0,0 +1,331 @@
# Installation Guide
This guide covers all installation methods for n8n-MCP.
## Table of Contents
- [Quick Start](#quick-start)
- [Docker Installation](#docker-installation)
- [Manual Installation](#manual-installation)
- [Development Setup](#development-setup)
- [Troubleshooting](#troubleshooting)
## Quick Start
The fastest way to get n8n-MCP running:
```bash
# Using Docker (recommended)
echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
docker compose up -d
```
## Docker Installation
### Prerequisites
- Docker Desktop or Docker Engine
- Docker Compose (included with Docker Desktop)
### Method 1: Using Pre-built Images
1. **Create a project directory:**
```bash
mkdir n8n-mcp && cd n8n-mcp
```
2. **Create docker-compose.yml:**
```yaml
version: '3.8'
services:
n8n-mcp:
image: ghcr.io/czlonkowski/n8n-mcp:latest
container_name: n8n-mcp
restart: unless-stopped
environment:
MCP_MODE: ${MCP_MODE:-http}
AUTH_TOKEN: ${AUTH_TOKEN:?AUTH_TOKEN is required}
NODE_ENV: ${NODE_ENV:-production}
LOG_LEVEL: ${LOG_LEVEL:-info}
PORT: ${PORT:-3000}
volumes:
- n8n-mcp-data:/app/data
ports:
- "${PORT:-3000}:3000"
healthcheck:
test: ["CMD", "curl", "-f", "http://127.0.0.1:3000/health"]
interval: 30s
timeout: 10s
retries: 3
volumes:
n8n-mcp-data:
driver: local
```
3. **Create .env file:**
```bash
echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
```
4. **Start the container:**
```bash
docker compose up -d
```
5. **Verify installation:**
```bash
curl http://localhost:3000/health
```
### Method 2: Building from Source
1. **Clone the repository:**
```bash
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
```
2. **Build the image:**
```bash
docker build -t n8n-mcp:local .
```
3. **Run with docker-compose:**
```bash
docker compose up -d
```
### Docker Management Commands
```bash
# View logs
docker compose logs -f
# Stop the container
docker compose stop
# Remove container and volumes
docker compose down -v
# Update to latest image
docker compose pull
docker compose up -d
# Execute commands inside container
docker compose exec n8n-mcp npm run validate
# Backup database
docker cp n8n-mcp:/app/data/nodes.db ./nodes-backup.db
```
## Manual Installation
### Prerequisites
- Node.js v16+ (v20+ recommended)
- npm or yarn
- Git
### Step-by-Step Installation
1. **Clone the repository:**
```bash
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
```
2. **Clone n8n documentation (optional but recommended):**
```bash
git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs
```
3. **Install dependencies:**
```bash
npm install
```
4. **Build the project:**
```bash
npm run build
```
5. **Initialize the database:**
```bash
npm run rebuild
```
6. **Validate installation:**
```bash
npm run test-nodes
```
### Running the Server
#### stdio Mode (for Claude Desktop)
```bash
npm start
```
#### HTTP Mode (for remote access)
```bash
npm run start:http
```
### Environment Configuration
Create a `.env` file in the project root:
```env
# Server configuration
MCP_MODE=http # or stdio
PORT=3000
HOST=0.0.0.0
NODE_ENV=production
LOG_LEVEL=info
# Authentication (required for HTTP mode)
AUTH_TOKEN=your-secure-token-here
# Database
NODE_DB_PATH=./data/nodes.db
REBUILD_ON_START=false
```
## Development Setup
### Prerequisites
- All manual installation prerequisites
- TypeScript knowledge
- Familiarity with MCP protocol
### Setup Steps
1. **Clone and install:**
```bash
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
```
2. **Set up development environment:**
```bash
cp .env.example .env
# Edit .env with your settings
```
3. **Development commands:**
```bash
# Run in development mode with auto-reload
npm run dev
# Run tests
npm test
# Type checking
npm run typecheck
# Linting
npm run lint
```
### Docker Development
1. **Use docker-compose override:**
```bash
cp docker-compose.override.yml.example docker-compose.override.yml
```
2. **Edit override for development:**
```yaml
version: '3.8'
services:
n8n-mcp:
build: .
environment:
NODE_ENV: development
LOG_LEVEL: debug
volumes:
- ./src:/app/src:ro
- ./dist:/app/dist
```
3. **Run with live reload:**
```bash
docker compose up --build
```
## Troubleshooting
### Common Issues
#### Port Already in Use
```bash
# Find process using port 3000
lsof -i :3000
# Use a different port
PORT=3001 docker compose up -d
```
#### Database Initialization Failed
```bash
# For Docker
docker compose exec n8n-mcp npm run rebuild
# For manual installation
npm run rebuild
```
#### Permission Denied Errors
```bash
# Fix permissions (Linux/macOS)
sudo chown -R $(whoami) ./data
# For Docker volumes
docker compose exec n8n-mcp chown -R nodejs:nodejs /app/data
```
#### Node Version Mismatch
The project includes automatic fallback to sql.js for compatibility. If you still have issues:
```bash
# Check Node version
node --version
# Use nvm to switch versions
nvm use 20
```
### Getting Help
1. Check the logs:
- Docker: `docker compose logs`
- Manual: Check console output or `LOG_LEVEL=debug npm start`
2. Validate the database:
```bash
npm run validate
```
3. Run tests:
```bash
npm test
```
4. Report issues:
- GitHub Issues: https://github.com/czlonkowski/n8n-mcp/issues
- Include logs and environment details
## Next Steps
After installation, configure Claude Desktop to use n8n-MCP:
- See [Claude Desktop Setup Guide](./README_CLAUDE_SETUP.md)
- For remote deployments, see [HTTP Deployment Guide](./HTTP_DEPLOYMENT.md)
- For Docker details, see [Docker README](../DOCKER_README.md)

66
docs/README.md Normal file
View File

@@ -0,0 +1,66 @@
# n8n-MCP Documentation
Welcome to the n8n-MCP documentation. This directory contains comprehensive guides for installation, configuration, and troubleshooting.
## 📚 Documentation Index
### Getting Started
- **[Installation Guide](./INSTALLATION.md)** - All installation methods including Docker, manual, and development setup
- **[Claude Desktop Setup](./README_CLAUDE_SETUP.md)** - Configure Claude Desktop to use n8n-MCP
- **[Quick Start Tutorial](../README.md)** - Basic overview and quick start instructions
### Deployment
- **[HTTP Deployment Guide](./HTTP_DEPLOYMENT.md)** - Deploy n8n-MCP as an HTTP server for remote access
- **[Docker Deployment](../DOCKER_README.md)** - Comprehensive Docker deployment guide
- **[Docker Testing Results](./DOCKER_TESTING_RESULTS.md)** - Docker implementation test results and findings
### Development
- **[Implementation Plan](../IMPLEMENTATION_PLAN.md)** - Technical implementation details
- **[HTTP Implementation Guide](./HTTP_IMPLEMENTATION_GUIDE.md)** - HTTP server implementation details
- **[Development Setup](./INSTALLATION.md#development-setup)** - Set up development environment
### Reference
- **[Troubleshooting Guide](./TROUBLESHOOTING.md)** - Solutions for common issues
- **[API Reference](./API_REFERENCE.md)** - MCP tools and API documentation (if available)
- **[Environment Variables](./INSTALLATION.md#environment-configuration)** - Configuration options
## 🚀 Quick Links
### For Users
1. **First Time Setup**: Start with the [Installation Guide](./INSTALLATION.md)
2. **Claude Desktop Users**: Follow [Claude Desktop Setup](./README_CLAUDE_SETUP.md)
3. **Remote Deployment**: See [HTTP Deployment Guide](./HTTP_DEPLOYMENT.md)
### For Developers
1. **Local Development**: See [Development Setup](./INSTALLATION.md#development-setup)
2. **Docker Development**: Check [Docker README](../DOCKER_README.md)
3. **Contributing**: Read the implementation plans and guides
## 🐳 Docker Quick Start
```bash
# Quick start with Docker
echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
docker compose up -d
# Check health
curl http://localhost:3000/health
```
## 📖 Documentation Updates
This documentation is actively maintained. Recent updates include:
- ✅ Docker deployment support (Phase 1 complete)
- ✅ Simplified installation process
- ✅ Enhanced troubleshooting guide
- ✅ Multiple deployment options
## 🤝 Getting Help
- **Issues**: [GitHub Issues](https://github.com/czlonkowski/n8n-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/czlonkowski/n8n-mcp/discussions)
- **Troubleshooting**: [Troubleshooting Guide](./TROUBLESHOOTING.md)
## 📝 License
This project is licensed under the Sustainable Use License. See [LICENSE](../LICENSE) for details.

203
docs/README_CLAUDE_SETUP.md Normal file
View File

@@ -0,0 +1,203 @@
# Claude Desktop Configuration for n8n-MCP
## Setup Options
You can set up n8n-MCP with Claude Desktop in three ways:
### Option 1: Docker (Recommended) 🐳
The easiest way to get started is using Docker:
#### 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"
}
}
}
}
```
**Setup steps:**
1. Create a `.env` file:
```bash
echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
```
2. Start the server:
```bash
docker compose up -d
```
3. Copy the AUTH_TOKEN to your Claude config
#### 1b. Docker with stdio Mode (Direct)
```json
{
"mcpServers": {
"n8n-docker": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "MCP_MODE=stdio",
"-v", "n8n-mcp-data:/app/data",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}
```
### Option 2: Local Installation
1. **Build the project first:**
```bash
cd /path/to/n8n-mcp
npm install
npm run build
npm run rebuild
```
2. **Add to Claude Desktop config:**
```json
{
"mcpServers": {
"n8n-documentation": {
"command": "node",
"args": [
"/path/to/n8n-mcp/dist/mcp/index.js"
],
"env": {
"NODE_ENV": "production"
}
}
}
}
```
### Option 3: NPM Global Install (Coming Soon)
```json
{
"mcpServers": {
"n8n-documentation": {
"command": "npx",
"args": [
"-y",
"n8n-mcp@latest"
]
}
}
}
```
## Configuration File Locations
- **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.
## Available Tools
Once configured, you'll have access to these tools in Claude:
- **`list_nodes`** - List and filter n8n nodes
```
list_nodes({ package: "n8n-nodes-base", limit: 10 })
```
- **`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
### Docker Issues
1. **Container fails to start:**
```bash
# Check logs
docker compose logs -f
# Check if port is in use
lsof -i :3000
```
2. **Authentication errors:**
- Ensure AUTH_TOKEN matches in .env and Claude config
- Token should be at least 32 characters
- Check quotes in JSON config
3. **Database not found:**
- The container will auto-initialize on first run
- To rebuild: `docker compose exec n8n-mcp npm run rebuild`
### Local Installation Issues
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

199
docs/SETUP.md Normal file
View File

@@ -0,0 +1,199 @@
# n8n-MCP Setup Guide
This guide will help you set up n8n-MCP with Claude Desktop.
## Prerequisites
- Node.js (any version - the project handles compatibility automatically)
- npm (comes with Node.js)
- Git
- Claude Desktop app
## Step 1: Install Node.js
### Using nvm (recommended for development)
```bash
# Install nvm if you haven't already
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Install latest Node.js
nvm install node
nvm use node
```
### Direct installation
Download and install the latest Node.js from [nodejs.org](https://nodejs.org/)
> **Note**: Version 2.3+ includes automatic database adapter fallback. If your Node.js version doesn't match the native SQLite module, it will automatically use a pure JavaScript implementation.
## Step 2: Clone the Repository
```bash
# Clone n8n-mcp
git clone https://github.com/yourusername/n8n-mcp.git
cd n8n-mcp
# Clone n8n documentation (required)
git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs
```
## Step 3: Install and Build
```bash
# Install dependencies
npm install
# Build the project
npm run build
# Initialize the database
npm run rebuild
# Verify installation
npm run test-nodes
```
Expected output:
```
🧪 Running node tests...
✅ nodes-base.httpRequest passed all checks
✅ nodes-base.slack passed all checks
✅ nodes-base.code passed all checks
📊 Test Results: 3 passed, 0 failed
```
## Step 4: Configure Claude Desktop
### macOS
1. Edit the Claude Desktop configuration:
```bash
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
2. Add the n8n-documentation server:
```json
{
"mcpServers": {
"n8n-documentation": {
"command": "node",
"args": [
"/Users/yourusername/path/to/n8n-mcp/dist/mcp/index.js"
]
}
}
}
```
### Windows
1. Edit the configuration:
```bash
notepad %APPDATA%\Claude\claude_desktop_config.json
```
2. Add the n8n-documentation server with your full path:
```json
{
"mcpServers": {
"n8n-documentation": {
"command": "node",
"args": [
"C:\\Users\\yourusername\\path\\to\\n8n-mcp\\dist\\mcp\\index.js"
]
}
}
}
```
## Step 5: Verify Installation
Run the validation script to ensure everything is working:
```bash
npm run validate
```
## Step 6: Restart Claude Desktop
1. Quit Claude Desktop completely
2. Start Claude Desktop again
3. You should see "n8n-documentation" in the MCP tools menu
## Troubleshooting
### Node version mismatch
**This is now handled automatically!** If you see messages about NODE_MODULE_VERSION:
- The system will automatically fall back to sql.js (pure JavaScript)
- No manual intervention required
- Both adapters provide identical functionality
- Check logs to see which adapter is active
### Database not found
```bash
# Rebuild the database
npm run rebuild
```
### Permission denied
```bash
# Make the wrapper script executable
chmod +x mcp-server-v20.sh
```
### Claude Desktop doesn't see the MCP server
1. Check the config file location:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
2. Verify the path in the config is absolute and correct
3. Check Claude Desktop logs:
- macOS: `~/Library/Logs/Claude/mcp.log`
## Testing the Integration
Once configured, you can test the integration in Claude Desktop:
1. Open a new conversation
2. Ask: "What MCP tools are available?"
3. You should see the n8n documentation tools listed
Example queries to test:
- "List all n8n trigger nodes"
- "Show me the properties of the HTTP Request node"
- "Search for nodes that work with Slack"
- "What AI tools are available in n8n?"
## Updating
To update to the latest version:
```bash
git pull
npm install
npm run build
npm run rebuild
```
## Development Mode
For development with hot reloading:
```bash
# Run in development mode
npm run dev
```
### Database Adapter Information
When the server starts, you'll see one of these messages:
- `Successfully initialized better-sqlite3 adapter` - Using native SQLite (faster)
- `Successfully initialized sql.js adapter` - Using pure JavaScript (compatible with any Node.js version)
Both adapters provide identical functionality, so the user experience is the same regardless of which one is used.

402
docs/TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,402 @@
# Troubleshooting Guide
This guide helps resolve common issues with n8n-MCP.
## Table of Contents
- [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)
## 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
# Or run as root temporarily
docker compose exec -u root n8n-mcp chown -R nodejs:nodejs /app
```
### 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
```bash
# Clean build
rm -rf dist
npm run build
# 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
docker compose restart
```
## Network and Authentication
### CORS Errors
#### Symptoms
- Browser console shows CORS errors
- Preflight requests fail
#### Solutions
1. **Check server CORS settings:**
- Verify MCP_MODE=http
- Check proxy configuration
2. **Test with curl:**
```bash
curl -X OPTIONS http://localhost:3000/mcp \
-H "Origin: http://localhost" \
-H "Access-Control-Request-Method: POST"
```
### SSL/HTTPS Issues
#### Solutions
1. **For development, use HTTP:**
```json
"connect", "http://localhost:3000/mcp"
```
2. **For production, use reverse proxy:**
- See nginx/Caddy examples in HTTP_DEPLOYMENT.md
## Performance Issues
### Slow Response Times
#### Solutions
1. **Check resource usage:**
```bash
# Docker
docker stats n8n-mcp
# System
top
htop
```
2. **Increase memory limits:**
```yaml
# docker-compose.yml
deploy:
resources:
limits:
memory: 1G
```
3. **Enable query logging:**
```bash
LOG_LEVEL=debug npm start
```
### High Memory Usage
#### Solutions
1. **Monitor with Docker:**
```bash
docker compose exec n8n-mcp ps aux
```
2. **Restart periodically:**
```bash
# Add to crontab
0 */6 * * * docker compose restart
```
## Getting More Help
1. **Enable debug logging:**
```bash
LOG_LEVEL=debug docker compose up
```
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