axiom8-mcp

AI-Powered n8n Documentation Server with Semantic Search

axiom8-mcp provides Claude and other AI assistants with intelligent access to n8n's complete workflow automation knowledge base through semantic search, hybrid retrieval, and AI-powered understanding.

🙏 Built on Solid Foundations

This project builds upon the excellent work of Romuald Czlonkowski, who created the original n8n-MCP server. Axioma has enhanced the original with hybrid search technology, semantic understanding, and AI-powered retrieval capabilities. All credit for the foundational architecture and initial implementation goes to the original author - we're standing on the shoulders of giants to make n8n knowledge even more accessible to AI assistants.

✨ What Makes axiom8-mcp Special

🧠 Semantic Search: Understands intent, not just keywords 🔍 Hybrid Retrieval: Combines text search + AI embeddings + reranking 📚 Complete Coverage: 525+ n8n nodes with full documentation 🤖 AI-Optimized: Built specifically for AI assistant integration 🚀 Production Ready: Validates workflows before deployment

Traditional Search vs Semantic Search

🚀 Quick Start

New to axiom8-mcp? Follow our Complete Installation Guide for step-by-step setup from zero.

5-Minute Setup

1. Get API Keys (optional, for semantic search):

• OpenAI API Key
• Cohere API Key (free tier available)

1. Build & Configure:

   git clone https://github.com/alexandre-axioma/axiom8-mcp.git
   cd axiom8-mcp
   docker build -t axiom8-mcp:latest .

1. Add to Claude Desktop:

   {
     "mcpServers": {
       "axiom8-mcp": {
         "command": "docker",
         "args": [
           "run", "-i", "--rm",
           "-e", "MCP_MODE=stdio",
           "-e", "ENABLE_SEMANTIC_SEARCH=true",
           "-e", "OPENAI_API_KEY=your-key-here",
           "-e", "COHERE_API_KEY=your-key-here",
           "axiom8-mcp:latest"
         ]
       }
     }
   }

1. Add to Claude Code:

   claude mcp add-json axiom8-mcp '{
     "command": "docker",
     "args": [
       "run", "-i", "--rm",
       "-e", "MCP_MODE=stdio",
       "-e", "ENABLE_SEMANTIC_SEARCH=true",
       "-e", "OPENAI_API_KEY=your-key-here",
       "-e", "COHERE_API_KEY=your-key-here",
       "axiom8-mcp:latest"
     ]
   }'

1. Test: Ask Claude: "Search for nodes that help process customer data"

🎯 Usage Examples

Smart Node Discovery

Claude: "I need to process emails and extract attachments"
→ Finds: Gmail, Email, File operations, with working examples

Intelligent Configuration

Claude: "Configure HTTP Request node for OAuth API calls"
→ Returns: Complete setup with authentication examples

Workflow Intelligence

Claude: "Build a workflow that monitors webhooks and saves data"
→ Suggests: Webhook → Filter → Database with full configuration

🔧 Configuration Modes

Full Power Mode (Recommended)

"-e", "ENABLE_SEMANTIC_SEARCH=true",
"-e", "ENABLE_COHERE_RERANKING=true",
"-e", "OPENAI_API_KEY=sk-...",
"-e", "COHERE_API_KEY=..."

Benefits: Best search quality, understands complex queries with hybrid search

Free Mode

"-e", "ENABLE_SEMANTIC_SEARCH=false"

Benefits: Traditional text search, no API keys needed

📊 Performance Comparison

🧠 Available Tools

🔍 Search & Discovery (Hybrid Search Enabled)

• search_nodes - Hybrid search across 525+ nodes with intent understanding
• search_templates - Hybrid search through 499+ community workflow templates
• list_nodes - Browse nodes by category, package, or AI capability
• get_node_essentials - Lightweight node info (5KB vs 100KB+ full schema)
• search_node_properties - Find specific properties (auth, headers, body) across nodes
• get_database_statistics - Overview of available nodes and coverage

⚙️ Node Configuration & Information

• get_node_info - Complete node schema with all properties and operations
• get_node_documentation - Human-readable docs with examples and patterns
• get_node_for_task - Pre-configured nodes for common tasks (send_slack_message, etc.)
• get_property_dependencies - Understand which properties enable others

🤖 AI Tools & Task Management

• list_ai_tools - 263+ nodes optimized for AI agent usage
• get_node_as_tool_info - Guide for using any node as an AI tool
• list_tasks - 29+ task templates organized by category (HTTP/API, Database, AI/LangChain, Communication)

✅ Validation & Quality Assurance

• validate_workflow - Complete workflow validation (structure + connections + expressions)
• validate_workflow_connections - Fast connection and flow validation
• validate_workflow_expressions - n8n expression syntax checking
• validate_node_operation - Full node configuration validation with suggestions
• validate_node_minimal - Quick check for missing required fields

📚 Templates & Workflows

• get_template - Download complete workflow JSON ready to import
• list_node_templates - Find templates using specific nodes
• get_templates_for_task - Curated templates by task type (ai_automation, data_sync, etc.)

🏗️ Architecture

Claude Desktop
    ↓ (MCP Protocol)
axiom8-mcp Server
    ↓ (Hybrid Search)
┌─────────────────────┐
│ FTS5 Text Search    │ ← Keywords, exact matches
│ + Vector Embeddings │ ← Semantic understanding  
│ + RRF Fusion        │ ← Combines both results
│ + Cohere Reranking  │ ← Final quality boost
└─────────────────────┘
    ↓
Pre-built Knowledge Base
• 525 n8n nodes
• 499+ workflow templates  
• Documentation & examples
• AI tool configurations

🔍 Technical Details

Hybrid Search Engine

• FTS5: SQLite full-text search for exact matches
• OpenAI Embeddings: text-embedding-3-small for semantic understanding
• RRF Fusion: Combines results using Reciprocal Rank Fusion
• Cohere Reranking: rerank-multilingual-v3.0 for final optimization

Database

• Pre-embedded: 525 nodes + 499 templates with embeddings ready
• SQLite BLOB storage: Efficient vector storage
• Content hashing: Incremental updates only when needed
• Zero-downtime: Atomic database operations

Performance

• Search latency: ~100-200ms with semantic search
• Database size: ~50MB with embeddings
• Memory usage: ~100MB runtime

📚 Documentation

• [Complete Installation Guide](./INSTALLATION_GUIDE.md) - Step-by-step setup from zero
• [Tools Reference](./docs/TOOLS.md) - Comprehensive guide to all 21 MCP tools with examples and performance tips

🚨 Troubleshooting

Common Issues

"No semantic search results"

• Check API keys are valid
• Verify OpenAI account has credits
• Test with basic mode first

"Docker image not found"

docker build -t axiom8-mcp:latest .

"Claude Desktop not connecting"

• Validate JSON configuration
• Restart Claude Desktop completely
• Check Docker is running

Debug Steps

1. Test Docker image: docker run --rm axiom8-mcp:latest
2. Validate config JSON at jsonlint.com
3. Check API keys independently
4. Enable debug logging: "LOG_LEVEL=debug"

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Original Author: Special thanks to Romuald Czlonkowski for creating the original n8n-MCP server that serves as the foundation for this project.

Enhanced by: Axioma - We've added hybrid search, semantic understanding, and AI-powered retrieval capabilities to make n8n knowledge even more accessible to AI assistants.

Ready to give your AI assistant superhuman n8n knowledge? Start with our Installation Guide!