{"_id":"@cmwen/min-n8n-mcp","_rev":"4-1593d44f8a3f2fe6ab4554eb7154f0b8","name":"@cmwen/min-n8n-mcp","dist-tags":{"latest":"1.0.2"},"versions":{"0.1.0":{"name":"@cmwen/min-n8n-mcp","version":"0.1.0","keywords":["mcp","n8n","workflow","automation","model-context-protocol"],"author":{"name":"cmwen"},"license":"MIT","_id":"@cmwen/min-n8n-mcp@0.1.0","maintainers":[{"name":"cmwen","email":"chungmin.wen@gmail.com"}],"homepage":"https://github.com/cmwen/min-n8n-mcp#readme","bugs":{"url":"https://github.com/cmwen/min-n8n-mcp/issues"},"bin":{"min-n8n-mcp":"dist/cli.js"},"dist":{"shasum":"2ca5cccc0cec547875d2194c3228369c4932975d","tarball":"https://registry.npmjs.org/@cmwen/min-n8n-mcp/-/min-n8n-mcp-0.1.0.tgz","fileCount":9,"integrity":"sha512-hz3GOsMHVmzf7uJuOna08a+qUK7IyrPEEve8meoWx5qinOeQlYTdHzZ8OOVee7VuK6D+0/edFvmWYTCzwHVALQ==","signatures":[{"sig":"MEYCIQDTLrzLfI12NJivU+AlZ3Fe+wFx8mQS8jZrPbPGoH/SQgIhANBcxLcityOETfru2zZrGwowqmgIMP12OUvhk7aRDqN5","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":709806},"main":"dist/index.js","type":"module","_from":"file:cmwen-min-n8n-mcp-0.1.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"scripts":{"dev":"tsx src/cli.ts --http --http-port 3000","lint":"biome check .","test":"vitest run","build":"tsup","test:ci":"pnpm test:unit && pnpm test:integration","lint:fix":"biome check . --fix","test:unit":"vitest run --config vitest.config.ts","test:watch":"vitest","type-check":"tsc --noEmit","test:coverage":"vitest run --coverage","test:security":"vitest run test/unit/security/","prepare-release":"./scripts/prepare-release.sh","test:integration":"vitest run --config vitest.integration.config.ts","test:performance":"vitest run test/integration/performance.test.ts","test:coverage:integration":"vitest run --config vitest.integration.config.ts --coverage"},"_npmUser":{"name":"cmwen","email":"chungmin.wen@gmail.com"},"_resolved":"/tmp/1439cec093fd0700be07ea99aac82c66/cmwen-min-n8n-mcp-0.1.0.tgz","_integrity":"sha512-hz3GOsMHVmzf7uJuOna08a+qUK7IyrPEEve8meoWx5qinOeQlYTdHzZ8OOVee7VuK6D+0/edFvmWYTCzwHVALQ==","repository":{"url":"git+https://github.com/cmwen/min-n8n-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Local MCP server for n8n workflow management","directories":{},"_nodeVersion":"18.20.8","dependencies":{"zod":"^3.22.0","pino":"^8.17.0","undici":"^6.6.0","express":"^5.1.0","commander":"^12.0.0","bottleneck":"^2.19.5","zod-to-json-schema":"^3.22.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","tsup":"^8.0.0","husky":"^9.0.0","vitest":"^1.2.0","typescript":"^5.3.0","@types/node":"^20.11.0","@biomejs/biome":"^1.5.0","@types/express":"^5.0.3","@vitest/coverage-v8":"^1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/min-n8n-mcp_0.1.0_1755779496465_0.3882932552821208","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@cmwen/min-n8n-mcp","version":"1.0.0","keywords":["mcp","n8n","workflow","automation","model-context-protocol"],"author":{"name":"cmwen"},"license":"MIT","_id":"@cmwen/min-n8n-mcp@1.0.0","maintainers":[{"name":"cmwen","email":"chungmin.wen@gmail.com"}],"homepage":"https://github.com/cmwen/min-n8n-mcp#readme","bugs":{"url":"https://github.com/cmwen/min-n8n-mcp/issues"},"bin":{"min-n8n-mcp":"dist/cli.js"},"dist":{"shasum":"c0ae41bb8fe6b3ea48580c6591b9ec22d4462669","tarball":"https://registry.npmjs.org/@cmwen/min-n8n-mcp/-/min-n8n-mcp-1.0.0.tgz","fileCount":9,"integrity":"sha512-lNVepXPR9wscQwahbbAIYIYWLA/P430dHC0wUAtU2q6VtWJ24lb8QTI5uIgxpf+qNnH2pUJOMvwxzcHJDB9AHA==","signatures":[{"sig":"MEQCIH2tGNT7ab5VTdHPT1mEtyn7DzaC3l7dFq01s2gnRwiXAiBeqL2AqsQFwTT4vgENRQ+uat9hia1urcQJcu7Foh9GZA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":719156},"main":"dist/index.js","type":"module","_from":"file:cmwen-min-n8n-mcp-1.0.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"scripts":{"dev":"tsx src/cli.ts --http --http-port 3000","lint":"biome check .","test":"vitest run","build":"tsup","test:ci":"pnpm test:unit && pnpm test:integration","lint:fix":"biome check . --fix","test:unit":"vitest run --config vitest.config.ts","test:watch":"vitest","type-check":"tsc --noEmit","test:coverage":"vitest run --coverage","test:security":"vitest run test/unit/security/","prepare-release":"./scripts/prepare-release.sh","test:integration":"vitest run --config vitest.integration.config.ts","test:performance":"vitest run test/integration/performance.test.ts","test:coverage:integration":"vitest run --config vitest.integration.config.ts --coverage"},"_npmUser":{"name":"cmwen","email":"chungmin.wen@gmail.com"},"_resolved":"/tmp/f636b31e95f87ea4492f997d93f93041/cmwen-min-n8n-mcp-1.0.0.tgz","_integrity":"sha512-lNVepXPR9wscQwahbbAIYIYWLA/P430dHC0wUAtU2q6VtWJ24lb8QTI5uIgxpf+qNnH2pUJOMvwxzcHJDB9AHA==","repository":{"url":"git+https://github.com/cmwen/min-n8n-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Local MCP server for n8n workflow management","directories":{},"_nodeVersion":"18.20.8","dependencies":{"zod":"^3.22.0","pino":"^8.17.0","undici":"^6.6.0","express":"^5.1.0","commander":"^12.0.0","bottleneck":"^2.19.5","zod-to-json-schema":"^3.22.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","tsup":"^8.0.0","husky":"^9.0.0","vitest":"^1.2.0","typescript":"^5.3.0","@types/node":"^20.11.0","@biomejs/biome":"^1.5.0","@types/express":"^5.0.3","@vitest/coverage-v8":"^1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/min-n8n-mcp_1.0.0_1759835568282_0.6565378600903533","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@cmwen/min-n8n-mcp","version":"1.0.1","keywords":["mcp","n8n","workflow","automation","model-context-protocol"],"author":{"name":"cmwen"},"license":"MIT","_id":"@cmwen/min-n8n-mcp@1.0.1","maintainers":[{"name":"cmwen","email":"chungmin.wen@gmail.com"}],"homepage":"https://github.com/cmwen/min-n8n-mcp#readme","bugs":{"url":"https://github.com/cmwen/min-n8n-mcp/issues"},"bin":{"min-n8n-mcp":"dist/cli.js"},"dist":{"shasum":"a861e7b30bf5695146eeb64866e0f25d5e6f289b","tarball":"https://registry.npmjs.org/@cmwen/min-n8n-mcp/-/min-n8n-mcp-1.0.1.tgz","fileCount":9,"integrity":"sha512-dG3rfsJJpG6ANiYbQFnpC+Lcnj4c0ELKYLrFjkFLUf0eEHMxjB1/0kMX+IW0Ah4i+dzxf6C8zlOSI3uTi4J7lA==","signatures":[{"sig":"MEUCIEt1rV+UMCzP6ffGcRdzo/JkvKkt3wLnUVAnFAEmPmsqAiEAhzPOX+OewuGoqHW6UJ8GjAOixMflN99EPAoPakLKV7E=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":726879},"main":"dist/index.js","type":"module","_from":"file:cmwen-min-n8n-mcp-1.0.1.tgz","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"scripts":{"dev":"tsx src/cli.ts --http --http-port 3000","lint":"biome check .","test":"vitest run","build":"tsup","test:ci":"pnpm test:unit && pnpm test:integration","lint:fix":"biome check . --fix","test:unit":"vitest run --config vitest.config.ts","test:watch":"vitest","type-check":"tsc --noEmit","test:coverage":"vitest run --coverage","test:security":"vitest run test/unit/security/","prepare-release":"./scripts/prepare-release.sh","test:integration":"vitest run --config vitest.integration.config.ts","test:performance":"vitest run test/integration/performance.test.ts","test:coverage:integration":"vitest run --config vitest.integration.config.ts --coverage"},"_npmUser":{"name":"cmwen","email":"chungmin.wen@gmail.com"},"_resolved":"/tmp/5cf4e4cdd22bfb3aa364d8d440956183/cmwen-min-n8n-mcp-1.0.1.tgz","_integrity":"sha512-dG3rfsJJpG6ANiYbQFnpC+Lcnj4c0ELKYLrFjkFLUf0eEHMxjB1/0kMX+IW0Ah4i+dzxf6C8zlOSI3uTi4J7lA==","repository":{"url":"git+https://github.com/cmwen/min-n8n-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Local MCP server for n8n workflow management","directories":{},"_nodeVersion":"18.20.8","dependencies":{"zod":"^3.22.0","pino":"^8.17.0","undici":"^6.6.0","express":"^5.1.0","commander":"^12.0.0","bottleneck":"^2.19.5","zod-to-json-schema":"^3.22.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","tsup":"^8.0.0","husky":"^9.0.0","vitest":"^1.2.0","typescript":"^5.3.0","@types/node":"^20.11.0","@biomejs/biome":"^1.5.0","@types/express":"^5.0.3","@vitest/coverage-v8":"^1.2.0"},"_npmOperationalInternal":{"tmp":"tmp/min-n8n-mcp_1.0.1_1760252699072_0.6359781655889434","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@cmwen/min-n8n-mcp","version":"1.0.2","description":"Local MCP server for n8n workflow management","main":"dist/index.js","bin":{"min-n8n-mcp":"dist/cli.js"},"type":"module","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","bottleneck":"^2.19.5","commander":"^12.0.0","express":"^5.1.0","pino":"^8.17.0","undici":"^6.6.0","zod":"^3.22.0","zod-to-json-schema":"^3.22.0"},"devDependencies":{"@biomejs/biome":"^2.2.6","@types/express":"^5.0.3","@types/node":"^20.11.0","@vitest/coverage-v8":"^1.2.0","husky":"^9.0.0","tsup":"^8.0.0","tsx":"^4.7.0","typescript":"^5.3.0","vitest":"^1.2.0"},"keywords":["mcp","n8n","workflow","automation","model-context-protocol"],"author":{"name":"cmwen"},"repository":{"type":"git","url":"git+https://github.com/cmwen/min-n8n-mcp.git"},"bugs":{"url":"https://github.com/cmwen/min-n8n-mcp/issues"},"homepage":"https://github.com/cmwen/min-n8n-mcp#readme","license":"MIT","publishConfig":{"access":"public"},"scripts":{"build":"tsup","dev":"tsx src/cli.ts --http --http-port 3000","lint":"biome check .","lint:fix":"biome check . --fix","test":"vitest run","test:watch":"vitest","test:unit":"vitest run --config vitest.config.ts","test:integration":"vitest run --config vitest.integration.config.ts","test:coverage":"vitest run --coverage","test:coverage:integration":"vitest run --config vitest.integration.config.ts --coverage","test:ci":"pnpm test:unit && pnpm test:integration","test:security":"vitest run test/unit/security/","test:performance":"vitest run test/integration/performance.test.ts","type-check":"tsc --noEmit","prepare-release":"./scripts/prepare-release.sh"},"_id":"@cmwen/min-n8n-mcp@1.0.2","types":"./dist/index.d.ts","_integrity":"sha512-Cw2br5WBqjPtUBdoL4R/ZV6I1FMs9kMdf6uhhG6+mbl6r/kMJc5+7HT65uyCEXeutJKHEDe+DuZDlM9CymF9Zw==","_resolved":"/tmp/486a8b8108780afe9bbbb1055dfa43bd/cmwen-min-n8n-mcp-1.0.2.tgz","_from":"file:cmwen-min-n8n-mcp-1.0.2.tgz","_nodeVersion":"18.20.8","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Cw2br5WBqjPtUBdoL4R/ZV6I1FMs9kMdf6uhhG6+mbl6r/kMJc5+7HT65uyCEXeutJKHEDe+DuZDlM9CymF9Zw==","shasum":"8cb68755b6ad0aa76b90e7d216d1d9b87c121cd9","tarball":"https://registry.npmjs.org/@cmwen/min-n8n-mcp/-/min-n8n-mcp-1.0.2.tgz","fileCount":9,"unpackedSize":720632,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIH4Do+MmaDNkajglpIkMh2hr/5VgQbKjAN8+Dqy4XVbVAiBouoQ2SRsScbQMy+ulvpM4f9R6PUHt8D9YvfIbLOT1TQ=="}]},"_npmUser":{"name":"cmwen","email":"chungmin.wen@gmail.com"},"directories":{},"maintainers":[{"name":"cmwen","email":"chungmin.wen@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/min-n8n-mcp_1.0.2_1760490290220_0.5703205918769285"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-21T12:31:36.038Z","modified":"2025-10-15T01:04:50.713Z","0.1.0":"2025-08-21T12:31:36.729Z","1.0.0":"2025-10-07T11:12:48.512Z","1.0.1":"2025-10-12T07:04:59.274Z","1.0.2":"2025-10-15T01:04:50.517Z"},"bugs":{"url":"https://github.com/cmwen/min-n8n-mcp/issues"},"author":{"name":"cmwen"},"license":"MIT","homepage":"https://github.com/cmwen/min-n8n-mcp#readme","keywords":["mcp","n8n","workflow","automation","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/cmwen/min-n8n-mcp.git"},"description":"Local MCP server for n8n workflow management","maintainers":[{"name":"cmwen","email":"chungmin.wen@gmail.com"}],"readme":"# @cmwen/min-n8n-mcp\n\n> Local n8n MCP (Model Context Protocol) server that provides AI agents programmatic access to n8n workflows via REST API.\n\n[![npm version](https://badge.fury.io/js/@cmwen%2Fmin-n8n-mcp.svg)](https://www.npmjs.com/package/@cmwen/min-n8n-mcp)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Overview\n\n**@cmwen/min-n8n-mcp** is a TypeScript-based MCP server that exposes n8n workflow management capabilities as callable tools for AI agents and LLMs. It acts as a thin, typed proxy to your n8n instance's REST API, enabling programmatic workflow automation through the Model Context Protocol.\n\n### Key Features\n\n- 🤖 **MCP Integration**: Full support for Model Context Protocol with tool discovery and schema validation\n- 🔄 **Dual Mode Operation**: Both STDIO (default) and HTTP modes for different use cases\n- 🛡️ **Robust Error Handling**: Comprehensive error mapping, retries, and timeouts\n- 📊 **Complete n8n API Coverage**: Workflows, executions, credentials, users, projects, and more\n- 🎯 **Type Safety**: Full TypeScript support with Zod schema validation\n- 🚀 **Zero Configuration**: Works out of the box with minimal setup\n- 🔍 **MCP Inspector Compatible**: HTTP mode supports MCP Inspector for debugging\n\n## Quick Start\n\n### Installation\n\n```bash\n# Run directly with npx (recommended)\nnpx @cmwen/min-n8n-mcp\n\n# Or install globally\nnpm install -g @cmwen/min-n8n-mcp\nmin-n8n-mcp\n```\n\n### Prerequisites\n\n- **Node.js**: >=18.0.0 (uses built-in fetch)\n- **n8n Instance**: Local or remote n8n server with API access\n- **API Token**: n8n API key for authentication ([How to get your API token](docs/TROUBLESHOOTING.md#getting-your-n8n-api-token))\n\n### Basic Usage\n\n**⚠️ Important:** Both `N8N_API_URL` and `N8N_API_TOKEN` are required. The server will fail immediately with helpful error messages if either is missing.\n\n1. **Set Environment Variables**:\n```bash\nexport N8N_API_URL=\"http://localhost:5678\"  # Your n8n instance URL\nexport N8N_API_TOKEN=\"your-api-token-here\"  # Your n8n API token\n```\n\n2. **Start in STDIO Mode** (default, for agent integration):\n```bash\nnpx @cmwen/min-n8n-mcp\n```\n\n3. **Start in HTTP Mode** (for MCP Inspector/debugging):\n```bash\nnpx @cmwen/min-n8n-mcp --http --http-port 3000\n```\n\n### Quick Validation\n\n```bash\n# Verify configuration (token will be redacted in output)\nN8N_API_URL=\"http://localhost:5678\" \\\nN8N_API_TOKEN=\"your-token\" \\\nnpx @cmwen/min-n8n-mcp --print-config\n```\n\n## Communication Modes\n\n### STDIO Mode (Default)\n- **Use Case**: Agent/LLM integration, CLI usage\n- **Protocol**: Standard input/output streams\n- **Best For**: Production environments, automated workflows\n\n### HTTP Mode\n- **Use Case**: Development, debugging, MCP Inspector compatibility\n- **Protocol**: HTTP endpoint (localhost:port)\n- **Best For**: Testing, visual debugging with MCP Inspector\n\n## Operating Modes\n\nThe MCP server offers three operating modes to balance functionality with performance, reducing LLM confusion and data verbosity:\n\n### Intermediate Mode (Default)\n- **Tools**: 15+ essential tools covering workflow management, executions, credentials, and tags\n- **Data Filtering**: Returns streamlined data with metadata but excludes verbose node/connection definitions\n- **Best For**: Most use cases requiring workflow automation with manageable tool count\n\n### Basic Mode\n- **Tools**: 7 essential tools for simple workflow operations (list, get, run, activate/deactivate)\n- **Data Filtering**: Returns only essential fields (ID, name, status, tags) reducing payload by ~50%\n- **Best For**: Simple workflow management with minimal tool exposure\n\n### Advanced Mode\n- **Tools**: Complete API access with 30+ tools covering all n8n operations\n- **Data Filtering**: No filtering - returns complete data unchanged\n- **Best For**: Complex automation requiring full n8n API capabilities\n\n### Usage Examples\n\n```bash\n# Use default intermediate mode\nnpx @cmwen/min-n8n-mcp\n\n# Specify mode explicitly\nnpx @cmwen/min-n8n-mcp --mode basic\nnpx @cmwen/min-n8n-mcp --mode intermediate\nnpx @cmwen/min-n8n-mcp --mode advanced\n\n# Via environment variable\nMCP_MODE=basic npx @cmwen/min-n8n-mcp\n```\n\n## Available Tools\n\nThe MCP server exposes comprehensive n8n management capabilities through the following tool categories:\n\n### Workflow Management\n- `listWorkflows` - List all workflows with filtering\n- `getWorkflow` - Get workflow details by ID\n- `createWorkflow` - Create new workflows\n- `updateWorkflow` - Update existing workflows\n- `deleteWorkflow` - Delete workflows\n- `activateWorkflow` - Activate workflows\n- `deactivateWorkflow` - Deactivate workflows\n- `getWorkflowTags` - Get workflow tags\n- `updateWorkflowTags` - Update workflow tags\n- `transferWorkflow` - Transfer workflows between projects\n\n### Execution Management\n- `listExecutions` - List workflow executions\n- `getExecution` - Get execution details\n- `deleteExecution` - Delete executions\n\n### Credential Management\n- `createCredential` - Create new credentials\n- `deleteCredential` - Delete credentials\n- `getCredentialType` - Get credential type schemas\n- `transferCredential` - Transfer credentials between projects\n\n### User & Project Management\n- `listUsers` - List users\n- `createUser` - Create new users\n- `getUser` - Get user details\n- `deleteUser` - Delete users\n- `changeUserRole` - Change user roles\n- `listProjects` - List projects\n- `createProject` - Create new projects\n- `updateProject` - Update projects\n- `deleteProject` - Delete projects\n- `addUsersToProject` - Add users to projects\n- `deleteUserFromProject` - Remove users from projects\n- `changeUserRoleInProject` - Change user roles in projects\n\n### Tag & Variable Management\n- `createTag` - Create tags\n- `listTags` - List tags\n- `getTag` - Get tag details\n- `updateTag` - Update tags\n- `deleteTag` - Delete tags\n- `createVariable` - Create variables\n- `listVariables` - List variables\n- `updateVariable` - Update variables\n- `deleteVariable` - Delete variables\n\n### Advanced Features\n- `generateAudit` - Generate audit reports\n- `pullSourceControl` - Pull from source control\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `N8N_API_URL` | n8n instance URL | - | ✅ |\n| `N8N_API_TOKEN` | n8n API token | - | ✅ |\n| `MCP_MODE` | Operating mode (basic\\|intermediate\\|advanced) | `intermediate` | ❌ |\n| `LOG_LEVEL` | Logging level | `info` | ❌ |\n| `HTTP_TIMEOUT_MS` | Request timeout | `30000` | ❌ |\n| `HTTP_RETRIES` | Retry attempts | `2` | ❌ |\n| `CONCURRENCY` | Concurrent requests | `4` | ❌ |\n\n### CLI Options\n\n```bash\nOptions:\n  --url <string>           n8n API URL (overrides N8N_API_URL)\n  --token <string>         n8n API token (overrides N8N_API_TOKEN)\n  --mode <mode>            Tool exposure mode (basic|intermediate|advanced, default: intermediate)\n  --http                   Enable HTTP mode\n  --http-port <number>     HTTP mode port (default: 3000)\n  --log-level <level>      Log level (debug|info|warn|error)\n  --timeout <ms>           HTTP timeout in milliseconds\n  --retries <number>       Number of retry attempts\n  --concurrency <number>   Maximum concurrent requests\n  --print-config           Print configuration and exit\n  -h, --help               Display help\n```\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/cmwen/min-n8n-mcp.git\ncd min-n8n-mcp\n\n# Install pnpm globally (required)\nnpm install -g pnpm\n\n# Install dependencies (takes ~2.5 minutes on first run)\npnpm install\n\n# Build the project\npnpm build\n```\n\n### Development Commands\n\n```bash\n# Run in development mode\npnpm dev\n\n# Run with configuration check\nN8N_API_URL=http://localhost:5678 N8N_API_TOKEN=test pnpm dev --print-config\n\n# Type checking\npnpm type-check\n\n# Linting and formatting\npnpm lint\npnpm lint:fix\n\n# Testing\npnpm test\n```\n\n### Project Structure\n\n```\nsrc/\n├── cli.ts              # CLI entry point\n├── server.ts           # MCP server bootstrap\n├── config.ts           # Configuration management\n├── logging.ts          # Structured logging\n├── http/               # HTTP client infrastructure\n├── resources/          # n8n API resource clients\n├── tools/              # MCP tool implementations\n├── schemas/            # Zod validation schemas\n└── util/               # Utilities (pagination, cache)\n```\n\n## Error Handling\n\nThe server includes comprehensive error handling with:\n\n- **HTTP Error Mapping**: 400/401/403/404/409/5xx → appropriate MCP errors\n- **Retry Logic**: Exponential backoff for transient failures\n- **Timeout Protection**: Configurable request timeouts\n- **Secret Redaction**: API tokens automatically redacted from logs\n- **Detailed Error Context**: Full error details available for debugging\n\n## Security\n\n- API tokens loaded from environment only (never persisted)\n- Automatic secret redaction in logs and error messages\n- HTTPS recommended for remote n8n instances\n- Request/response body logging disabled by default for credential endpoints\n\n## Testing\n\n```bash\n# Run all tests\npnpm test\n\n# Run specific test categories\npnpm test:unit           # Unit tests\npnpm test:integration    # Integration tests\npnpm test:e2e           # End-to-end tests\n```\n\n## Performance\n\n- **Concurrent Request Limiting**: Prevents resource exhaustion\n- **Intelligent Caching**: TTL cache for low-volatility data\n- **Pagination Support**: Auto-pagination options available\n- **Connection Pooling**: Efficient HTTP client with keep-alive\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Configuration validation failed**\n   - Ensure both `N8N_API_URL` and `N8N_API_TOKEN` are set\n   - The server provides detailed error messages with setup instructions\n   - See [Troubleshooting Guide](docs/TROUBLESHOOTING.md#configuration-issues)\n\n2. **\"Cannot connect to n8n API\"**\n   - Verify n8n is running and accessible: `curl http://localhost:5678/healthz`\n   - Check firewall/network settings\n   - See [Troubleshooting Guide](docs/TROUBLESHOOTING.md#connection-issues)\n\n3. **\"pnpm not found\"** (development only)\n   ```bash\n   npm install -g pnpm\n   ```\n\n4. **\"Unauthorized\" or \"Invalid API token\"**\n   - Verify API token is correct\n   - Generate new token in n8n Settings > API\n   - See [Troubleshooting Guide](docs/TROUBLESHOOTING.md#authentication-issues)\n\n5. **\"keyValidator._parse is not a function\"**\n   - This was a known issue that has been fixed\n   - Update to latest version: `npx @cmwen/min-n8n-mcp@latest`\n\nFor comprehensive troubleshooting, see **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)**.\n\n### Debug Mode\n\n```bash\n# Enable debug logging\nLOG_LEVEL=debug npx @cmwen/min-n8n-mcp\n\n# Print configuration without starting server\nnpx @cmwen/min-n8n-mcp --print-config\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`pnpm test`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\nFor a deeper walkthrough of project structure, workflows, and expectations, read the [Repository Guidelines](AGENTS.md).\n\n### Development Guidelines\n\n- Follow TypeScript strict mode\n- Use Biome for linting/formatting (configured in `biome.json`)\n- Add tests for new features\n- Update documentation as needed\n- Follow conventional commit format\n\n## Implementation Status\n\nThis project follows a staged implementation approach:\n\n- ✅ **Stage 1**: Foundation Setup (CLI, config, build tooling)\n- ✅ **Stage 2**: HTTP Client Infrastructure\n- ✅ **Stage 3**: MCP Server Core\n- ✅ **Stage 4**: Resource Clients\n- ✅ **Stage 5**: Tool Implementation\n- ✅ **Stage 6**: Critical Bug Fixes (MCP tool validation)\n- 🚧 **Stage 7**: Testing & Quality Assurance\n- ⏳ **Stage 8**: Documentation & Release\n\n**Recent Update**: Fixed critical MCP tool validation issue that prevented tools from working with MCP SDK v1.17.2.\n\nSee [Implementation Roadmap](docs/IMPLEMENTATION_ROADMAP.md) for detailed progress.\n\n## API Documentation\n\nFor detailed information, see:\n- **[Usage Examples](docs/EXAMPLES.md)** - Comprehensive examples for all use cases\n- **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Solve common issues\n- **[Known Limitations](docs/KNOWN_LIMITATIONS.md)** - API coverage and missing features\n- **[Technical Design](docs/TECHNICAL_DESIGN.md)** - Architecture and implementation details\n- **[Product Requirements](docs/PRD.md)** - Complete tool specifications\n- **[OpenAPI Specification](docs/openapi.yml)** - n8n API reference\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- 📖 **Documentation**: Check the [docs](docs/) directory\n- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/cmwen/min-n8n-mcp/issues)\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/cmwen/min-n8n-mcp/discussions)\n- 📧 **Contact**: [Create an issue](https://github.com/cmwen/min-n8n-mcp/issues/new)\n\n## Related Projects\n\n- [n8n](https://n8n.io/) - Workflow automation platform\n- [Model Context Protocol](https://modelcontextprotocol.io/) - Protocol for AI agent tool integration\n- [MCP Inspector](https://github.com/modelcontextprotocol/inspector) - Tool for debugging MCP servers\n","readmeFilename":"README.md"}