docs: comprehensive documentation update for production deployment
- 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
488
README.md
488
README.md
@@ -4,7 +4,7 @@
|
||||
[](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
|
||||
[](LICENSE)
|
||||
|
||||
A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations.
|
||||
A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. Deploy locally or remotely to give Claude and other AI assistants deep knowledge about n8n's 450+ workflow automation nodes.
|
||||
|
||||
## Overview
|
||||
|
||||
@@ -23,97 +23,76 @@ n8n-MCP serves as a bridge between n8n's workflow automation platform and AI mod
|
||||
- **Versioned Node Support**: Handles complex versioned nodes like HTTPRequest and Code
|
||||
- **Fast Search**: SQLite with FTS5 for instant full-text search across all documentation
|
||||
- **MCP Protocol**: Standard interface for AI assistants to query n8n knowledge
|
||||
- **HTTP Server Mode**: Deploy remotely with fixed implementation (v2.3.2) that bypasses stream issues
|
||||
- **Remote Deployment Ready**: Production-ready HTTP server for multi-user services
|
||||
- **Universal Compatibility**: Works with any Node.js version through automatic adapter fallback
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
Choose your deployment method:
|
||||
|
||||
- Node.js (any version - automatic fallback to pure JavaScript if needed)
|
||||
- npm or yarn
|
||||
- Git
|
||||
### 🐳 Docker (Recommended)
|
||||
|
||||
> **Note**: The project uses an intelligent database adapter that automatically falls back to a pure JavaScript implementation (sql.js) if native dependencies fail to load. This ensures compatibility with any Node.js version, including Claude Desktop's bundled runtime.
|
||||
|
||||
### Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone https://github.com/yourusername/n8n-mcp.git
|
||||
cd n8n-mcp
|
||||
```
|
||||
|
||||
2. Clone n8n documentation (required for full documentation coverage):
|
||||
```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 the installation:
|
||||
```bash
|
||||
npm run test-nodes
|
||||
```
|
||||
|
||||
## Docker Quick Start 🐳
|
||||
|
||||
The easiest way to get started is using Docker:
|
||||
|
||||
### Option 1: Simple HTTP Server (Recommended)
|
||||
|
||||
1. Create a `.env` file:
|
||||
```bash
|
||||
# Generate a secure token
|
||||
AUTH_TOKEN=$(openssl rand -base64 32)
|
||||
echo "AUTH_TOKEN=$AUTH_TOKEN" > .env
|
||||
# 1. Create environment file
|
||||
echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
|
||||
echo "USE_FIXED_HTTP=true" >> .env
|
||||
```
|
||||
|
||||
2. Run with Docker Compose:
|
||||
```bash
|
||||
# 2. Start the server
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
3. Test the server:
|
||||
```bash
|
||||
# 3. Check health
|
||||
curl http://localhost:3000/health
|
||||
```
|
||||
|
||||
4. Configure Claude Desktop with mcp-remote:
|
||||
That's it! The server is running and ready for connections.
|
||||
|
||||
### 💻 Local Installation
|
||||
|
||||
**Prerequisites:**
|
||||
- Node.js (any version - automatic fallback if needed)
|
||||
- npm or yarn
|
||||
- Git
|
||||
|
||||
```bash
|
||||
# 1. Clone the repository
|
||||
git clone https://github.com/czlonkowski/n8n-mcp.git
|
||||
cd n8n-mcp
|
||||
|
||||
# 2. Clone n8n docs (optional but recommended)
|
||||
git clone https://github.com/n8n-io/n8n-docs.git ../n8n-docs
|
||||
|
||||
# 3. Install and build
|
||||
npm install
|
||||
npm run build
|
||||
|
||||
# 4. Initialize database
|
||||
npm run rebuild
|
||||
|
||||
# 5. Start the server
|
||||
npm start # stdio mode for Claude Desktop
|
||||
npm run start:http # HTTP mode for remote access
|
||||
```
|
||||
|
||||
## 🔧 Claude Desktop Configuration
|
||||
|
||||
### For Local Installation (stdio mode)
|
||||
|
||||
**macOS/Linux:**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"n8n-remote": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/mcp-remote@latest",
|
||||
"connect",
|
||||
"http://localhost:3000/mcp"
|
||||
],
|
||||
"n8n-documentation": {
|
||||
"command": "node",
|
||||
"args": ["/path/to/n8n-mcp/dist/mcp/index.js"],
|
||||
"env": {
|
||||
"MCP_AUTH_TOKEN": "your-auth-token-here"
|
||||
"NODE_ENV": "production"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Option 2: Local stdio Mode (Direct Docker)
|
||||
### For Docker (stdio mode)
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -121,9 +100,7 @@ curl http://localhost:3000/health
|
||||
"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"
|
||||
@@ -133,170 +110,10 @@ curl http://localhost:3000/health
|
||||
}
|
||||
```
|
||||
|
||||
### Building and Running with Docker
|
||||
### For Remote Server (HTTP mode)
|
||||
|
||||
The Docker image (~150MB) includes all dependencies and a pre-built database:
|
||||
**Important**: Requires Node.js 18+ on your local machine.
|
||||
|
||||
```bash
|
||||
# Using pre-built image (recommended)
|
||||
docker run -d \
|
||||
-e MCP_MODE=http \
|
||||
-e USE_FIXED_HTTP=true \
|
||||
-e AUTH_TOKEN="your-secure-token" \
|
||||
-p 3000:3000 \
|
||||
ghcr.io/czlonkowski/n8n-mcp:latest
|
||||
|
||||
# Or build locally
|
||||
docker build -t n8n-mcp:local .
|
||||
```
|
||||
|
||||
For detailed Docker documentation, see [Docker Deployment Guide](./docs/DOCKER_README.md).
|
||||
|
||||
## Usage
|
||||
|
||||
### With Claude Desktop
|
||||
|
||||
1. Edit your Claude Desktop configuration:
|
||||
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
||||
- Linux: `~/.config/Claude/claude_desktop_config.json`
|
||||
|
||||
2. Add the n8n-documentation server:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"n8n-documentation": {
|
||||
"command": "node",
|
||||
"args": [
|
||||
"/path/to/n8n-mcp/dist/mcp/index.js"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Restart Claude Desktop
|
||||
|
||||
> **Note**: The Node.js wrapper script (`mcp-server-v20.sh`) is no longer required! The project now automatically handles version mismatches.
|
||||
|
||||
### Available MCP Tools
|
||||
|
||||
- `list_nodes` - List all n8n nodes with filtering options
|
||||
- `get_node_info` - Get detailed information about a specific node
|
||||
- `search_nodes` - Full-text search across all node documentation
|
||||
- `list_ai_tools` - List all AI-capable nodes
|
||||
- `get_node_documentation` - Get parsed documentation for a node
|
||||
- `get_database_statistics` - View database metrics and coverage
|
||||
|
||||
### Example Queries
|
||||
|
||||
```typescript
|
||||
// List all trigger nodes
|
||||
list_nodes({ isTrigger: true })
|
||||
|
||||
// Get info about the HTTP Request node
|
||||
get_node_info({ nodeType: "nodes-base.httpRequest" })
|
||||
|
||||
// Search for OAuth-related nodes
|
||||
search_nodes({ query: "oauth" })
|
||||
|
||||
// Find AI-capable tools
|
||||
list_ai_tools()
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
npm run build # Build TypeScript
|
||||
npm run rebuild # Rebuild node database
|
||||
npm run test-nodes # Test critical nodes
|
||||
npm run validate # Validate node data
|
||||
npm start # Start MCP server
|
||||
npm test # Run tests
|
||||
npm run typecheck # Check TypeScript types
|
||||
```
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
src/
|
||||
├── loaders/ # Node package loaders
|
||||
├── parsers/ # Node metadata parsers
|
||||
├── mappers/ # Documentation mappers
|
||||
├── database/ # SQLite repository
|
||||
├── scripts/ # Build and test scripts
|
||||
└── mcp/ # MCP server implementation
|
||||
```
|
||||
|
||||
### Node.js Version Compatibility
|
||||
|
||||
The project works with any Node.js version thanks to automatic adapter fallback:
|
||||
|
||||
- **Primary**: Uses `better-sqlite3` when compatible (faster)
|
||||
- **Fallback**: Uses `sql.js` when version mismatch detected (pure JS)
|
||||
- **Automatic**: No manual configuration needed
|
||||
|
||||
## Technical Architecture
|
||||
|
||||
### Database Adapter
|
||||
|
||||
The project features an intelligent database adapter that ensures compatibility across different Node.js versions:
|
||||
|
||||
1. **Primary**: Attempts to use `better-sqlite3` for optimal performance
|
||||
2. **Fallback**: Automatically switches to `sql.js` (pure JavaScript) if:
|
||||
- Native modules fail to load
|
||||
- Node.js version mismatch is detected
|
||||
- Running in restricted environments (like Claude Desktop)
|
||||
|
||||
This dual-adapter approach means:
|
||||
- ✅ Works with any Node.js version
|
||||
- ✅ No compilation required in fallback mode
|
||||
- ✅ Maintains full functionality with either adapter
|
||||
- ✅ Automatic persistence with sql.js
|
||||
|
||||
### Performance Characteristics
|
||||
|
||||
- **better-sqlite3**: Native performance, ~10-50x faster
|
||||
- **sql.js**: Pure JavaScript, ~2-5x slower but still responsive
|
||||
- Both adapters support the same API for seamless operation
|
||||
|
||||
## Metrics
|
||||
|
||||
Current implementation achieves:
|
||||
|
||||
- ✅ 458/458 nodes loaded (100%)
|
||||
- ✅ 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
|
||||
|
||||
## Remote Deployment
|
||||
|
||||
### HTTP Server Mode
|
||||
|
||||
n8n-MCP now supports HTTP mode for remote deployments. This allows you to:
|
||||
- Host the MCP server on a cloud VPS
|
||||
- Connect from Claude Desktop using mcp-remote
|
||||
- Single-user design for private use
|
||||
- Simple token-based authentication
|
||||
|
||||
### Quick Start for HTTP Mode
|
||||
|
||||
1. On your server:
|
||||
```bash
|
||||
# Set environment variables
|
||||
export MCP_MODE=http
|
||||
export USE_FIXED_HTTP=true # Important: Use the fixed implementation
|
||||
export AUTH_TOKEN=$(openssl rand -base64 32)
|
||||
|
||||
# Start the server
|
||||
npm run http # This runs the fixed HTTP server
|
||||
```
|
||||
|
||||
2. On your client, configure Claude Desktop with mcp-remote:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
@@ -304,49 +121,190 @@ npm run http # This runs the fixed HTTP server
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/mcp-remote@latest",
|
||||
"connect",
|
||||
"https://your-server.com/mcp"
|
||||
"mcp-remote",
|
||||
"https://your-server.com/mcp",
|
||||
"--header",
|
||||
"Authorization: Bearer ${AUTH_TOKEN}"
|
||||
],
|
||||
"env": {
|
||||
"MCP_AUTH_TOKEN": "your-auth-token"
|
||||
"AUTH_TOKEN": "your-auth-token"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For detailed instructions, see [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md).
|
||||
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`
|
||||
|
||||
## Contributing
|
||||
⚠️ **Note**: After editing, restart Claude Desktop to apply changes.
|
||||
|
||||
## 🚀 Remote Deployment
|
||||
|
||||
### Production HTTP Server
|
||||
|
||||
For multi-user services and remote deployments:
|
||||
|
||||
```bash
|
||||
# 1. Set environment variables
|
||||
export AUTH_TOKEN="your-secure-token-min-32-chars"
|
||||
export USE_FIXED_HTTP=true
|
||||
export MCP_MODE=http
|
||||
export PORT=3000
|
||||
|
||||
# 2. Start with Docker
|
||||
docker run -d \
|
||||
--name n8n-mcp \
|
||||
--restart unless-stopped \
|
||||
-e MCP_MODE=$MCP_MODE \
|
||||
-e USE_FIXED_HTTP=$USE_FIXED_HTTP \
|
||||
-e AUTH_TOKEN=$AUTH_TOKEN \
|
||||
-p $PORT:3000 \
|
||||
ghcr.io/czlonkowski/n8n-mcp:latest
|
||||
|
||||
# 3. Or use Docker Compose
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Client Requirements
|
||||
|
||||
⚠️ **Important**: Remote connections require:
|
||||
- Node.js 18+ installed locally (for mcp-remote)
|
||||
- Or Claude Pro/Team/Enterprise (for native remote MCP support)
|
||||
|
||||
See [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md) for detailed instructions.
|
||||
|
||||
## 📡 Available MCP Tools
|
||||
|
||||
Once connected, Claude can use these tools:
|
||||
|
||||
### Tools
|
||||
|
||||
- **`list_nodes`** - List all n8n nodes with filtering options
|
||||
- **`get_node_info`** - Get detailed information about a specific node
|
||||
- **`search_nodes`** - Full-text search across all node documentation
|
||||
- **`list_ai_tools`** - List all AI-capable nodes
|
||||
- **`get_node_documentation`** - Get parsed documentation for a node
|
||||
- **`get_database_statistics`** - View database metrics and coverage
|
||||
|
||||
### Example Usage
|
||||
|
||||
```typescript
|
||||
// List all trigger nodes
|
||||
list_nodes({ isTrigger: true })
|
||||
|
||||
// Get info about the HTTP Request node
|
||||
get_node_info({ nodeType: "n8n-nodes-base.httpRequest" })
|
||||
|
||||
// Search for OAuth-related nodes
|
||||
search_nodes({ query: "oauth authentication" })
|
||||
|
||||
// Find AI-capable tools
|
||||
list_ai_tools()
|
||||
|
||||
// Get Slack node documentation
|
||||
get_node_documentation({ nodeType: "n8n-nodes-base.slack" })
|
||||
```
|
||||
|
||||
## 🛠️ Development
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
# Build & Test
|
||||
npm run build # Build TypeScript
|
||||
npm run rebuild # Rebuild node database
|
||||
npm run test-nodes # Test critical nodes
|
||||
npm run validate # Validate node data
|
||||
npm test # Run all tests
|
||||
npm run typecheck # Check TypeScript types
|
||||
|
||||
# Run Server
|
||||
npm start # Start in stdio mode
|
||||
npm run start:http # Start in HTTP mode
|
||||
npm run dev # Development with auto-reload
|
||||
npm run dev:http # HTTP dev mode
|
||||
|
||||
# Docker
|
||||
docker compose up -d # Start with Docker
|
||||
docker compose logs # View logs
|
||||
docker compose down # Stop containers
|
||||
```
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
n8n-mcp/
|
||||
├── src/
|
||||
│ ├── loaders/ # NPM package loaders
|
||||
│ ├── parsers/ # Node metadata extraction
|
||||
│ ├── mappers/ # Documentation mapping
|
||||
│ ├── database/ # SQLite with FTS5
|
||||
│ ├── scripts/ # Build and maintenance
|
||||
│ ├── mcp/ # MCP server implementation
|
||||
│ └── utils/ # Shared utilities
|
||||
├── data/ # SQLite database
|
||||
├── docs/ # Documentation
|
||||
└── docker-compose.yml # Docker configuration
|
||||
```
|
||||
|
||||
## 📊 Metrics & Coverage
|
||||
|
||||
Current database coverage:
|
||||
|
||||
- ✅ **458/458** nodes loaded (100%)
|
||||
- ✅ **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
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- [Installation Guide](./docs/INSTALLATION.md) - Detailed setup instructions
|
||||
- [Claude Desktop Setup](./docs/README_CLAUDE_SETUP.md) - Configure Claude Desktop
|
||||
- [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md) - Remote server deployment
|
||||
- [Docker Guide](./docs/DOCKER_README.md) - Container deployment
|
||||
- [Troubleshooting](./docs/TROUBLESHOOTING.md) - Common issues and solutions
|
||||
- [Architecture](./docs/ARCHITECTURE.md) - Technical design details
|
||||
|
||||
## 🔄 Recent Updates
|
||||
|
||||
### v2.3.2 - HTTP Server Fix
|
||||
- ✅ Fixed "stream is not readable" error
|
||||
- ✅ Direct JSON-RPC implementation bypassing transport issues
|
||||
- ✅ Added `USE_FIXED_HTTP=true` for stable HTTP mode
|
||||
- ✅ Average response time: ~12ms
|
||||
|
||||
### v2.3.0 - Universal Compatibility
|
||||
- ✅ Automatic database adapter fallback
|
||||
- ✅ Works with ANY Node.js version
|
||||
- ✅ No manual configuration needed
|
||||
|
||||
See [CHANGELOG.md](./docs/CHANGELOG.md) for full version history.
|
||||
|
||||
## 📦 License
|
||||
|
||||
This project uses the Sustainable Use License. Key points:
|
||||
- ✅ Free for internal business and personal use
|
||||
- ✅ Modifications allowed for own use
|
||||
- ❌ Cannot host as a service without permission
|
||||
- ❌ Cannot include in commercial products without permission
|
||||
|
||||
See [LICENSE](./LICENSE) for full details.
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome! Please:
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Run tests and validation
|
||||
5. Submit a pull request
|
||||
3. Run tests (`npm test`)
|
||||
4. Submit a pull request
|
||||
|
||||
## License
|
||||
## 👏 Acknowledgments
|
||||
|
||||
This project uses the Sustainable Use License. See LICENSE file for details.
|
||||
|
||||
Copyright (c) 2024 AiAdvisors Romuald Czlonkowski
|
||||
|
||||
## Recent Updates (v2.3.2)
|
||||
|
||||
### HTTP Server Fix
|
||||
The v2.3.2 release fixes critical issues with the HTTP server:
|
||||
- ✅ Fixed "stream is not readable" error by removing body parsing middleware
|
||||
- ✅ Fixed "Server not initialized" error with direct JSON-RPC implementation
|
||||
- ✅ Added `USE_FIXED_HTTP=true` environment variable for stable HTTP mode
|
||||
- ✅ Improved performance with average response time of ~12ms
|
||||
|
||||
### Node.js Compatibility (v2.3)
|
||||
- ✅ Automatic database adapter fallback (better-sqlite3 → sql.js)
|
||||
- ✅ Works with any Node.js version without manual configuration
|
||||
- ✅ Perfect for Claude Desktop integration
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- n8n team for the excellent workflow automation platform
|
||||
- Anthropic for the Model Context Protocol specification
|
||||
- [n8n](https://n8n.io) team for the workflow automation platform
|
||||
- [Anthropic](https://anthropic.com) for the Model Context Protocol
|
||||
- All contributors and users of this project
|
||||
@@ -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)
|
||||
@@ -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 .
|
||||
```
|
||||
|
||||
- **`get_node_info`** - Get detailed information about a specific node
|
||||
```
|
||||
get_node_info({ nodeType: "httpRequest" })
|
||||
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
|
||||
```
|
||||
|
||||
- **`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
|
||||
**"Cannot find image" error:**
|
||||
```bash
|
||||
# Pull the latest image
|
||||
docker pull ghcr.io/czlonkowski/n8n-mcp:latest
|
||||
```
|
||||
|
||||
# Check if port is in use
|
||||
lsof -i :3000
|
||||
```
|
||||
**Permission denied:**
|
||||
```bash
|
||||
# Ensure Docker is running
|
||||
docker ps
|
||||
```
|
||||
|
||||
2. **Authentication errors:**
|
||||
- Ensure AUTH_TOKEN matches in .env and Claude config
|
||||
- Token should be at least 32 characters
|
||||
- Check quotes in JSON config
|
||||
### Quick Fixes
|
||||
|
||||
3. **Database not found:**
|
||||
- The container will auto-initialize on first run
|
||||
- To rebuild: `docker compose exec n8n-mcp npm run rebuild`
|
||||
- 🔄 **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
|
||||
|
||||
### 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
|
||||
For more help, see [Troubleshooting Guide](./TROUBLESHOOTING.md)
|
||||
@@ -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
|
||||
```
|
||||
|
||||
2. **Increase memory limits:**
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
deploy:
|
||||
# Increase limits
|
||||
# docker-compose.yml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 1G
|
||||
```
|
||||
```
|
||||
|
||||
3. **Enable query logging:**
|
||||
```bash
|
||||
LOG_LEVEL=debug npm start
|
||||
```
|
||||
**Expected performance:**
|
||||
- Response time: ~12ms
|
||||
- Memory usage: 50-100MB
|
||||
- Database queries: <5ms
|
||||
|
||||
### High Memory Usage
|
||||
## 🆘 Still Need Help?
|
||||
|
||||
#### Solutions
|
||||
### Debug Mode
|
||||
|
||||
1. **Monitor with Docker:**
|
||||
```bash
|
||||
docker compose exec n8n-mcp ps aux
|
||||
```
|
||||
```bash
|
||||
# Enable verbose logging
|
||||
LOG_LEVEL=debug npm start
|
||||
|
||||
2. **Restart periodically:**
|
||||
```bash
|
||||
# Add to crontab
|
||||
0 */6 * * * docker compose restart
|
||||
```
|
||||
# Docker debug
|
||||
docker compose logs -f --tail 100
|
||||
```
|
||||
|
||||
## Getting More Help
|
||||
### Get Support
|
||||
|
||||
1. **Enable debug logging:**
|
||||
```bash
|
||||
LOG_LEVEL=debug docker compose up
|
||||
```
|
||||
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`
|
||||
|
||||
2. **Collect diagnostic info:**
|
||||
```bash
|
||||
# System info
|
||||
uname -a
|
||||
node --version
|
||||
docker --version
|
||||
### Common Solutions Summary
|
||||
|
||||
# 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
|
||||
141
scripts/mcp-http-client.js
Executable file
141
scripts/mcp-http-client.js
Executable file
@@ -0,0 +1,141 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* Minimal MCP HTTP Client for Node.js v16 compatibility
|
||||
* This bypasses mcp-remote and its TransformStream dependency
|
||||
*/
|
||||
|
||||
const http = require('http');
|
||||
const https = require('https');
|
||||
const readline = require('readline');
|
||||
|
||||
// Get configuration from command line arguments
|
||||
const url = process.argv[2];
|
||||
const authToken = process.env.MCP_AUTH_TOKEN;
|
||||
|
||||
if (!url) {
|
||||
console.error('Usage: node mcp-http-client.js <server-url>');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
if (!authToken) {
|
||||
console.error('Error: MCP_AUTH_TOKEN environment variable is required');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Parse URL
|
||||
const parsedUrl = new URL(url);
|
||||
const isHttps = parsedUrl.protocol === 'https:';
|
||||
const httpModule = isHttps ? https : http;
|
||||
|
||||
// Create readline interface for stdio
|
||||
const rl = readline.createInterface({
|
||||
input: process.stdin,
|
||||
output: process.stdout,
|
||||
terminal: false
|
||||
});
|
||||
|
||||
// Buffer for incomplete JSON messages
|
||||
let buffer = '';
|
||||
|
||||
// Function to send JSON-RPC request
|
||||
function sendRequest(request) {
|
||||
const requestBody = JSON.stringify(request);
|
||||
|
||||
const options = {
|
||||
hostname: parsedUrl.hostname,
|
||||
port: parsedUrl.port || (isHttps ? 443 : 80),
|
||||
path: parsedUrl.pathname,
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Content-Length': Buffer.byteLength(requestBody),
|
||||
'Authorization': `Bearer ${authToken}`
|
||||
}
|
||||
};
|
||||
|
||||
const req = httpModule.request(options, (res) => {
|
||||
let responseData = '';
|
||||
|
||||
res.on('data', (chunk) => {
|
||||
responseData += chunk;
|
||||
});
|
||||
|
||||
res.on('end', () => {
|
||||
try {
|
||||
const response = JSON.parse(responseData);
|
||||
// Ensure the response has the correct structure
|
||||
if (response.jsonrpc && (response.result !== undefined || response.error !== undefined)) {
|
||||
console.log(JSON.stringify(response));
|
||||
} else {
|
||||
// Wrap non-JSON-RPC responses
|
||||
console.log(JSON.stringify({
|
||||
jsonrpc: '2.0',
|
||||
id: request.id || null,
|
||||
error: {
|
||||
code: -32603,
|
||||
message: 'Internal error',
|
||||
data: response
|
||||
}
|
||||
}));
|
||||
}
|
||||
} catch (err) {
|
||||
console.log(JSON.stringify({
|
||||
jsonrpc: '2.0',
|
||||
id: request.id || null,
|
||||
error: {
|
||||
code: -32700,
|
||||
message: 'Parse error',
|
||||
data: err.message
|
||||
}
|
||||
}));
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
req.on('error', (err) => {
|
||||
console.log(JSON.stringify({
|
||||
jsonrpc: '2.0',
|
||||
id: request.id || null,
|
||||
error: {
|
||||
code: -32000,
|
||||
message: 'Transport error',
|
||||
data: err.message
|
||||
}
|
||||
}));
|
||||
});
|
||||
|
||||
req.write(requestBody);
|
||||
req.end();
|
||||
}
|
||||
|
||||
// Process incoming JSON-RPC messages from stdin
|
||||
rl.on('line', (line) => {
|
||||
// Try to parse each line as a complete JSON-RPC message
|
||||
try {
|
||||
const request = JSON.parse(line);
|
||||
|
||||
// Forward the request to the HTTP server
|
||||
sendRequest(request);
|
||||
} catch (err) {
|
||||
// Log parse errors to stdout in JSON-RPC format
|
||||
console.log(JSON.stringify({
|
||||
jsonrpc: '2.0',
|
||||
id: null,
|
||||
error: {
|
||||
code: -32700,
|
||||
message: 'Parse error',
|
||||
data: err.message
|
||||
}
|
||||
}));
|
||||
}
|
||||
});
|
||||
|
||||
// Handle process termination
|
||||
process.on('SIGINT', () => {
|
||||
process.exit(0);
|
||||
});
|
||||
|
||||
process.on('SIGTERM', () => {
|
||||
process.exit(0);
|
||||
});
|
||||
@@ -20,9 +20,12 @@ async function main() {
|
||||
try {
|
||||
const mode = process.env.MCP_MODE || 'stdio';
|
||||
|
||||
// Only show debug messages in HTTP mode to avoid corrupting stdio communication
|
||||
if (mode === 'http') {
|
||||
console.error(`Starting n8n Documentation MCP Server in ${mode} mode...`);
|
||||
console.error('Current directory:', process.cwd());
|
||||
console.error('Node version:', process.version);
|
||||
}
|
||||
|
||||
if (mode === 'http') {
|
||||
// Check if we should use the fixed implementation
|
||||
|
||||
Reference in New Issue
Block a user