# n8n Workflow Downloader MCP Server

[![npm version](https://badge.fury.io/js/n8n-workflow-downloader-mcp.svg)](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

```bash
npm install -g n8n-workflow-downloader-mcp
```

### For development

```bash
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):

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

```bash
# 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)