flowforge-mcp

Model Context Protocol server for FlowForge — expose your local-first ETL pipelines to LLM clients (Claude Desktop, Cursor, GitHub Copilot, OpenAI Desktop, custom Agent SDK apps).

The LLM never receives your raw rows unless it explicitly asks for them through query_sql or preview_dataset. Pipelines run locally; only summaries/schemas cross the wire.

Install

# As a one-off (recommended for client config files)
npx @vjsr1982/flowforge-mcp --help

# Or globally
npm i -g @vjsr1982/flowforge-mcp

Requires Node.js ≥ 20.

Modes

| Mode | Transport | Auth | Use case | |---|---|---|---| | --remote (default) | stdio ↔ HTTPS | Authorization: Bearer ff_pat_… | Web/cloud users | | --local | stdio ↔ Tauri sidecar IPC | none (per-launch secret) | Desktop app users |

Get a token (remote mode)

1. Sign in at https://flowforge.pick-app.com.mx.
2. Settings → API Tokens → Create token (scope: mcp minimum).
3. Copy the token (shown once) — format ff_pat_<32 chars>.
4. Save it as FLOWFORGE_API_TOKEN env var, or in ~/.flowforge/token.

Claude Desktop config

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "flowforge": {
      "command": "npx",
      "args": ["-y", "@vjsr1982/flowforge-mcp"],
      "env": { "FLOWFORGE_API_TOKEN": "ff_pat_..." }
    }
  }
}

CLI

flowforge-mcp [--remote] [--base-url <url>] [--token <ff_pat_…>]
flowforge-mcp --local

| Env var | Default | Notes | |---|---|---| | FLOWFORGE_API_TOKEN | — | required for remote mode | | FLOWFORGE_BASE_URL | https://flowforge.pick-app.com.mx | override for self-hosted |

Tools (v1)

Always available:

• list_pipelines, get_pipeline, validate_pipeline, create_pipeline

Available when the engine reports canExecute (currently desktop sidecar only):

• run_pipeline, query_sql, list_datasets, describe_dataset, preview_dataset

Resources

• pipeline:///{id} — pipeline JSON document
• pipelines://list — index of pipelines

Prompts

• etl/clean-csv — design a cleanup pipeline for a dataset
• etl/explain-pipeline — explain a pipeline in plain English
• etl/optimize-pipeline — suggest performance improvements

Security

• Token format: ff_pat_<32 base62>. Hashed (SHA-256) at rest by the FlowForge backend.
• query_sql is read-only — DDL, ATTACH, PRAGMA and side-effect statements are rejected by the backend's sql-validator.
• Local mode never sends data to the network. The desktop sidecar is keyed by a per-launch secret stored mode 0600 in the OS config dir.

Development

npm install
npm run build
npm test

License: MIT