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

Implement SQLite database with full-text search for n8n node documentation

Browse Source 
Major features implemented:
- SQLite storage service with FTS5 for fast node search
- Database rebuild mechanism for bulk node extraction
- MCP tools: search_nodes, extract_all_nodes, get_node_statistics
- Production Docker deployment with persistent storage
- Management scripts for database operations
- Comprehensive test suite for all functionality

Database capabilities:
- Stores node source code and metadata
- Full-text search by node name or content
- No versioning (stores latest only as per requirements)
- Supports complete database rebuilds
- ~4.5MB database with 500+ nodes indexed

Production features:
- Automated deployment script
- Docker Compose production configuration
- Database initialization on first run
- Volume persistence for data
- Management utilities for operations

Documentation:
- Updated README with complete instructions
- Production deployment guide
- Clear troubleshooting section
- API reference for all new tools

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
czlonkowski
2025-06-07 21:12:17 +00:00
parent 0cff8fbe6a
commit 078b67ff35
42 changed files with 33875 additions and 196 deletions
Download Patch File Download Diff File Expand all files Collapse all files

325
README.md
View File

@@ -1,76 +1,96 @@
# n8n-mcp
# n8n-MCP Integration
Integration between n8n workflow automation and Model Context Protocol (MCP). This project provides:
Complete integration between n8n workflow automation and Model Context Protocol (MCP), enabling bidirectional communication between n8n workflows and AI assistants.
- An MCP server that exposes n8n workflows and operations to AI assistants
- A custom n8n node for connecting to MCP servers from within workflows
## Overview
This project provides two main components:
1. **MCP Server**: Allows AI assistants (like Claude) to interact with n8n workflows, execute them, and explore n8n nodes
2. **n8n Custom Node**: Enables n8n workflows to connect to and use MCP servers
**Important**: The MCP server uses stdio transport and is designed to be invoked by AI assistants like Claude Desktop. It's not a standalone HTTP server but rather a tool that AI assistants can call directly.
## Features
- **MCP Server**: Expose n8n workflows as tools, resources, and prompts for AI assistants
- **n8n Node**: Connect to any MCP server from n8n workflows
- **Bidirectional Integration**: Use AI capabilities in n8n and n8n automation in AI contexts
- **Node Source Extraction**: Extract source code from any n8n node, including AI Agent nodes
- **Authentication**: Secure token-based authentication
- **Flexible Transport**: Support for WebSocket and stdio connections
- **Bidirectional Integration**: n8n workflows can call MCP tools, and MCP servers can execute n8n workflows
- **Node Source Extraction**: Extract and search source code from any n8n node, including AI Agent nodes
- **SQLite Database**: Full-text search for n8n node documentation and source code (500+ nodes indexed)
- **Production Ready**: Docker-based deployment with persistent storage
- **Comprehensive MCP Tools**: 12+ tools for workflow management, node exploration, and database search
- **Custom n8n Node**: Connect to any MCP server from n8n workflows
- **Auto-indexing**: Automatically builds a searchable database of all n8n nodes on first run
## Prerequisites
- Node.js 18+
- Docker and Docker Compose (for production deployment)
- n8n instance with API access enabled
- (Optional) Claude Desktop for MCP integration
## Quick Start
### Prerequisites
- Node.js 18+
- n8n instance with API access enabled
- MCP-compatible AI assistant (Claude, etc.)
### Installation
```bash
# Clone the repository
git clone https://github.com/czlonkowski/n8n-mcp.git
git clone https://github.com/yourusername/n8n-mcp.git
cd n8n-mcp
# Install dependencies
npm install
# Copy environment configuration
# Copy environment template
cp .env.example .env
# Edit .env with your n8n credentials
# Configure your n8n API credentials
# Edit .env with your n8n instance details
```
### Running the MCP Server
```bash
# Build the project
npm run build
# Start the MCP server
npm start
# Initialize the database
npm run db:init
# (Optional) Rebuild database with all nodes
npm run db:rebuild
```
For development:
### Development
```bash
# Run tests
npm test
# Start development server
npm run dev
# Type checking
npm run typecheck
```
### Production Deployment
```bash
# Use the automated deployment script
./scripts/deploy-production.sh
# Or manually with Docker Compose
docker compose -f docker-compose.prod.yml up -d
```
See [Production Deployment Guide](docs/PRODUCTION_DEPLOYMENT.md) for detailed instructions.
## Configuration
### Environment Variables
Create a `.env` file based on `.env.example`:
Environment variables (`.env` file):
```env
# MCP Server Configuration
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=localhost
# n8n Configuration
N8N_API_URL=http://localhost:5678
N8N_API_KEY=your-n8n-api-key
N8N_BASIC_AUTH_USER=admin
N8N_BASIC_AUTH_PASSWORD=your-password
N8N_HOST=localhost
N8N_API_KEY=your-api-key
# Authentication
MCP_AUTH_TOKEN=your-secure-token
# Database
NODE_DB_PATH=/app/data/nodes.db
# Logging
LOG_LEVEL=info
@@ -99,20 +119,32 @@ Add the server to your Claude configuration:
### Available MCP Tools
#### Workflow Management
- `execute_workflow` - Execute an n8n workflow by ID
- `list_workflows` - List all available workflows
- `get_workflow` - Get details of a specific workflow
- `create_workflow` - Create a new workflow
- `update_workflow` - Update an existing workflow
- `delete_workflow` - Delete a workflow
- `list_workflows` - List all workflows with filtering options
- `get_workflow` - Get detailed workflow information
- `create_workflow` - Create new workflows programmatically
- `update_workflow` - Update existing workflows
- `delete_workflow` - Delete workflows
- `get_executions` - Get workflow execution history
- `get_execution_data` - Get detailed execution data
- `get_node_source_code` - Extract source code of any n8n node
#### Node Exploration & Search
- `list_available_nodes` - List all available n8n nodes
- `get_node_source_code` - Extract source code of any n8n node
- `search_nodes` - Search nodes by name or content using full-text search
- `extract_all_nodes` - Extract and index all nodes to database
- `get_node_statistics` - Get database statistics (total nodes, packages, etc.)
### Using the n8n MCP Node
1. Copy the node files to your n8n custom nodes directory
1. Install the node in n8n:
```bash
# Copy to n8n custom nodes directory
cp -r dist/n8n/* ~/.n8n/custom/
# Or use the install script
./scripts/install-n8n-node.sh
```
2. Restart n8n
3. The MCP node will appear in the nodes panel
4. Configure with your MCP server credentials
@@ -139,44 +171,64 @@ Add the server to your Claude configuration:
## Architecture
### Project Structure
### Components
```
n8n-mcp/
├── src/
│ ├── mcp/ # MCP server implementation
│ ├── n8n/ # n8n node implementation
│ ├── utils/ # Shared utilities
│ └── types/ # TypeScript type definitions
├── tests/ # Test files
└── dist/ # Compiled output
1. **MCP Server** (`src/mcp/`): Exposes n8n operations as MCP tools
2. **n8n Custom Node** (`src/n8n/`): Allows n8n to connect to MCP servers
3. **SQLite Storage** (`src/services/`): Persistent storage with full-text search
4. **Bridge Layer** (`src/utils/`): Converts between n8n and MCP formats
### Database Management
The SQLite database stores n8n node documentation and source code with full-text search capabilities:
```bash
# Initialize empty database
npm run db:init
# Rebuild the entire database (indexes all nodes)
npm run db:rebuild
# In production
./scripts/manage-production.sh rebuild-db
# View statistics
./scripts/manage-production.sh db-stats
```
### Key Components
#### Search Examples
- **MCP Server**: Handles MCP protocol requests and translates to n8n API calls
- **n8n API Client**: Manages communication with n8n instance
- **Bridge Layer**: Converts between n8n and MCP data formats
- **Authentication**: Validates tokens and manages access control
```javascript
// Search for nodes by name
await mcp.callTool('search_nodes', { query: 'webhook' })
## Development
// Search in specific package
await mcp.callTool('search_nodes', {
query: 'http',
packageName: 'n8n-nodes-base'
})
### Running Tests
// Get database statistics
await mcp.callTool('get_node_statistics', {})
```
## Testing
### Run All Tests
```bash
npm test
```
### Building
### Test Specific Features
```bash
npm run build
```
# Test node extraction
node tests/test-mcp-extraction.js
### Type Checking
# Test database search
node tests/test-sqlite-search.js
```bash
npm run typecheck
# Test AI Agent extraction
./scripts/test-ai-agent-extraction.sh
```
## API Reference
@@ -201,14 +253,36 @@ Parameters:
Extract source code of any n8n node.
Parameters:
- `nodeType` (string, required): The node type identifier (e.g., `@n8n/n8n-nodes-langchain.Agent`)
- `nodeType` (string, required): The node type identifier (e.g., `n8n-nodes-base.Webhook`)
- `includeCredentials` (boolean, optional): Include credential type definitions if available
#### search_nodes
Search nodes using full-text search in the SQLite database.
Parameters:
- `query` (string, optional): Search term for node names/descriptions
- `packageName` (string, optional): Filter by package name
- `nodeType` (string, optional): Filter by node type pattern
- `hasCredentials` (boolean, optional): Filter nodes with credentials
- `limit` (number, optional): Limit results (default: 20)
#### extract_all_nodes
Extract and index all available nodes to the database.
Parameters:
- `packageFilter` (string, optional): Filter by package name
- `limit` (number, optional): Limit number of nodes to extract
#### get_node_statistics
Get database statistics including total nodes, packages, and size.
No parameters required.
#### list_available_nodes
List all available n8n nodes in the system.
Parameters:
- `category` (string, optional): Filter by category (e.g., AI, Data Transformation)
- `category` (string, optional): Filter by category
- `search` (string, optional): Search term to filter nodes
### MCP Resources
@@ -227,65 +301,88 @@ Parameters:
- `optimize_workflow_prompt` - Optimize workflow performance
- `explain_workflow_prompt` - Explain workflow functionality
## Management
Use the management script for production operations:
```bash
# Check status
./scripts/manage-production.sh status
# View logs
./scripts/manage-production.sh logs
# Create backup
./scripts/manage-production.sh backup
# Update services
./scripts/manage-production.sh update
```
## Troubleshooting
### Common Issues
1. **Connection refused**: Ensure n8n is running and API is enabled
2. **Authentication failed**: Check your API key in .env
3. **Workflow not found**: Verify workflow ID exists in n8n
4. **MCP connection failed**: Check server is running and accessible
1. **MCP server keeps restarting in Docker**
- This is expected behavior. The MCP server uses stdio transport and waits for input from AI assistants.
- For testing, use the development mode or invoke through Claude Desktop.
### Debug Mode
2. **Database not found**
- Run `npm run db:init` to create the database
- Run `npm run db:rebuild` to populate with all nodes
3. **n8n API connection failed**
- Verify n8n is running and accessible
- Check API key in `.env` file
- Ensure n8n API is enabled in settings
4. **Node extraction fails**
- Ensure Docker volume mounts are correct
- Check read permissions on node_modules directory
## Documentation
- [Production Deployment Guide](docs/PRODUCTION_DEPLOYMENT.md)
- [AI Agent Extraction Test](docs/AI_AGENT_EXTRACTION_TEST.md)
## Security
- Token-based authentication for n8n API
- Read-only access to node source files
- Isolated Docker containers
- Persistent volume encryption (optional)
## Project Structure
Enable debug logging:
```env
LOG_LEVEL=debug
```
## Special Features
### AI Agent Node Extraction
The MCP server can extract source code from n8n nodes, particularly useful for AI Agent nodes:
```bash
# Test AI Agent extraction
./scripts/test-ai-agent-extraction.sh
# Or use the standalone test
node tests/test-mcp-extraction.js
```
This feature allows AI assistants to:
- Understand n8n node implementations
- Generate compatible code
- Debug workflow issues
- Create custom variations
### Docker Volumes for Node Access
When running in Docker, mount n8n's node_modules for source extraction:
```yaml
volumes:
- n8n_modules:/usr/local/lib/node_modules/n8n/node_modules:ro
n8n-mcp/
├── src/
│ ├── mcp/ # MCP server implementation
│ ├── n8n/ # n8n custom node
│ ├── services/ # SQLite storage service
│ ├── utils/ # Utilities and helpers
│ └── scripts/ # Database management scripts
├── tests/ # Test suite
├── docs/ # Documentation
├── scripts/ # Deployment and management scripts
└── data/ # SQLite database (created on init)
```
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request
## License
ISC License - see LICENSE file for details
ISC License
## Support
- Issues: https://github.com/czlonkowski/n8n-mcp/issues
- n8n Documentation: https://docs.n8n.io
- MCP Specification: https://modelcontextprotocol.io
- GitHub Issues: [Report bugs or request features](https://github.com/yourusername/n8n-mcp/issues)
- n8n Community: [n8n.io/community](https://community.n8n.io/)
- MCP Documentation: [modelcontextprotocol.io](https://modelcontextprotocol.io/)