flowise-adapter-mcp

This Python utility, flowise-adapter-mcp, implements an MCP server layer to interface directly with Flowise backend services. Its core purpose is to expose Flowise assets—specifically chatflows and assistants—as discoverable, callable tools within an MCP execution environment. It supports two distinct operational paradigms for integration flexibility.

Key capabilities include querying available conversational flows, triggering predictions using those flows, and managing tool registration based on configuration.

Operational Modes

The adapter operates in one of two modes, determined by environment configuration:

1. Dynamic Tool Registry Mode (Default/LowLevel): Scans the connected Flowise instance and programmatically generates distinct MCP tools corresponding to every accessible chatflow. This offers granular, dynamic access.
2. Static Proxy Mode (FastMCP): Simplifies integration by exposing only two fixed tools: list_flows and invoke_prediction. This is ideal for environments requiring minimal setup overhead.

---

Core Functionality

• Adaptive Tooling: LowLevel mode automatically generates tools based on runtime inventory from the Flowise API.
• Minimal Interface: FastMCP mode furnishes list_chatflows and create_prediction for basic operational needs.
• Access Control: Comprehensive filtering mechanisms using ID-based whitelists/blacklists or name-based regular expression matching are supported across both modes.
• MCP Compliance: Designed for seamless incorporation into established Model Context Protocol architectures.

Deployment & Setup

Integration via Smithery (Automated)

Install the adapter directly into your Claude Desktop setup using the Smithery CLI:

npx -y @smithery/cli install @andydukes/mcp-flowise --client claude

Prerequisites

• Python runtime environment, version 3.12 or newer.
• The uvx package manager utility.

Direct Installation and Execution via uvx

Execute the server directly from the source repository using uvx:

uvx --from git+https://github.com/andydukes/mcp-flowise mcp-flowise

MCP Ecosystem Configuration (mcpServers Entry)

To embed this service within a larger MCP orchestration framework, configure the server launch parameters within your main configuration file:

{
    "mcpServers": {
        "flowise_service": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/andydukes/mcp-flowise",
                "mcp-flowise"
            ],
            "env": {
                "FLOWISE_API_KEY": "${FLOWISE_API_KEY}",
                "FLOWISE_API_ENDPOINT": "${FLOWISE_API_ENDPOINT}"
            }
        }
    }
}

---

Mode Details

1. FastMCP Mode (Simplified Interface)

Activation: Set the environment flag FLOWISE_SIMPLE_MODE to true.

• Tool Set: Exposes only list_chatflows and create_prediction.
• Configuration: Supports specifying a single target flow or assistant via FLOWISE_CHATFLOW_ID or FLOWISE_ASSISTANT_ID.
• Discovery: list_chatflows can still enumerate all available resources.

2. Dynamic Mode (LowLevel/Default)

Activation: FLOWISE_SIMPLE_MODE is unset or set to false.

• Tool Generation: Creates a unique, callable tool for every individual chatflow found.
• Naming Convention: Tools inherit names derived from the associated chatflow identifier, normalized for MCP compatibility.
• Documentation: Tool descriptions are sourced from the FLOWISE_CHATFLOW_DESCRIPTIONS environment variable; absent descriptions default to the flow's base name.

Example Tool Signature: A Flow named "DataAnalysis" yields a tool signature like data_analysis(input_query: str) -> str.

---

Platform Specifics: Windows Execution via uvx

Users on Windows might encounter path resolution issues when using Git URLs directly with uvx. The recommended workaround involves local cloning and explicit path configuration in mcpServers:

Windows mcpServers Example

{
  "mcpServers": {
    "local_flowise_hook": {
      "command": "C:\\Users\matth\.local\bin\\uvx.exe",
      "args": [
        "--from",
        "C:\\Users\\matth\\downloads\\mcp-flowise", 
        "mcp-flowise"
      ],
      "env": {
        "LOGLEVEL": "ERROR",
        "APPDATA": "C:\\Users\\matth\\AppData\\Roaming",
        "FLOWISE_API_KEY": "your-api-key-goes-here",
        "FLOWISE_API_ENDPOINT": "http://localhost:3010/"
      }
    }
  }
}

Configuration Notes for Windows:

• Specify the full, absolute path for the uvx.exe executable.
• Specify the full path to the locally cloned repository directory.
• Ensure critical environment variables like APPDATA are correctly mapped if the underlying Python environment requires them for operation.

---

Environment Variable Reference

Mandatory & General Settings

• FLOWISE_API_KEY: Required secret token for Flowise authentication.
• FLOWISE_API_ENDPOINT: The base URI for the Flowise service (Default: http://localhost:3010).

Dynamic Mode Customization

• FLOWISE_CHATFLOW_DESCRIPTIONS: Supplies detailed, comma-separated mappings for tool descriptions, formatted as flow_id:tool_description. FLOWISE_CHATFLOW_DESCRIPTIONS="a3b4c5:Perform complex financial modeling,d6e7f8:Generate standard report draft"

FastMCP Mode Overrides

• FLOWISE_CHATFLOW_ID: Forces the simple mode tool to target this specific flow ID.
• FLOWISE_ASSISTANT_ID: Forces the simple mode tool to target this specific assistant ID.
• FLOWISE_CHATFLOW_DESCRIPTION: Optional text to use as the description for the single exposed tool.

---

Resource Selection Filtering

Resource visibility can be finely controlled using these environment variables, applicable in both operational modes:

Variable	Scope	Description
FLOWISE_WHITELIST_ID	ID List	Only include flows whose IDs match this comma-separated list.
FLOWISE_BLACKLIST_ID	ID List	Exclude flows whose IDs match this comma-separated list.
FLOWISE_WHITELIST_NAME_REGEX	Regex	Include flows whose names match this pattern (e.g., .*critical.*).
FLOWISE_BLACKLIST_NAME_REGEX	Regex	Exclude flows whose names match this pattern (e.g., .*testing.*).

Filtering Precedence: Whitelist inclusion checks are processed before blacklist exclusions. If a flow is whitelisted, it will be included unless it is also explicitly blacklisted (i.e., blacklists act as a final veto).

---

Security Advisory

• Credential Protection: Treat FLOWISE_API_KEY as highly sensitive data. Never commit keys directly into source control.
• Configuration Management: Utilize OS environment variables or dedicated secret management solutions over hardcoding values.

Ensure your source code repository ignores local configuration files:

# .gitignore entry
.env

---

Debugging Common Issues

• Authentication Failure: Verify the integrity and presence of FLOWISE_API_KEY.
• Startup Conflict: The server will halt if both FLOWISE_CHATFLOW_ID and FLOWISE_ASSISTANT_ID are specified simultaneously in FastMCP mode.
• Connectivity: Confirm that the network path to FLOWISE_API_ENDPOINT is open and the service is active.

---

Licensing

This project is distributed under the permissive MIT License. Full details are available in the LICENSE file.

Development Roadmap

• [x] Implemented FastMCP Mode
• [x] Implemented LowLevel Dynamic Mode
• [x] Implemented Flow Filtering Logic
• [x] Enabled Claude Desktop Compatibility
• [ ] Full Native Support for Flowise Assistants (beyond basic prediction invocation)