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

docs: restructure README for better user experience

Browse Source 
Major reorganization to improve onboarding and clarity:

Structure changes:
- Moved Claude testimonial up after Overview for immediate social proof
- Quick Start now Docker-first with exact commands (5-minute setup)
- Added Docker Desktop prerequisite
- Features section moved after Quick Start
- Reorganized MCP tools into Core/Advanced categories
- Simplified Claude Desktop configuration with 3 clear options
- Separated Local Development from Quick Start
- Added Production Deployment section for teams
- Updated metrics with performance data
- Added centered footer with community message

Content improvements:
- Clearer docker-compose.yml creation commands
- Exact file paths for Claude Desktop config
- Updated tool examples focusing on essentials
- Consolidated recent updates
- Better categorization of documentation links

The README now provides a smoother path from discovery to deployment,
with Docker as the primary recommended approach.

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
2025-06-16 22:51:42 +02:00
parent d3861368a2
commit 9192723add
1 changed files with 227 additions and 228 deletions
Download Patch File Download Diff File Expand all files Collapse all files

453
README.md
View File

@@ -5,9 +5,7 @@
[![Version](https://img.shields.io/badge/version-2.4.0-blue.svg)](https://github.com/czlonkowski/n8n-mcp)
[![Docker](https://img.shields.io/badge/docker-ghcr.io%2Fczlonkowski%2Fn8n--mcp-green.svg)](https://github.com/czlonkowski/n8n-mcp/pkgs/container/n8n-mcp)
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 525+ workflow automation nodes.
> *"Before MCP, I was translating. Now I'm composing."* - Claude, after reducing workflow creation time from 45 minutes to 3 minutes
A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to n8n node documentation, properties, and operations. Deploy in minutes to give Claude and other AI assistants deep knowledge about n8n's 525+ workflow automation nodes.
## Overview
@@ -33,42 +31,168 @@ When Claude, Anthropic's AI assistant, tested n8n-MCP, the results were transfor
[Read the full interview →](docs/CLAUDE_INTERVIEW.md)
## Features
## 🚀 Quick Start with Docker
- **Comprehensive Node Information**: Access properties, operations, credentials, and documentation for all n8n nodes
- **AI Tool Detection**: Automatically identifies nodes with AI capabilities (usableAsTool)
- **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
- **Remote Deployment Ready**: Production-ready HTTP server for multi-user services
- **Universal Compatibility**: Works with any Node.js version through automatic adapter fallback
Get n8n-MCP running in 5 minutes:
## Quick Start
Choose your deployment method:
### 🐳 Docker (Recommended)
**Prerequisites:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed on your system
```bash
# 1. Create environment file
# 1. Create .env file with auth token
echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env
echo "USE_FIXED_HTTP=true" >> .env
# 2. Start the server
# 2. Create docker-compose.yml
cat > docker-compose.yml << 'EOF'
services:
n8n-mcp:
image: ghcr.io/czlonkowski/n8n-mcp:latest
container_name: n8n-mcp
ports:
- "3000:3000"
environment:
- MCP_MODE=stdio
- LOG_LEVEL=error
- DISABLE_CONSOLE_OUTPUT=true
volumes:
- n8n-mcp-data:/app/data
restart: unless-stopped
volumes:
n8n-mcp-data:
EOF
# 3. Start the container
docker compose up -d
# 3. Check health
curl http://localhost:3000/health
# 4. Configure Claude Desktop
# Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
# or %APPDATA%\Claude\claude_desktop_config.json (Windows)
```
That's it! The server is running and ready for connections.
Add this to your Claude Desktop config:
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "MCP_MODE=stdio",
"-e", "LOG_LEVEL=error",
"-e", "DISABLE_CONSOLE_OUTPUT=true",
"-v", "n8n-mcp-data:/app/data",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}
```
### 💻 Local Installation
**5. Restart Claude Desktop** - That's it! 🎉
**Prerequisites:**
- Node.js (any version - automatic fallback if needed)
- npm or yarn
- Git
## Features
- **🔍 Smart Node Search**: Find nodes by name, category, or functionality
- **📖 Essential Properties**: Get only the 10-20 properties that matter (NEW in v2.4.0)
- **🎯 Task Templates**: Pre-configured settings for common automation tasks
- **✅ Config Validation**: Validate node configurations before deployment
- **🔗 Dependency Analysis**: Understand property relationships and conditions
- **💡 Working Examples**: Real-world examples for immediate use
- **⚡ Fast Response**: Average query time ~12ms with optimized SQLite
- **🌐 Universal Compatibility**: Works with any Node.js version
## 📡 Available MCP Tools
Once connected, Claude can use these powerful tools:
### Core Tools
- **`list_nodes`** - List all n8n nodes with filtering options
- **`get_node_info`** - Get comprehensive information about a specific node
- **`get_node_essentials`** - Get only essential properties with examples (95% smaller)
- **`search_nodes`** - Full-text search across all node documentation
- **`search_node_properties`** - Find specific properties within nodes
- **`list_ai_tools`** - List all AI-capable nodes
### Advanced Tools
- **`get_node_for_task`** - Pre-configured node settings for common tasks
- **`list_tasks`** - Discover available task templates
- **`validate_node_config`** - Validate configurations before use
- **`get_property_dependencies`** - Analyze property visibility conditions
- **`get_node_documentation`** - Get parsed documentation from n8n-docs
- **`get_database_statistics`** - View database metrics and coverage
### Example Usage
```typescript
// Get essentials for quick configuration
get_node_essentials("nodes-base.httpRequest")
// Find nodes for a specific task
search_nodes({ query: "send email gmail" })
// Get pre-configured settings
get_node_for_task("send_email")
// Validate before deployment
validate_node_config({
nodeType: "nodes-base.httpRequest",
config: { method: "POST", url: "..." }
})
```
## 🔧 Claude Desktop Configuration
### Option 1: Docker (Recommended)
See Quick Start above for the simplest setup.
### Option 2: Local Installation
If you prefer running locally:
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "node",
"args": ["/path/to/n8n-mcp/dist/mcp/index.js"],
"env": {
"NODE_ENV": "production",
"LOG_LEVEL": "error",
"MCP_MODE": "stdio",
"DISABLE_CONSOLE_OUTPUT": "true"
}
}
}
}
```
### Option 3: Remote Server
For team deployments:
```json
{
"mcpServers": {
"n8n-remote": {
"command": "node",
"args": [
"/path/to/n8n-mcp/scripts/mcp-http-client.js",
"http://your-server.com:3000/mcp"
],
"env": {
"MCP_AUTH_TOKEN": "your-auth-token"
}
}
}
}
```
**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`
## 💻 Local Development Setup
For contributors and advanced users:
```bash
# 1. Clone the repository
@@ -90,147 +214,7 @@ npm start # stdio mode for Claude Desktop
npm run start:http # HTTP mode for remote access
```
## 🔧 Claude Desktop Configuration
### For Local Installation (stdio mode) - Recommended
```json
{
"mcpServers": {
"n8n-mcp": {
"command": "node",
"args": ["/path/to/n8n-mcp/dist/mcp/index.js"],
"env": {
"NODE_ENV": "production",
"LOG_LEVEL": "error",
"MCP_MODE": "stdio",
"DISABLE_CONSOLE_OUTPUT": "true"
}
}
}
}
```
⚠️ **Important**: The environment variables above are required for proper stdio communication.
### For Docker (stdio mode)
```json
{
"mcpServers": {
"n8n-docker": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "MCP_MODE=stdio",
"-e", "LOG_LEVEL=error",
"-e", "DISABLE_CONSOLE_OUTPUT=true",
"-v", "n8n-mcp-data:/app/data",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}
```
### For Remote Server (HTTP mode)
For production deployments with HTTP mode, use the custom HTTP client:
```json
{
"mcpServers": {
"n8n-remote": {
"command": "node",
"args": [
"/path/to/n8n-mcp/scripts/mcp-http-client.js",
"http://your-server.com:3000/mcp"
],
"env": {
"MCP_AUTH_TOKEN": "your-auth-token"
}
}
}
}
```
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`
⚠️ **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
### Development Commands
```bash
# Build & Test
@@ -239,61 +223,62 @@ 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
# Update Dependencies
npm run update:n8n:check # Check for n8n updates
npm run update:n8n # Update n8n packages
# 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
```
### Automated Updates
## 🚀 Production Deployment
n8n releases weekly. This project includes automated dependency updates:
- **GitHub Actions**: Runs weekly to check and update n8n packages
- **Update Script**: `npm run update:n8n` for manual updates
- **Validation**: All updates are tested before merging
### HTTP Server for Teams
See [Dependency Updates Guide](./docs/DEPENDENCY_UPDATES.md) for details.
Deploy n8n-MCP as a shared service:
### Project Structure
```bash
# Using Docker
docker run -d \
--name n8n-mcp \
--restart unless-stopped \
-e MCP_MODE=http \
-e USE_FIXED_HTTP=true \
-e AUTH_TOKEN=$AUTH_TOKEN \
-p 3000:3000 \
ghcr.io/czlonkowski/n8n-mcp:latest
```
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
# Using Docker Compose
cat > docker-compose.yml << 'EOF'
services:
n8n-mcp:
image: ghcr.io/czlonkowski/n8n-mcp:latest
container_name: n8n-mcp
ports:
- "3000:3000"
environment:
- MCP_MODE=http
- USE_FIXED_HTTP=true
- AUTH_TOKEN=${AUTH_TOKEN}
volumes:
- n8n-mcp-data:/app/data
restart: unless-stopped
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
interval: 30s
timeout: 10s
retries: 3
volumes:
n8n-mcp-data:
EOF
docker compose up -d
```
## 📊 Metrics & Coverage
Current database coverage (updated to n8n v1.97.1):
- ✅ **525/525** nodes loaded (100%)
- ✅ **520** nodes with properties (99%)
- ✅ **334** nodes with operations (63.6%)
- ✅ **470** nodes with documentation (90%)
- ✅ **263** AI-capable tools detected
- ✅ All critical nodes validated
- ✅ **AI Agent & LangChain nodes** fully documented
See [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md) for detailed instructions.
## 📚 Documentation
@@ -302,34 +287,38 @@ Current database coverage (updated to n8n v1.97.1):
- [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md) - Remote server deployment
- [Docker Guide](./docs/DOCKER_README.md) - Container deployment
- [Claude's Interview](./docs/CLAUDE_INTERVIEW.md) - Real-world impact of n8n-MCP
- [Troubleshooting](./docs/TROUBLESHOOTING.md) - Common issues and solutions
- [Architecture](./docs/ARCHITECTURE.md) - Technical design details
- [Troubleshooting](./docs/TROUBLESHOOTING.md) - Common issues and solutions
## 📊 Metrics & Coverage
Current database coverage (n8n v1.97.1):
- ✅ **525/525** nodes loaded (100%)
- ✅ **520** nodes with properties (99%)
- ✅ **470** nodes with documentation (90%)
- ✅ **263** AI-capable tools detected
- ✅ **AI Agent & LangChain nodes** fully documented
- ⚡ **Average response time**: ~12ms
- 💾 **Database size**: ~15MB (optimized)
## 🔄 Recent Updates
### v2.4.0 - AI Documentation Fix & MIT License
- ✅ Fixed missing AI/LangChain documentation (75.6% coverage for LangChain)
- ✅ Added root-nodes path to documentation mapper
- ✅ AI Agent, chains, and vector stores now fully documented
- ✅ Overall documentation improved: 87% → 90%
### v2.4.0 - AI-Optimized Tools & MIT License
- ✅ **NEW**: `get_node_essentials` - 95% smaller responses
- ✅ **NEW**: Task templates for common automations
- ✅ **NEW**: Configuration validation
- ✅ Fixed missing AI/LangChain documentation
- ✅ Changed to MIT License for wider adoption
### v2.3.3 - Automated Dependency Updates
- ✅ Implemented automated n8n dependency update system
- ✅ Created GitHub Actions workflow for weekly updates
- ✅ Successfully updated to n8n v1.97.1
- ✅ Fixed validation script for new node type format
- ✅ Significant increase in AI-capable nodes (35 → 263)
### 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.3 - Automated Updates
- ✅ Weekly automated n8n dependency updates
- ✅ GitHub Actions workflow
- ✅ AI-capable nodes: 35 → 263
### v2.3.0 - Universal Compatibility
- ✅ Automatic database adapter fallback
- ✅ Works with ANY Node.js version
- ✅ Automatic database adapter fallback
- ✅ No manual configuration needed
See [CHANGELOG.md](./docs/CHANGELOG.md) for full version history.
@@ -338,7 +327,10 @@ See [CHANGELOG.md](./docs/CHANGELOG.md) for full version history.
MIT License - see [LICENSE](LICENSE) for details.
**Attribution appreciated!** If you use n8n-MCP, consider giving it a ⭐ star on GitHub or mentioning it in your project. See [ATTRIBUTION.md](ATTRIBUTION.md) for easy ways to give credit.
**Attribution appreciated!** If you use n8n-MCP, consider:
- ⭐ Starring this repository
- 💬 Mentioning it in your project
- 🔗 Linking back to this repo
## 🤝 Contributing
@@ -353,3 +345,10 @@ Contributions are welcome! Please:
- [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
---
<div align="center">
<strong>Built with ❤️ for the n8n community</strong><br>
<sub>Making AI + n8n workflow creation delightful</sub>
</div>