openapi-to-n8n

v1.0.5

Published

9 months ago

Convert OpenAPI specifications to n8n custom nodes - A no-code Middleware Control Platform

0High
0Medium
0Low

abnerjezweb

n8n openapi swagger workflow automation no-code api integration middleware mcp

OpenAPI to n8n MCP

A powerful CLI tool and Model Context Protocol (MCP) server that automatically converts OpenAPI specifications into fully functional n8n custom nodes. Generate TypeScript-based n8n nodes, credentials, and workflow templates from any OpenAPI v3+ specification.

Features

🚀 Automatic Node Generation: Convert any OpenAPI spec to n8n nodes in seconds
🤖 MCP Server: Use with Claude Desktop and other MCP-compatible AI assistants
🔐 Auth Support: Handles API Key, Bearer Token, Basic Auth, and OAuth2
📝 TypeScript Support: Generates type-safe n8n nodes
🔄 CRUD Workflows: Auto-generate workflow templates for common operations
📦 NPM Publishing: Ready-to-publish package structure
🎨 Customizable: Configure node appearance, behavior, and metadata
🌐 Registry Support: Share and version your generated nodes
🛡️ Security First: Built-in security validation and best practices

Installation

Global Installation

npm install -g openapi-to-n8n

Using npx (no installation required)

npx openapi-to-n8n generate ./api-spec.yaml

Local Development

git clone https://github.com/abnercalapiz/openapi-to-n8n.git
cd openapi-to-n8n
npm install
npm run build
npm link

Quick Start

1. Generate n8n Nodes

# Generate from local file
openapi-to-n8n generate ./petstore.yaml -o ./my-petstore-node

# Generate from URL
openapi-to-n8n generate https://api.example.com/openapi.json -o ./my-api-node

# Generate with custom settings
openapi-to-n8n generate ./api.yaml \
  --output ./custom-node \
  --name "MyCustomAPI" \
  --color "#FF6B6B" \
  --icon ./icon.svg

2. Validate OpenAPI Spec

openapi-to-n8n validate ./api.yaml

3. Generate CRUD Workflows

openapi-to-n8n workflow ./api.yaml -o ./workflows

4. Test Generated Node

# Copy to n8n custom nodes folder
cp -r ./my-node ~/.n8n/custom/

# Or link for development
cd ./my-node && npm link
cd ~/.n8n/custom && npm link my-node

MCP Server Usage

Setup with Claude Desktop

Install the package globally:
```
npm install -g openapi-to-n8n
```
Add to Claude Desktop configuration:
Edit your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
```
{
  "mcpServers": {
    "openapi-to-n8n": {
      "command": "npx",
      "args": ["openapi-to-n8n-mcp"]
    }
  }
}
```
Restart Claude Desktop

MCP Tools Available

generate-node: Generate n8n nodes from OpenAPI specs
validate-spec: Validate OpenAPI specifications
generate-workflow: Create workflow templates
convert-from-file: Convert local OpenAPI files

Example MCP Usage

Once connected, you can use natural language commands in Claude:

"Validate the OpenAPI spec at /path/to/api.yaml"
"Generate an n8n node from https://api.example.com/openapi.json"
"Convert this OpenAPI spec to an n8n node with TypeScript"
"Create workflow templates from the API specification"

Usage Examples

Basic Example

# api.yaml
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      operationId: getUsers
      summary: Get all users
      responses:
        200:
          description: Success

openapi-to-n8n generate api.yaml

Advanced Example with Auth

openapi: 3.0.0
info:
  title: Secure API
  version: 2.0.0
  x-n8n-node-name: SecureAPI
  x-n8n-node-color: "#1A82E2"
servers:
  - url: https://api.secure.com
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
paths:
  /data:
    get:
      operationId: getData
      summary: Get secure data

Programmatic Usage

import { OpenAPIToN8n } from 'openapi-to-n8n';

const converter = new OpenAPIToN8n();

async function generateNode() {
  const result = await converter.generate('./api.yaml', {
    outputDir: './generated',
    nodeName: 'MyAPI',
    typescript: true,
    generateCredentials: true,
    generateWorkflows: true,
  });

  console.log(`Node generated at: ${result.outputPath}`);
}

CLI Commands

`generate`

Generate n8n nodes from OpenAPI specification.

openapi-to-n8n generate <openapi-file> [options]

Options:
  -o, --output <dir>        Output directory (default: "./generated")
  -n, --name <name>         Node name (defaults to API title)
  --no-typescript           Generate JavaScript instead of TypeScript
  --no-credentials          Skip credentials generation
  --icon <path>            Path to node icon
  --color <color>          Node color (default: "#1A82E2")
  --category <category>    Node category (default: "Development")
  --overwrite              Overwrite existing files

`validate`

Validate OpenAPI specification.

openapi-to-n8n validate <openapi-file> [options]

Options:
  --strict                 Enable strict validation
  --format <format>        Output format: text|json (default: "text")

`workflow`

Generate CRUD workflow templates.

openapi-to-n8n workflow <openapi-file> [options]

Options:
  -o, --output <dir>       Output directory (default: "./workflows")
  --format <format>        Workflow format: json|yaml (default: "json")
  --split                  Generate separate files for each operation
  --include-auth           Include authentication nodes

`publish`

Publish generated node to registry.

openapi-to-n8n publish <node-dir> [options]

Options:
  --registry <url>         Registry URL
  --token <token>          Authentication token
  --dry-run                Perform dry run
  --tag <tag>              Version tag (default: "latest")

Publishing to NPM

Manual Publishing

Prepare your node:

cd ./generated/my-node
npm init -y
npm version 1.0.0

Test locally:

npm link
cd ~/.n8n/custom && npm link my-node

Publish to NPM:
```
npm login
npm publish
```

Automated Publishing

Setup GitHub Actions:

# .github/workflows/publish.yml
name: Publish
on:
  release:
    types: [published]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: npm ci
      - run: npm run build
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

Configure NPM token:
- Get token from npmjs.com
- Add as NPM_TOKEN in GitHub secrets
Create release:
```
git tag v1.0.0
git push origin v1.0.0
```

Node Registry

Publishing to Registry

# Publish to default registry
openapi-to-n8n publish ./my-node

# Publish to custom registry
openapi-to-n8n publish ./my-node \
  --registry https://registry.n8n.io \
  --token YOUR_TOKEN

Using Registry Nodes

# Search for nodes
openapi-to-n8n search "weather api"

# Install from registry
openapi-to-n8n install weather-api@latest

Security Best Practices

API Credentials

Never commit credentials to version control
Use environment variables for sensitive data
Implement credential rotation
Use n8n's built-in credential encryption

OpenAPI Validation

# Validate with security checks
openapi-to-n8n validate api.yaml --strict

# Security report
openapi-to-n8n security api.yaml

Secure Node Generation

// Use secure defaults
const options = {
  validateSSL: true,
  sanitizeInputs: true,
  rateLimiting: true,
  timeout: 30000,
};

Configuration

Global Config

# Set default author
openapi-to-n8n config set author "Your Name"

# Set default registry
openapi-to-n8n config set registry "https://registry.n8n.io"

# View config
openapi-to-n8n config list

Project Config

// .openapi-to-n8n.json
{
  "defaults": {
    "output": "./nodes",
    "typescript": true,
    "color": "#FF6B6B",
    "category": "Custom APIs"
  },
  "registry": {
    "url": "https://registry.n8n.io",
    "publish": {
      "access": "public",
      "tag": "latest"
    }
  }
}

Advanced Features

Custom Templates

# Use custom templates
openapi-to-n8n generate api.yaml \
  --template ./my-templates \
  --helper ./my-helpers.js

Batch Processing

# Process multiple specs
find ./specs -name "*.yaml" -exec openapi-to-n8n generate {} \;

# With parallel processing
ls ./specs/*.yaml | parallel -j 4 openapi-to-n8n generate {}

CI/CD Integration

# GitHub Actions example
- name: Generate n8n Nodes
  uses: openapi-to-n8n/action@v1
  with:
    spec: ./api.yaml
    output: ./generated
    publish: true
    npm-token: ${{ secrets.NPM_TOKEN }}

Troubleshooting

Common Issues

Module not found:
```
npm install -g openapi-to-n8n
```
Permission denied:
```
sudo npm install -g openapi-to-n8n
```

Invalid OpenAPI spec:

openapi-to-n8n validate api.yaml --strict

Debug Mode

# Enable debug logging
DEBUG=openapi-to-n8n:* openapi-to-n8n generate api.yaml

# Verbose output
openapi-to-n8n generate api.yaml --verbose

Contributing

We welcome contributions! Please see our Contributing Guide.

Development Setup

# Clone repo
git clone https://github.com/abnercalapiz/openapi-to-n8n.git
cd openapi-to-n8n

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Link for testing
npm link

Submitting PRs

Fork the repository
Create feature branch (git checkout -b feature/amazing)
Commit changes (git commit -m 'Add amazing feature')
Push branch (git push origin feature/amazing)
Open Pull Request

License

Support

🐛 Issues: GitHub Issues
📦 NPM: Package Page
💻 GitHub: Repository

Acknowledgments

n8n - Workflow automation platform
OpenAPI Initiative - API specification
Contributors and community members

Made with ❤️ by Jezweb