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

refactor: reorganize documentation and configuration files for improved clarity

Browse Source
This commit is contained in:
czlonkowski
2025-06-12 15:03:12 +02:00
parent 8bf670c31e
commit f831b02415
21 changed files with 1094 additions and 1841 deletions
Download Patch File Download Diff File Expand all files Collapse all files

326
README.md
View File

@@ -1,326 +0,0 @@
# n8n Node Documentation MCP Server
An MCP (Model Context Protocol) server that provides n8n node documentation, source code, and usage examples to AI assistants like Claude.
## Purpose
This MCP server serves as a comprehensive knowledge base for AI assistants to understand and work with n8n nodes. It provides:
- **Complete node source code** - The actual TypeScript/JavaScript implementation of each n8n node
- **Official documentation** - Markdown documentation from the n8n-docs repository
- **Usage examples** - Sample workflow JSON showing how to use each node
- **Search capabilities** - Full-text search across node names, descriptions, and documentation
## Features
- 🔍 **Full-text search** - Search nodes by name, description, or documentation content
- 📚 **Complete documentation** - Fetches and indexes official n8n documentation
- 💻 **Source code access** - Provides full source code for each node
- 🎯 **Usage examples** - Auto-generates example workflows for each node type
- 🔄 **Database rebuild** - Rebuilds the entire database with latest node information
- ⚡ **Fast SQLite storage** - All data stored locally for instant access
## Installation
### Prerequisites
- Node.js 18+
- Git (for cloning n8n-docs)
### Quick Start
```bash
# Clone the repository
git clone https://github.com/yourusername/n8n-mcp.git
cd n8n-mcp
# Install dependencies
npm install
# Copy environment configuration
cp .env.example .env
# Build the project
npm run build
# Initialize and rebuild the database with all nodes
npm run db:rebuild:v2
# Start the local MCP server (for Claude Desktop)
npm run start:v2
```
### Deployment Options
This MCP server can be deployed in two ways:
1. **Local Installation** - Run on your machine and connect Claude Desktop locally
2. **Remote Deployment** - Deploy to a VM/server and connect Claude Desktop over HTTPS
For remote deployment instructions, see [docs/REMOTE_DEPLOYMENT.md](docs/REMOTE_DEPLOYMENT.md).
## Installing in Claude Desktop
### 1. Build the project first
```bash
npm install
npm run build
npm run db:rebuild:v2 # This indexes all n8n nodes
```
### 2. Locate 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`
### 3. Edit the configuration file
```json
{
"mcpServers": {
"n8n-nodes": {
"command": "node",
"args": ["/absolute/path/to/n8n-mcp/dist/index-v2.js"],
"env": {
"NODE_DB_PATH": "/absolute/path/to/n8n-mcp/data/nodes-v2.db"
}
}
}
}
```
**Important**: Use absolute paths, not relative paths like `~/` or `./`
### 4. Restart Claude Desktop
After saving the configuration, completely quit and restart Claude Desktop.
### 5. Verify the connection
In Claude, you should see "n8n-nodes" in the MCP connections. Try asking:
- "What n8n nodes are available?"
- "Show me how to use the IF node in n8n"
- "Search for webhook nodes in n8n"
- "Show me the source code for the HTTP Request node"
### Remote Server Configuration
If you're connecting to a remote server instead of local installation:
```json
{
"mcpServers": {
"n8n-nodes-remote": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/client-http",
"https://n8ndocumentation.aiservices.pl/mcp"
],
"env": {
"MCP_AUTH_TOKEN": "your-auth-token-from-server"
}
}
}
}
```
Replace `n8ndocumentation.aiservices.pl` with your actual domain and use the auth token configured on your server.
## Available MCP Tools
### `list_nodes`
Lists all available n8n nodes with basic information.
- Parameters: `category`, `packageName`, `isTrigger` (all optional)
### `get_node_info`
Gets complete information about a specific node including source code, documentation, and examples.
- Parameters: `nodeType` (required) - e.g., "n8n-nodes-base.if", "If", "webhook"
### `search_nodes`
Searches for nodes by name, description, or documentation content.
- Parameters: `query` (required), `category`, `hasDocumentation`, `limit` (optional)
### `get_node_example`
Gets example workflow JSON for a specific node.
- Parameters: `nodeType` (required)
### `get_node_source_code`
Gets only the source code of a node.
- Parameters: `nodeType` (required), `includeCredentials` (optional)
### `get_node_documentation`
Gets only the documentation for a node.
- Parameters: `nodeType` (required), `format` (optional: "markdown" or "plain")
### `rebuild_database`
Rebuilds the entire node database with latest information.
- Parameters: `includeDocumentation` (optional, default: true)
### `get_database_statistics`
Gets statistics about the node database.
- No parameters required
## Example Usage
When you ask Claude about the IF node, it will use the MCP tools to provide:
```json
{
"nodeType": "n8n-nodes-base.if",
"name": "If",
"displayName": "If",
"description": "Route items based on comparison operations",
"sourceCode": "// Full TypeScript source code...",
"documentation": "# If Node\n\nThe If node splits a workflow...",
"exampleWorkflow": {
"nodes": [{
"parameters": {
"conditions": {
"conditions": [{
"leftValue": "={{ $json }}",
"rightValue": "",
"operator": {
"type": "object",
"operation": "notEmpty"
}
}]
}
},
"type": "n8n-nodes-base.if",
"position": [220, 120],
"name": "If"
}],
"connections": {
"If": {
"main": [[], []]
}
}
}
}
```
## Database Management
### Initial Setup
The database is automatically created when you run:
```bash
npm run db:rebuild:v2
```
This process:
1. Clones/updates the n8n-docs repository
2. Extracts source code from all n8n nodes
3. Fetches documentation for each node
4. Generates usage examples
5. Stores everything in SQLite with full-text search
### Manual Rebuild
To update the database with latest nodes:
```bash
npm run db:rebuild:v2
```
### Database Location
The SQLite database is stored at: `data/nodes-v2.db`
## Development
```bash
# Run in development mode (local stdio)
npm run dev:v2
# Run HTTP server for remote access
npm run dev:http
# Run tests
npm run test:v2
# Type checking
npm run typecheck
```
### Running Remote Server
To run the server for remote access:
```bash
# Copy and configure environment
cp .env.example .env
# Edit .env with your domain and auth token
# Run in production mode
npm run start:http
# Or with PM2 for production
pm2 start dist/index-http.js --name n8n-mcp
```
## Troubleshooting
### Claude Desktop doesn't show the MCP server
1. Ensure you've restarted Claude Desktop after editing the config
2. Check the config file is valid JSON (no trailing commas)
3. Verify the absolute paths are correct
4. Check Claude's developer console for errors (Help → Developer)
### "Connection failed" in Claude
1. Ensure the MCP server is built (`npm run build`)
2. Check that the database exists (`data/nodes-v2.db`)
3. Verify the NODE_DB_PATH in Claude config points to the correct database file
### Database rebuild fails
Some nodes may fail to extract (deprecated nodes, triggers without main node file). This is normal. The rebuild will continue and index all available nodes.
### No documentation for some nodes
Not all nodes have documentation in the n8n-docs repository. The server will still provide source code and generated examples for these nodes.
## Project Structure
```
n8n-mcp/
├── src/
│ ├── mcp/
│ │ ├── server-v2.ts # MCP server implementation
│ │ └── tools-v2.ts # MCP tool definitions
│ ├── services/
│ │ └── node-documentation-service.ts # Database service
│ ├── utils/
│ │ ├── documentation-fetcher.ts # n8n-docs fetcher
│ │ ├── example-generator.ts # Example generator
│ │ └── node-source-extractor.ts # Source extractor
│ └── scripts/
│ └── rebuild-database-v2.ts # Database rebuild
└── data/
└── nodes-v2.db # SQLite database
```
## License
This project is licensed under the [Sustainable Use License](LICENSE).
### What does this mean?
- ✅ **Free to use** for internal business purposes
- ✅ **Free to use** for personal/non-commercial projects
- ✅ **Free to modify** for your own use
- ✅ **Free to share** with others (non-commercially)
- ❌ **Cannot** host as a service for others
- ❌ **Cannot** include in commercial products without permission
This is a "fair-code" license similar to n8n's approach. See [LICENSE_FAQ.md](LICENSE_FAQ.md) for more details.
## Support
For issues and questions, please use the GitHub issue tracker.
For commercial licensing inquiries, please open an issue with the "licensing" tag.