n8n-workflow-downloader-mcp

n8n Workflow Downloader MCP Server

An MCP (Model Context Protocol) server that enables AI agents to download n8n workflows from URLs.

Features

• Download n8n workflows from URLs like https://n8n.io/workflows/3442
• Returns the complete workflow JSON structure
• Includes metadata (workflow ID, name, URL)
• Handles errors gracefully

Installation

As a global npm package

npm install -g n8n-workflow-downloader-mcp

For development

git clone https://github.com/andrewlwn77/n8n-workflow-downloader-mcp.git
cd n8n-workflow-downloader-mcp
npm install
npm run build

Usage

With Claude Desktop or other MCP clients

Add to your MCP configuration:

Using npx (recommended):

{
  "mcpServers": {
    "n8n-workflow-downloader": {
      "command": "npx",
      "args": ["n8n-workflow-downloader-mcp"],
      "transport": {
        "type": "stdio"
      },
      "env": {
        "PUPPETEER_EXECUTABLE_PATH": "/opt/google/chrome/google-chrome"
      }
    }
  }
}

If installed globally via npm:

{
  "mcpServers": {
    "n8n-workflow-downloader": {
      "command": "n8n-workflow-downloader",
      "transport": {
        "type": "stdio"
      },
      "env": {
        "PUPPETEER_EXECUTABLE_PATH": "/opt/google/chrome/google-chrome"
      }
    }
  }
}

If installed locally or from source:

{
  "mcpServers": {
    "n8n-workflow-downloader": {
      "command": "node",
      "args": ["./path/to/build/index.js"],
      "transport": {
        "type": "stdio"
      },
      "env": {
        "PUPPETEER_EXECUTABLE_PATH": "/opt/google/chrome/google-chrome"
      }
    }
  }
}

Environment Variables

• PUPPETEER_EXECUTABLE_PATH (optional): Path to Chrome/Chromium executable
  • If not set, Puppeteer will use its bundled Chromium
  • Useful for systems with Chrome installed in non-standard locations
  • Example: /opt/google/chrome/google-chrome, /usr/bin/chromium-browser

Available Tools

download_n8n_workflow

Downloads an n8n workflow from a given URL.

Input:

• url (string, required): The n8n workflow URL (e.g., https://n8n.io/workflows/3442)

Output:

• workflow: The complete n8n workflow JSON object
• metadata: Object containing:
  • id: The workflow ID
  • name: The workflow name
  • url: The original URL

Example usage in Claude:

Please download the n8n workflow from https://n8n.io/workflows/3442

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

# Run tests
npm test

# Run specific test suites
npm run test:unit        # Unit tests only
npm run test:integration # Integration tests only

# Run tests in watch mode
npm run test:watch

# Generate test coverage report
npm run test:coverage

# Test the server manually (for debugging/development)
node test-server.js

Testing

The project includes comprehensive test coverage:

• Unit Tests (tests/unit/): Test individual modules in isolation

  • Downloader module validation and error handling
  • URL parsing and validation
  • Mock puppeteer interactions

• Integration Tests (tests/integration/): Test the complete MCP server

  • Server initialization
  • Tool listing and discovery
  • End-to-end workflow download simulation
  • Error handling and validation

Run npm test to execute all tests, or use the specific test commands listed above.

Manual Testing

The test-server.js script provides a quick way to manually test the MCP server:

• Initializes the server
• Lists available tools
• Demonstrates a tool call
• Shows real-time server output

This is useful for debugging and development, complementing the automated test suite.

Technical Details

• Uses Puppeteer to automate the workflow download process
• Intercepts clipboard operations to capture workflow JSON
• Built with TypeScript and the official MCP SDK
• Implements stdio transport for local communication
• Supports custom Chrome/Chromium executable paths via PUPPETEER_EXECUTABLE_PATH

Requirements

• Node.js 16+
• Chrome/Chromium (for Puppeteer)

Changelog

[1.0.0] - 2025-01-10

Added

• Initial release of n8n-workflow-downloader MCP server
• Support for downloading n8n workflows from URLs
• Browser automation using Puppeteer to handle the n8n.io website interaction
• Clipboard access permissions for reading workflow JSON
• Robust error handling for failed downloads
• TypeScript support with full type definitions
• Comprehensive test suite with unit and integration tests
• MCP server implementation following the Model Context Protocol specification

Technical Details

• Built with @modelcontextprotocol/sdk for MCP server implementation
• Uses Puppeteer for browser automation
• Implements proper clipboard permissions handling
• Supports workflow URLs in the format: https://n8n.io/workflows/{id}