n8n-workflows — User Guide

A fast, self-hosted search engine and documentation browser for a large curated collection of n8n workflow files. Point it at a folder of workflow .json exports, run one command, and get an instant web interface to search, filter, preview, visualize, and download thousands of workflows in milliseconds.

This guide is for people who want to run the tool and find workflows. If you operate the service, tune its database, deploy it to a server, or extend its APIs, see the companion Admin Guide.

1. What This Tool Does

n8n-workflows turns a directory full of n8n workflow .json files into a searchable catalog. It scans every workflow, extracts its metadata (name, trigger type, the services it integrates with, node count, complexity), stores that in a local SQLite database with full-text search, and serves a single-page web app plus a JSON API on top.

The bundled collection ships pre-organized into service folders (workflows/Slack, workflows/Telegram, workflows/Github, and ~200 more). As published, the indexed catalog contains:

Note

These figures come from the collection's published statistics snapshot. Your own numbers will differ if you add, remove, or re-index workflows — the tool recomputes them every time it indexes.

What you can do with it:

• Full-text search across workflow names, descriptions, integrations, and tags
• Filter by trigger type (Manual, Webhook, Scheduled, Complex), complexity (low/medium/high), active status, and service category
• Preview a workflow's metadata and raw JSON
• View an auto-generated Mermaid diagram of any workflow's node graph
• Download any workflow's .json file to import into your own n8n instance

Tip

This is a documentation and discovery tool, not an n8n runtime. It does not execute workflows. To run a workflow you find here, download its JSON and import it into your own n8n installation (Workflows → Import from File).

2. Quick Start

The fastest path from clone to a running search interface.

Requirements

• Python 3.9–3.12 (the dependencies are pinned for this range)
• pip for installing dependencies
• Roughly 50 MB of disk for the database once indexed (varies with collection size)
• A modern web browser

Important

Python 3.13+ is outside the tested range for the pinned dependency versions. If you are on 3.13, use the Docker method in Section 3 instead, which controls the runtime for you.

Run it

# 1. Clone the repository
git clone https://github.com/Zie619/n8n-workflows.git
cd n8n-workflows

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Start the server (indexes the database on first run)
python run.py

On first launch you will see the indexer build the database, then the server start:

🚀 n8n-workflows Advanced Search Engine
==================================================
✅ Dependencies verified
✅ Directories verified
🔄 Setting up database: database/workflows.db
📚 Indexing workflows...
✅ Indexed 4343 workflows
📊 Database contains 4343 workflows
🌐 Starting server at http://127.0.0.1:8000
📊 API Documentation: http://127.0.0.1:8000/docs
🔍 Workflow Search: http://127.0.0.1:8000/api/workflows

Open http://127.0.0.1:8000 in your browser. The first run indexes every workflow; subsequent runs reuse the database and start almost instantly.

Note

By default the server binds to 127.0.0.1 (localhost only). It will not be reachable from other machines unless you explicitly bind to 0.0.0.0 — see Section 4.

3. Installation

Choose the method that fits your environment.

Python (local)

git clone https://github.com/Zie619/n8n-workflows.git
cd n8n-workflows
pip install -r requirements.txt
python run.py

Recommended: use a virtual environment so dependencies stay isolated.

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python run.py

Docker (one command)

A helper script builds the image, starts the container, waits for health, and opens your browser:

git clone https://github.com/Zie619/n8n-workflows.git
cd n8n-workflows
./run-as-docker-container.sh

The script requires Docker and Docker Compose. When it finishes:

🌐 Access URLs:
   Main Interface: http://localhost:8000
   API Documentation: http://localhost:8000/docs
   API Stats: http://localhost:8000/api/stats

Stop it with docker compose down; follow logs with docker compose logs -f.

Node.js (alternative)

The project ships a second implementation of the same core API in Node.js, under src/. Use it if you prefer a Node runtime.

npm install
node src/index-workflows.js      # build the database
node src/server.js               # start the server

The Node server exposes the same core endpoints as the Python server (search, stats, detail, download, diagram). See Section 8 for its command-line options.

Tip

The Python stack (run.py) is the primary, most fully featured way to run the tool. Pick the Node stack only if Python isn't available in your environment.

Verifying the install

curl http://127.0.0.1:8000/health

{"status":"healthy","message":"N8N Workflow API is running"}

If you get JSON back, the server is up. Then check the catalog loaded:

curl http://127.0.0.1:8000/api/stats

{"total":4343,"active":434,"inactive":3908,...}

4. Starting the Server (Command-Line Options)

run.py is the launcher you'll use most. It checks dependencies, ensures the database/, static/, and workflows/ directories exist, indexes the database if needed, and starts the web server.

python run.py [options]

Common invocations:

python run.py                    # default: localhost:8000, index if needed
python run.py --port 3000        # run on port 3000
python run.py --host 0.0.0.0     # accept connections from your network
python run.py --reindex          # rebuild the database from scratch
python run.py --dev              # auto-reload while developing

Warning

Binding to --host 0.0.0.0 exposes the interface to everyone who can reach your machine on that port. The server has no login for browsing, so only do this on a trusted network or behind a reverse proxy with authentication. See the Admin Guide for hardening.

Tip

Setting the environment variable CI=true has the same effect as --skip-index — handy for automated test environments where you don't want to rebuild the database.

5. Using the Web Interface

Open the main page (default http://127.0.0.1:8000) and you get a single search-first interface.

Searching

• Type in the search box and results update as you type (the input is debounced, so it waits briefly after you stop typing).
• Press / anywhere on the page to jump straight to the search box.
• Press Esc to clear the current search.

Search matches against each workflow's name, description, integrations, and tags.

Filtering

Three dropdown filters narrow results, and they combine with your search text:

Browsing results

Each result is a workflow card showing the name, a generated description, its category, trigger type, complexity, node count, and the first few integrations it uses. Click a card to open a detail modal with the full integration list, tags, active/inactive status, and filename.

Results load in pages of 20. Click Load More to reveal the next batch.

Note

When you first open the page (before any search), the interface shows a set of Featured Workflows — workflows that use at least one detected integration — so you have something to explore immediately.

Downloading a workflow

Every card and detail view has a 📥 Download JSON button. It downloads that workflow's raw .json file. There's also a 📋 Copy ID / Copy Filename button to copy the filename to your clipboard.

To use a downloaded workflow:

1. Open your own n8n instance.
2. Go to Workflows → Import from File (or paste the JSON via Import from URL/Clipboard).
3. Select the downloaded .json file.
4. Reconnect any credentials the workflow expects (API keys, OAuth, etc.) — credentials are not included in the exported files.

Caution

Always review a workflow before activating it in your own n8n. Check which nodes make outbound requests and which credentials they expect. Downloaded workflows are community automations — treat them as untrusted until you've read them.

6. Common Tasks (Recipes)

Find every workflow for a specific service

Type the service name in the search box — e.g. slack, telegram, openai, google sheets. Or use the API directly:

curl "http://127.0.0.1:8000/api/workflows?q=slack"

Browse only Scheduled automations

Set the Trigger filter to Scheduled, or:

curl "http://127.0.0.1:8000/api/workflows?trigger=Scheduled"

Find simple, beginner-friendly workflows

Set Complexity to low (5 nodes or fewer):

curl "http://127.0.0.1:8000/api/workflows?complexity=low"

See only workflows that are marked active

curl "http://127.0.0.1:8000/api/workflows?active_only=true"

Look at one workflow's full JSON before downloading

curl "http://127.0.0.1:8000/api/workflows/0720_Schedule_Filter_Create_Scheduled.json"

This returns both the stored metadata and the complete raw workflow JSON.

Visualize a workflow as a diagram

curl "http://127.0.0.1:8000/api/workflows/0720_Schedule_Filter_Create_Scheduled.json/diagram"

You get Mermaid flowchart code describing the workflow's nodes and their connections. Triggers are colored blue, conditional nodes (If/Switch) yellow, code nodes purple, and error handlers red — paste it into any Mermaid renderer to see the graph.

Browse by category from the API

curl "http://127.0.0.1:8000/api/categories"                      # list categories
curl "http://127.0.0.1:8000/api/workflows/category/messaging"    # workflows in a category

7. Searching via the JSON API

The same data behind the web UI is available as a JSON API, so you can script against it. The primary endpoint is /api/workflows.

Search & filter parameters

Example — page 2 of webhook workflows mentioning "invoice", 10 per page:

curl "http://127.0.0.1:8000/api/workflows?q=invoice&trigger=Webhook&page=2&per_page=10"

{
  "workflows": [ ... ],
  "total": 37,
  "page": 2,
  "per_page": 10,
  "pages": 4,
  "query": "invoice",
  "filters": {"trigger": "Webhook", "complexity": "all", "active_only": false}
}

Endpoints you'll use as a consumer

Tip

The server publishes interactive API documentation at /docs (Swagger UI). Open http://127.0.0.1:8000/docs to try every endpoint from your browser with no extra tools.

Note

The detail, download, and diagram endpoints are rate-limited to 60 requests per minute per IP address. If you script bulk downloads, pace your requests or you'll get HTTP 429 responses (see Troubleshooting).

8. Running the Node.js Server

If you use the Node.js stack instead of Python, the entry point is src/server.js. It serves the same core search/browse/download API.

node src/server.js [options]

Build or refresh the database first with the Node indexer:

node src/index-workflows.js            # index all workflows
node src/index-workflows.js --force    # force a full re-index
node src/index-workflows.js --stats    # show database statistics only

Note

The Node and Python servers use the same on-disk SQLite database format and the same workflows/ directory, but pick one stack and stick with it for a given deployment to avoid confusion about which one indexed the data.

9. Working With the Database Directly

workflow_db.py is a small command-line tool for indexing and searching without starting the web server — useful for scripting or quick checks.

python workflow_db.py [options]

Examples:

python workflow_db.py --index                 # build/update the index
python workflow_db.py --index --force          # rebuild everything
python workflow_db.py --search "telegram bot"  # search from the terminal
python workflow_db.py --stats                  # show totals

Database Statistics:
  Total workflows: 4343
  Active: 434
  Total nodes: 29528
  Unique integrations: 268
  Trigger types: {'Complex': 1737, 'Manual': 998, 'Scheduled': 477, 'Webhook': 1129}

Tip

Re-indexing is incremental by default. The indexer hashes each file and skips ones that haven't changed since the last run, so updating after adding a few workflows is fast. Use --force only when you want to rebuild everything.

10. Understanding the Catalog

A few concepts make the search results easier to interpret.

Trigger type — how a workflow starts:

Trigger type : Inferred from the workflow's nodes. Webhook = starts on an inbound HTTP call; Scheduled = starts on a timer/cron; Manual = started by hand; Complex = a larger workflow (more than 10 nodes and more than 3 integrations) that doesn't fit the simpler categories.

Complexity — a rough size signal based on node count:

Complexity : low = 5 nodes or fewer, medium = 6–15 nodes, high = 16 or more nodes. It reflects structural size, not how hard the workflow is to understand.

Integrations — the external services a workflow touches:

Integrations : Detected from each node's type (e.g. an n8n-nodes-base.slack node → "Slack"). Pure utility nodes (Set, If, Merge, Code, sticky notes, etc.) are intentionally excluded so the integration list reflects real services. The most common integrations in the collection are HTTP Request, OpenAI, AI Agent, Webhook, and Form Trigger.

Active vs. inactive — taken straight from the workflow's active flag in its JSON. Most workflows in the published collection are inactive (they're examples to import, not running automations).

11. Troubleshooting

Error: Database setup error: No module named 'workflow_db'

Cause: You ran a command from the wrong directory, so Python couldn't find workflow_db.py. This module lives at the repository root.

Solution: Run all commands from the repository root (the folder containing run.py and workflow_db.py):

cd /path/to/n8n-workflows
python run.py

Prevention: Don't run run.py from inside a subfolder, and don't copy it elsewhere without its sibling modules.

Error: Missing dependencies: fastapi, uvicorn

Cause: Dependencies aren't installed (or you're in the wrong virtual environment).

Solution:

pip install -r requirements.txt

Prevention: Activate your virtual environment before running, and keep dependencies installed there.

The page loads but says "Setup Required" / no workflows appear

Cause: The server started but the database is empty — usually because indexing was skipped (--skip-index or CI=true) or the workflows/ directory is missing.

Solution: Force an index and restart:

python run.py --reindex

Prevention: Only use --skip-index/CI when you intend to start with an existing, already-populated database.

Browser console: Failed to load search index

Cause: This appears on the static (GitHub Pages-style) front end when it can't fetch its pre-built api/search-index.json file. It typically means you opened the static docs/ page without the data file present.

Solution: Use the live server (python run.py) and open http://127.0.0.1:8000, which serves data from the API rather than a static file.

HTTP 429 — Rate limit exceeded. Please try again later.

Cause: You sent more than 60 requests per minute from one IP to the detail, download, or diagram endpoints.

Solution: Slow down. Add a short delay between requests when scripting bulk operations.

Prevention: Batch your needs — fetch a search page once (which lists many workflows) instead of hammering per-workflow endpoints.

HTTP 400 — Invalid filename format

Cause: The filename you requested isn't a plain name.json (the server blocks anything containing slashes, .., or other special characters as a security measure).

Solution: Use the exact filename returned by /api/workflows — e.g. 0720_Schedule_Filter_Create_Scheduled.json — with no path in front of it.

HTTP 404 — Workflow file not found

Cause: The filename doesn't exist in the workflows/ directory, or the database is out of sync with the files on disk.

Solution: Confirm the filename via a search, then re-index if you recently changed files:

python run.py --reindex

Docker container won't start / "trouble using the Docker image"

Cause: Docker or Docker Compose isn't installed, or a port is already in use.

Solution: Verify both are installed (docker --version, docker compose version), make sure nothing else is on port 8000, then re-run ./run-as-docker-container.sh. Inspect logs with docker compose logs -f.

Server starts but is unreachable from another computer

Cause: The default bind address is 127.0.0.1 (localhost only).

Solution: Start with python run.py --host 0.0.0.0 and open the host machine's IP from the other computer. Make sure your firewall allows the port.

12. Frequently Asked Questions

Q: Does this tool run my workflows? No. It only catalogs, searches, and serves workflow files. To run a workflow, download its JSON and import it into your own n8n instance.

Q: How fast is search? Very. The search engine uses SQLite full-text search (FTS5) with indexes, so queries across thousands of workflows return in well under a second — typically tens of milliseconds.

Q: Where does the workflow data come from? From the .json files in the workflows/ directory, organized into per-service subfolders. The bundled collection ships thousands of community workflows already sorted.

Q: Can I add my own workflows? Yes. Drop additional .json files into the workflows/ directory (any subfolder) and re-index with python run.py --reindex or python workflow_db.py --index. They'll appear in search.

Q: Are credentials/API keys included in downloaded workflows? No. Exported workflow JSON contains node configuration but not your secrets. You'll reconnect credentials inside your own n8n after importing.

Q: What's the difference between the Python and Node.js servers? They implement the same core search/browse/download API over the same database. Python (run.py) is the primary, most complete stack; Node (src/server.js) is an alternative for Node-only environments.

Q: Why are most workflows marked "inactive"? The collection is a library of examples. The active flag reflects each workflow's state at export time; most are templates meant to be imported, not live automations.

Q: Where's the interactive API documentation? At /docs on the running server (Swagger UI) — e.g. http://127.0.0.1:8000/docs.

Q: Can I change the port or run multiple instances? Yes. Use --port to pick a port. Run separate instances on different ports if you want multiple catalogs.

Q: How do I update the catalog after the files change? Re-index. Indexing is incremental (it skips unchanged files), so updates are quick: python run.py --reindex or python workflow_db.py --index.

Q: Does it work offline? Yes. Once dependencies are installed and the database is built, the search engine runs entirely locally with no internet connection required.

13. Quick Reference

Start the server:

python run.py [--host H] [--port P] [--reindex] [--dev] [--skip-index]

Index / query the database directly:

python workflow_db.py [--index] [--force] [--search "TEXT"] [--stats]

Node.js stack:

node src/index-workflows.js [--force] [--stats]
node src/server.js [-p PORT] [-h HOST] [--dev]

Key URLs (default host/port):

Keyboard shortcuts (web UI):

Search/filter cheatsheet:

?q=slack                 # text search
?trigger=Scheduled       # Manual | Webhook | Scheduled | Complex
?complexity=low          # low | medium | high
?active_only=true        # active workflows only
?page=2&per_page=50      # pagination (per_page max 100)