n8n Workflow Downloader MCP Server

![npm version](https://badge.fury.io/js/n8n-workflow-downloader-mcp)

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)

n8n-workflow-downloader-mcp