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

455
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) [![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) [![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. 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.
> *"Before MCP, I was translating. Now I'm composing."* - Claude, after reducing workflow creation time from 45 minutes to 3 minutes
## Overview ## 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) [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 Get n8n-MCP running in 5 minutes:
- **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
## Quick Start **Prerequisites:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed on your system
Choose your deployment method:
### 🐳 Docker (Recommended)
```bash ```bash
# 1. Create environment file # 1. Create .env file with auth token
echo "AUTH_TOKEN=$(openssl rand -base64 32)" > .env 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 docker compose up -d
# 3. Check health # 4. Configure Claude Desktop
curl http://localhost:3000/health # 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:** ## Features
- Node.js (any version - automatic fallback if needed)
- npm or yarn - **🔍 Smart Node Search**: Find nodes by name, category, or functionality
- Git - **📖 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 ```bash
# 1. Clone the repository # 1. Clone the repository
@@ -90,147 +214,7 @@ npm start # stdio mode for Claude Desktop
npm run start:http # HTTP mode for remote access npm run start:http # HTTP mode for remote access
``` ```
## 🔧 Claude Desktop Configuration ### Development Commands
### 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
```bash ```bash
# Build & Test # Build & Test
@@ -239,61 +223,62 @@ npm run rebuild # Rebuild node database
npm run test-nodes # Test critical nodes npm run test-nodes # Test critical nodes
npm run validate # Validate node data npm run validate # Validate node data
npm test # Run all tests npm test # Run all tests
npm run typecheck # Check TypeScript types
# Update Dependencies # Update Dependencies
npm run update:n8n:check # Check for n8n updates npm run update:n8n:check # Check for n8n updates
npm run update:n8n # Update n8n packages npm run update:n8n # Update n8n packages
# Run Server # 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 # Development with auto-reload
npm run dev:http # HTTP dev mode 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: ### HTTP Server for Teams
- **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
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
``` # Using Docker Compose
n8n-mcp/ cat > docker-compose.yml << 'EOF'
├── src/ services:
│ ├── loaders/ # NPM package loaders n8n-mcp:
│ ├── parsers/ # Node metadata extraction image: ghcr.io/czlonkowski/n8n-mcp:latest
│ ├── mappers/ # Documentation mapping container_name: n8n-mcp
│ ├── database/ # SQLite with FTS5 ports:
│ ├── scripts/ # Build and maintenance - "3000:3000"
│ ├── mcp/ # MCP server implementation environment:
│ └── utils/ # Shared utilities - MCP_MODE=http
├── data/ # SQLite database - USE_FIXED_HTTP=true
├── docs/ # Documentation - AUTH_TOKEN=${AUTH_TOKEN}
└── docker-compose.yml # Docker configuration 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 See [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md) for detailed instructions.
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
## 📚 Documentation ## 📚 Documentation
@@ -302,34 +287,38 @@ Current database coverage (updated to n8n v1.97.1):
- [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md) - Remote server deployment - [HTTP Deployment Guide](./docs/HTTP_DEPLOYMENT.md) - Remote server deployment
- [Docker Guide](./docs/DOCKER_README.md) - Container deployment - [Docker Guide](./docs/DOCKER_README.md) - Container deployment
- [Claude's Interview](./docs/CLAUDE_INTERVIEW.md) - Real-world impact of n8n-MCP - [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 - [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 ## 🔄 Recent Updates
### v2.4.0 - AI Documentation Fix & MIT License ### v2.4.0 - AI-Optimized Tools & MIT License
- ✅ Fixed missing AI/LangChain documentation (75.6% coverage for LangChain) - ✅ **NEW**: `get_node_essentials` - 95% smaller responses
- ✅ Added root-nodes path to documentation mapper - ✅ **NEW**: Task templates for common automations
- ✅ AI Agent, chains, and vector stores now fully documented - ✅ **NEW**: Configuration validation
- ✅ Overall documentation improved: 87% → 90% - ✅ Fixed missing AI/LangChain documentation
- ✅ Changed to MIT License for wider adoption - ✅ Changed to MIT License for wider adoption
### v2.3.3 - Automated Dependency Updates ### v2.3.3 - Automated Updates
- ✅ Implemented automated n8n dependency update system - ✅ Weekly automated n8n dependency updates
- ✅ Created GitHub Actions workflow for weekly updates - ✅ GitHub Actions workflow
- ✅ Successfully updated to n8n v1.97.1 - ✅ AI-capable nodes: 35 → 263
- ✅ 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.0 - Universal Compatibility ### v2.3.0 - Universal Compatibility
- ✅ Automatic database adapter fallback
- ✅ Works with ANY Node.js version - ✅ Works with ANY Node.js version
- ✅ Automatic database adapter fallback
- ✅ No manual configuration needed - ✅ No manual configuration needed
See [CHANGELOG.md](./docs/CHANGELOG.md) for full version history. 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. 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 ## 🤝 Contributing
@@ -352,4 +344,11 @@ Contributions are welcome! Please:
- [n8n](https://n8n.io) team for the workflow automation platform - [n8n](https://n8n.io) team for the workflow automation platform
- [Anthropic](https://anthropic.com) for the Model Context Protocol - [Anthropic](https://anthropic.com) for the Model Context Protocol
- All contributors and users of this project - 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>