Flowise MCP Server

A Model Context Protocol (MCP) server that provides programmatic integration with Flowise AI workflow platform. This enables LLM-based tools like Claude Code to create, manage, and run Flowise chatflows and agentflows.

Features

• Run Predictions: Execute chatflows with questions, conversation history, file uploads, or lead capture
• Manage Chatflows: Create, update, delete, and list chatflows programmatically
• Node Discovery: List all available nodes and get detailed specifications for building flows
• Full Flow Types: Supports CHATFLOW, AGENTFLOW, MULTIAGENT, and ASSISTANT types

Prerequisites

• Node.js 20+
• pnpm package manager
• A running Flowise instance

Installation

# Clone the repository
git clone https://github.com/wksbx/flowise-mcp-server.git
cd flowise-mcp-server

# Install dependencies
pnpm install

# Build the project
pnpm build

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit .env with your Flowise settings:

FLOWISE_BASE_URL=http://localhost:3000
FLOWISE_API_KEY=your-api-key-here

• FLOWISE_BASE_URL: URL where your Flowise instance is running
• FLOWISE_API_KEY: API key from Flowise (Settings > API Keys)

Usage

Running Directly

pnpm start

Running with Docker

# Build the Docker image
pnpm docker:build

# Run the container
pnpm docker:run

Configuring with MCP Clients

Add to your MCP client configuration (e.g., Claude Desktop, Claude Code):

Using Node directly:

{
  "mcpServers": {
    "flowise": {
      "command": "node",
      "args": ["/path/to/flowise-mcp-server/dist/index.js"],
      "env": {
        "FLOWISE_BASE_URL": "http://localhost:3000",
        "FLOWISE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "flowise": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--add-host=host.docker.internal:host-gateway",
        "--env-file", "/path/to/your/.env",
        "flowise-mcp-server"
      ]
    }
  }
}

Available Tools

Prediction Tools

Tool	Description
create_prediction	Run a chatflow with a question
create_prediction_with_history	Run with conversation history for context
create_prediction_with_files	Run with file attachments (images, documents)
create_prediction_with_lead	Run and capture lead email

Chatflow Management

Tool	Description
list_chatflows	List all available chatflows
get_chatflow	Get a specific chatflow's configuration
create_chatflow	Create a new chatflow
update_chatflow	Update an existing chatflow
delete_chatflow	Delete a chatflow (irreversible)

Node Discovery

Tool	Description
list_nodes	List all available node types
get_nodes_by_category	Get nodes filtered by category
get_node	Get detailed spec for a specific node type

Examples

Running a Chatflow

Use create_prediction with:
- chatflowId: "abc123"
- question: "What is the weather today?"

Creating a Simple Chatflow

1. Use get_node to fetch specs for needed nodes (e.g., "chatOpenAI", "llmChain")
2. Use create_chatflow with:
   - name: "My Chatflow"
   - flowData: { nodes: [...], edges: [...] }
   - type: "CHATFLOW"

Development

# Build TypeScript
pnpm build

# Run in development mode (build + run)
pnpm dev

Testing

The project includes comprehensive unit tests using Vitest.

# Run tests once
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage report
pnpm test:coverage

Test Structure

src/
├── flowise-api.test.ts   # API client tests (8 tests)
└── handlers.test.ts      # Tool handler tests (26 tests)

Project Structure

flowise-mcp-server/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── flowise-api.ts     # Flowise API client
│   ├── handlers.ts        # Tool handler functions
│   └── *.test.ts          # Unit tests
├── dist/                  # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── vitest.config.ts       # Test configuration
├── Dockerfile
├── .env.example           # Environment template
└── mcp-config.example.json

Troubleshooting

Connection Issues

• Ensure Flowise is running and accessible at the configured URL
• When using Docker, use host.docker.internal to connect to Flowise on the host machine
• Verify your API key is correct in Flowise settings

Authentication Errors

• Check that your FLOWISE_API_KEY matches one configured in Flowise
• API keys can be created in Flowise under Settings > API Keys

License

MIT - see LICENSE

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related Projects

• Flowise - Drag & drop UI to build LLM flows
• Model Context Protocol - Open protocol for LLM tool integration