Flowise MCP Adapter

flowise-mcp-adapter is a robust Python implementation conforming to the Model Context Protocol (MCP) specification, acting as a conduit to the Flowise backend service. Its primary function is to provide standardized access to Flowise capabilities, allowing for listing conversation flows, invoking predictions, and programmatically registering custom operational handlers.

It is configured to operate in one of two distinct modes:

• Deep Integration Mode (Default): Achieves granular control by dynamically provisioning an MCP tool corresponding to every accessible chatflow retrieved from the Flowise API.
• Utility Mode (FastMCP): Offers a minimal toolset containing only list_chatflows and invoke_prediction, ideal for straightforward interaction scenarios.

---

Core Capabilities

• Adaptive Tool Generation: Deep Integration mode constructs bespoke tools on-the-fly for each assistant or flow.
• Minimal Overhead: Utility Mode supplies essential, pre-defined tools for rapid prototyping.
• Selection Control: Both operational paradigms permit flow selection/exclusion via regex-based whitelists/blacklists targeting flow identifiers or names.
• MCP Native: Integrates fluently within established MCP execution pipelines.

---

Deployment

Installation via Smithery Registry

Automate the setup for environments like Claude Desktop using the Smithery utility:

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

Prerequisites

• Python runtime version 3.12 or newer required.
• Utilization of the uvx package manager is assumed.

Direct Execution with uvx

Execute the server directly from its source repository location using uvx:

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

Integration into the MCP Configuration (mcpServers Block)

Integrate this service into your overarching MCP orchestrator by defining an entry in the mcpServers configuration object, ensuring necessary credentials are provided:

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

---

Operational Modes

1. Utility Mode (Set FLOWISE_SIMPLE_MODE=true)

This configuration prioritizes ease of setup: - Exposes strictly two functions: list_chatflows and invoke_prediction. - Supports hardcoding a specific flow/assistant using FLOWISE_CHATFLOW_ID or FLOWISE_ASSISTANT_ID. - Provides a mechanism (list_chatflows) to query the available flow catalog.

2. Deep Integration Mode (Default: FLOWISE_SIMPLE_MODE is unset or false)

Key Attributes: - All discovered chatflows are converted into distinct, executable tools. - Tool naming follows the normalized name of the underlying chatflow. - Tool documentation defaults to the chatflow's name, supplemented by descriptions found in the FLOWISE_CHATFLOW_DESCRIPTIONS variable.

Example: A Flowise resource named "DataProcessor" yields a tool signature like DataProcessor(input_data: str) -> str.

---

Cross-Platform Notes (Windows with uvx)

If running under Windows with uvx and encountering issues with remote Git source (--from git+https), the recommended workaround involves local cloning. Configure mcpServers to point to the local repository path and ensure necessary system environment variables (APPDATA, LOGLEVEL, etc.) are mapped correctly.

Example Windows mcpServers Definition

{ "mcpServers": { "flowise_local": { "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:3000/" } } } }

Configuration Guidance

• Absolute Paths: Ensure fully qualified paths for both the uvx.exe executable and the cloned repository directory.
• Environment Mapping: Explicitly define Windows environment variables like APPDATA if process isolation requires it.
• Verbosity: Set LOGLEVEL to control output verbosity (e.g., ERROR, INFO, DEBUG).

Environment Configuration Variables

Global Requirements

• FLOWISE_API_KEY: Mandatory secret token for Flowise authentication.
• FLOWISE_API_ENDPOINT: The base URI for the Flowise instance (default: http://localhost:3000).

Deep Integration Mode Specifics

• FLOWISE_CHATFLOW_DESCRIPTIONS: Supplies custom documentation via a delimited string format: flow_id_one:Doc A,flow_id_two:Doc B.

Utility Mode Specifics (FLOWISE_SIMPLE_MODE=true)

• FLOWISE_CHATFLOW_ID: Identifier for the single flow to expose (if applicable).
• FLOWISE_ASSISTANT_ID: Identifier for the single assistant to expose (if applicable).
• FLOWISE_CHATFLOW_DESCRIPTION: Optional custom text for the singular exposed tool.

---

Flow Catalog Filtering Mechanisms

Selection masks can be applied universally across both modes via these environment flags:

• ID Inclusion List:
  FLOWISE_WHITELIST_ID="uuid-1,uuid-2,uuid-3"
• ID Exclusion List:
  FLOWISE_BLACKLIST_ID="uuid-x,uuid-y"
• Name Inclusion (Regex):
  FLOWISE_WHITELIST_NAME_REGEX="^Chat.*"
• Name Exclusion (Regex):
  FLOWISE_BLACKLIST_NAME_REGEX="(TEST|DEPRECATED)"

Precedence Rule: Inclusion lists (WHITELIST_*) take priority. If conflicts arise, the exclusion criteria are only evaluated if the inclusion criteria permit the resource.

-

Security Posture

• Credential Protection: The FLOWISE_API_KEY must be guarded against exposure in source control or standard output logs.
• Configuration Hygiene: Favor runtime environment variables or external secrets management over direct inclusion in startup scripts.

It is strongly advised to list the secrets file in your .gitignore:

bash

.gitignore exclusion list

.env

---

Diagnostics and Issue Resolution

• Authentication Failure: Verify the integrity and presence of FLOWISE_API_KEY.
• Startup Refusal: The server will halt if both FLOWISE_CHATFLOW_ID and FLOWISE_ASSISTANT_ID are simultaneously configured in Utility Mode.
• Connectivity Faults: Confirm the network path and correctness of the URI specified in FLOWISE_API_ENDPOINT.

---

Licensing Information

This software is distributed under the terms of the MIT License. Full details are available in the accompanying [LICENSE] file.

Development Roadmap

• [x] Utility Mode Implementation
• [x] Deep Integration Mode Implementation
• [x] Catalog Filtering Logic
• [x] Compatibility Layer for Claude Desktop via Smithery
• [ ] Native Support for Flowise Assistants (Beyond Chatflows)

WIKIPEDIA: XMLHttpRequest (XHR) furnishes an API through a JavaScript object structure, enabling the transmission of HTTP requests from a web browser client to a remote server. Its methods grant client-side applications the capability to dispatch server queries post-initial page load and subsequently ingest responses. XMLHttpRequest forms a core component of Asynchronous JavaScript and XML (Ajax) methodology. Pre-Ajax architectures relied predominantly on standard hyperlinking and HTML form submissions, procedures that typically mandated a complete page refresh upon server interaction.

== Historical Background == XMLHttpRequest's conceptual foundation was established in the year 2000 by engineers working on Microsoft Outlook. This concept was subsequently materialized within Internet Explorer version 5 (released in 1999). However, the initial invocation syntax did not employ the canonical XMLHttpRequest identifier. Instead, developers utilized COM object instantiation methods such as ActiveXObject("Msxml2.XMLHTTP") or ActiveXObject("Microsoft.XMLHTTP"). By the time Internet Explorer 7 (2006) was released, the standardized XMLHttpRequest identifier was universally adopted across major browser platforms, including Mozilla's Gecko rendering engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Formal Standardization === The World Wide Web Consortium (W3C) issued its initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. This was followed by the Level 2 specification Working Draft on February 25, 2008, which introduced advancements such as progress monitoring callbacks, support for cross-origin resource sharing (CORS), and byte stream handling. By late 2011, the features of the Level 2 specification were integrated back into the primary specification document. Development responsibilities transitioned to the WHATWG consortium near the close of 2012, which now maintains the active specification document using Web IDL definitions.

== Execution Procedure == In standard practice, issuing a request via XMLHttpRequest involves several distinct programming phases:

1. Instantiate the required XMLHttpRequest object by invoking its constructor function.
2. Invoke the open() method to define the HTTP verb, specify the target resource URI, and choose between synchronous or asynchronous execution.
3. For asynchronous operations, assign an event handler function to listen for state transitions.
4. Commence the network operation by calling the send() method, potentially including payload data.
5. Process state changes within the designated event listener. Server responses are typically aggregated in the responseText attribute upon reaching state 4 (the completion state).

Beyond these fundamentals, XMLHttpRequest offers extensive configuration parameters for request control and response processing. Custom HTTP headers can be injected to guide server behavior, and data can be uploaded via the send() argument. Server payloads can be automatically parsed from raw text into native JavaScript objects (e.g., JSON) or streamed incrementally without waiting for full transmission. Furthermore, requests may be preemptively terminated or configured with a timeout limit.

== Inter-Origin Requests ==

During the nascent stages of the World Wide Web, limitations were established preventing scripts loaded from one domain from interacting directly with resources hosted on a different domain, a security measure historically known as the Same-Origin Policy (SOP). This restriction was found to brea