← Portfolio/mcp-flowise
mcp-flowise · docs

Installation and usage

An MCP server that exposes the chatflows of your local (or remote) Flowise instance as tools for Claude, Cursor, free-code, VS Code, Windsurf, or any MCP client — either as two generic tools or as one dedicated tool per chatflow.

PyPI version npm version

Watch: mcp-flowise in action

Requirements

  • A running Flowise instance, reachable from wherever this server runs (default http://localhost:3000).
  • Node.js 18+ (to run via npx) or Python 3.10+ with uv (to run via uvx). You only need one of the two.

Tools

The server exposes tools in one of two modes, chosen with FLOWISE_DYNAMIC:

Simple mode (default)

ToolWhat it does
list_chatflows()Returns a JSON array of {"id", "name"} for every chatflow that passes the configured whitelist/blacklist filters.
create_prediction(chatflow_id, question)Runs the given chatflow with question and returns its response (the raw Flowise JSON, re-serialized as a string).

This mode fits any client out of the box: the model discovers chatflows with list_chatflows and calls create_prediction with whichever id it needs, without you touching the config again when chatflows change.

Dynamic mode (FLOWISE_DYNAMIC=true)

At startup, the server calls Flowise once, and registers one tool per chatflow instead of the two generic ones — e.g. a chatflow named "Support Bot" becomes a tool flowise_support_bot(question). See Dynamic mode below for naming rules.

Installation

One-command install (any client)

npx -y -p @suamkf08/mcp-flowise mcp-flowise-install --client claude
npx -y -p @suamkf08/mcp-flowise mcp-flowise-install --client cursor
npx -y -p @suamkf08/mcp-flowise mcp-flowise-install --client free-code
npx -y -p @suamkf08/mcp-flowise mcp-flowise-install --client vscode
npx -y -p @suamkf08/mcp-flowise mcp-flowise-install --client windsurf

-p @suamkf08/mcp-flowise pulls the published package, which ships the mcp-flowise-install binary; npx then runs that binary. There is no separate @suamkf08/mcp-flowise-install package on npm — the installer lives inside @suamkf08/mcp-flowise.

The script prompts for FLOWISE_API_ENDPOINT (defaults to http://localhost:3000 if you just press enter) and FLOWISE_API_KEY (leave empty if Flowise auth is disabled), then writes the mcp-flowise entry into that client's config file and prints the path it wrote to. If an entry already exists it asks before overwriting. Restart the client afterwards to pick up the change.

only two vars

The installer only asks for endpoint and API key. If you want FLOWISE_DYNAMIC or the whitelist/blacklist filters (see Configuration), add them to the generated config's env block by hand, or use the manual install below.

Manual install

Every client config follows the same shape — a command/args/env block — only the file path and surrounding structure differ.

Claude Desktop

Edit claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows, ~/.config/Claude/claude_desktop_config.json on Linux):

option A — npx (Node.js)
{
  "mcpServers": {
    "mcp-flowise": {
      "command": "npx",
      "args": ["-y", "@suamkf08/mcp-flowise"],
      "env": {
        "FLOWISE_API_ENDPOINT": "http://localhost:3000",
        "FLOWISE_API_KEY": ""
      }
    }
  }
}
option B — uvx (uv)

Install uv first if you don't have it:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
{
  "mcpServers": {
    "mcp-flowise": {
      "command": "uvx",
      "args": ["mcp-flowise"],
      "env": {
        "FLOWISE_API_ENDPOINT": "http://localhost:3000",
        "FLOWISE_API_KEY": ""
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "mcp-flowise": {
      "command": "npx",
      "args": ["-y", "@suamkf08/mcp-flowise"],
      "env": {
        "FLOWISE_API_ENDPOINT": "http://localhost:3000",
        "FLOWISE_API_KEY": ""
      }
    }
  }
}

free-code

Add to ~/.free-code/agent/mcp.json (or import with /mcp-import):

{
  "mcpServers": {
    "mcp-flowise": {
      "command": "npx",
      "args": ["-y", "@suamkf08/mcp-flowise"],
      "env": {
        "FLOWISE_API_ENDPOINT": "http://localhost:3000",
        "FLOWISE_API_KEY": ""
      }
    }
  }
}

Then enable it:

/mcp enable mcp-flowise
/reload

VS Code / Windsurf

Same command/args/env block as above, written into that client's own MCP config file — the one-command installer (above) already knows both paths per OS, so it's usually simpler to run it with --client vscode or --client windsurf than to find the file by hand.

Configuration

All configuration is via environment variables passed in the env block of the MCP config:

Environment variableDefaultDescription
FLOWISE_API_ENDPOINThttp://localhost:3000Base URL of your Flowise instance. Trailing slash is stripped automatically.
FLOWISE_API_KEY(empty)Bearer token (Flowise → Settings → API Keys). Sent as Authorization: Bearer <key> only when non-empty.
FLOWISE_DYNAMICfalseSet to true (also accepts 1/yes) to register one tool per chatflow instead of the two generic tools.
FLOWISE_WHITELIST_ID(empty)Comma-separated chatflow IDs to include. If set, any chatflow whose id isn't in this list is dropped.
FLOWISE_BLACKLIST_ID(empty)Comma-separated chatflow IDs to exclude, checked after the whitelist.
FLOWISE_WHITELIST_NAME_REGEX(empty)Only include chatflows whose name matches this regex (re.search, not full match).
FLOWISE_BLACKLIST_NAME_REGEX(empty)Exclude chatflows whose name matches this regex, checked last.
LOG_LEVELINFOPython logging level for the server's own stderr logs.

These filters apply the same way in both simple mode (they shape what list_chatflows() returns) and dynamic mode (they shape what gets registered at startup) — see Filtering chatflows for the exact order they're applied in.

Dynamic mode

With FLOWISE_DYNAMIC=true, the server fetches the chatflow list once at startup and registers a tool per chatflow instead of the two generic ones. Each tool takes a single question argument and internally calls the same prediction endpoint as create_prediction.

Tool naming

The chatflow's name is turned into a tool name by:

  1. Replacing every run of non-alphanumeric characters with _.
  2. Trimming leading/trailing underscores and lowercasing.
  3. Prefixing with flowise_ (falling back to flowise_chatflow if the result is empty).

So "Support Bot" → flowise_support_bot, and "Lead-Scoring v2" → flowise_lead_scoring_v2.

name collisions

If two chatflows normalize to the same tool name, the second (and any further duplicate) gets the first 6 characters of its chatflow id appended, e.g. flowise_support_bot_a1b2c3, so both remain callable.

startup snapshot

The chatflow list is fetched only once, when the server process starts. Chatflows added, renamed, or removed in Flowise afterwards won't appear (or disappear) as tools until the MCP client restarts this server. If you add/rename chatflows often, simple mode's list_chatflows() is more convenient since it re-queries Flowise on every call.

If fetching chatflows fails at startup (Flowise unreachable, auth error, etc.), the error is logged to stderr and dynamic registration is skipped — the server still starts, just with no chatflow tools registered.

Filtering chatflows

Whitelist/blacklist filters are combined and applied in this fixed order, per chatflow:

1. FLOWISE_WHITELIST_ID set and chatflow id NOT in it → drop 2. chatflow id IN FLOWISE_BLACKLIST_ID → drop 3. FLOWISE_WHITELIST_NAME_REGEX set and name doesn't match → drop 4. name matches FLOWISE_BLACKLIST_NAME_REGEX → drop otherwise → keep

A chatflow only survives if it passes all four checks. Regexes use Python's re.search, so they match anywhere in the name, not just the whole string — FLOWISE_WHITELIST_NAME_REGEX=support matches both "Support Bot" and "Customer Support v3".

Error handling

Both tools catch httpx.HTTPError (connection failures, timeouts, non-2xx responses) and return a plain-text error message instead of raising — so a Flowise instance being down or a bad chatflow_id surfaces to the model as readable text, not a protocol-level failure: 

Error contacting Flowise at http://localhost:3000: ...
Error calling chatflow <id>: ...

Every HTTP request (list or predict) uses a 120-second timeout.

Development

git clone https://github.com/suamkf08/mcp-flowise
cd mcp-flowise
uv run mcp-flowise        # starts over stdio; Ctrl+C to quit

Inspect it interactively with MCP Inspector:

uv run mcp dev mcp_flowise/server.py
smithery

smithery.yaml at the repo root declares a stdio startCommand for deploying through Smithery, with a config schema covering flowiseApiEndpoint (required), flowiseApiKey, flowiseDynamic, flowiseWhitelistId, and flowiseBlacklistId. The name-regex filters aren't exposed in that schema — set them as plain environment variables if you need them there.

Flowise API reference

What this server actually calls on your Flowise instance:

PurposeRequest
List chatflowsGET {endpoint}/api/v1/chatflows
Run a chatflowPOST {endpoint}/api/v1/prediction/{chatflowId} with body {"question": "..."}
AuthAuthorization: Bearer <FLOWISE_API_KEY>, omitted entirely if the key is empty

Security

  • This server talks stdio to its MCP client only — it doesn't open any network port itself. All network traffic is outbound, from this process to your Flowise FLOWISE_API_ENDPOINT.
  • FLOWISE_API_KEY is stored in plain text in whichever client config file you write it to (claude_desktop_config.json, mcp.json, etc.) — treat that file with the same care as any other credential file.
  • If FLOWISE_API_ENDPOINT points at a non-localhost Flowise instance, prefer https:// so the API key isn't sent in the clear over the network.
  • Whitelist/blacklist filters only affect what's exposed as MCP tools to the client — they are not an authentication or authorization boundary against Flowise itself. Anyone with the same FLOWISE_API_KEY can call any chatflow directly against the Flowise API, filters or not.