Langflow Builder MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to programmatically build and modify Langflow flows. Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

Give your AI assistant the ability to create flows, add components, wire up agents with tools, write custom components inline, and manage your entire Langflow workspace — all through natural language.

Features

• Component Discovery — List, search, and inspect schemas for all available Langflow components
• Flow Management — Create, read, update, delete, and duplicate flows
• Node Manipulation — Add, configure, move, and remove nodes with full template control
• Custom Components — Write Python components inline with no server restart required
• Tool Mode — Enable tool_mode on any component so Agents can call it as a tool
• Connection Management — Connect/disconnect nodes with automatic type validation
• Build & Execute — Run flows and get results, with proper NDJSON streaming support
• Layout Engine — Analyze, auto-arrange, and manually position nodes for clean layouts
• Source Explorer — Search and read Langflow's source code to understand internals

Quick Start

1. Install

# Using pip
pip install langflow-builder-mcp

# Using uv (recommended)
uv pip install langflow-builder-mcp

# From source
git clone https://github.com/sportsrecruits/langflow-builder-mcp.git
cd langflow-builder-mcp
pip install -e .

2. Create a Langflow API Key

The MCP server authenticates with Langflow using an API key. To create one:

1. Open your Langflow instance in a browser
2. Click your profile icon (bottom-left corner of the sidebar)
3. Select Settings
4. Go to the Langflow API section
5. Click Add New to generate a new API key
6. Copy the key — you'll need it in the next step

If you're running Langflow locally with default settings and have not enabled authentication, you may need to start Langflow with --auto-login disabled or configure a superuser to access the API settings.

3. Configure

The server connects to a running Langflow instance. Set your Langflow URL and API key:

export LANGFLOW_MCP_LANGFLOW_URL="http://localhost:7860"
export LANGFLOW_MCP_API_KEY="sk-..."

4. Add to your AI tool

See Installation per Tool below for Claude Code, Cursor, Windsurf, etc.

Installation per Tool

Claude Code

Add to your project-level MCP config (.mcp.json in your project root):

{
  "mcpServers": {
    "langflow-builder": {
      "command": "python",
      "args": ["-m", "langflow_builder_mcp.server"],
      "env": {
        "LANGFLOW_MCP_LANGFLOW_URL": "http://localhost:7860",
        "LANGFLOW_MCP_API_KEY": "sk-..."
      }
    }
  }
}

Or add it globally at ~/.claude/mcp.json to make it available in all projects.

Claude Desktop

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

{
  "mcpServers": {
    "langflow-builder": {
      "command": "python",
      "args": ["-m", "langflow_builder_mcp.server"],
      "env": {
        "LANGFLOW_MCP_LANGFLOW_URL": "http://localhost:7860",
        "LANGFLOW_MCP_API_KEY": "sk-..."
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "langflow-builder": {
      "command": "python",
      "args": ["-m", "langflow_builder_mcp.server"],
      "env": {
        "LANGFLOW_MCP_LANGFLOW_URL": "http://localhost:7860",
        "LANGFLOW_MCP_API_KEY": "sk-..."
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "langflow-builder": {
      "command": "python",
      "args": ["-m", "langflow_builder_mcp.server"],
      "env": {
        "LANGFLOW_MCP_LANGFLOW_URL": "http://localhost:7860",
        "LANGFLOW_MCP_API_KEY": "sk-..."
      }
    }
  }
}

Using uvx (no install needed)

If you have uv installed, you can run without installing:

{
  "mcpServers": {
    "langflow-builder": {
      "command": "uvx",
      "args": ["langflow-builder-mcp"],
      "env": {
        "LANGFLOW_MCP_LANGFLOW_URL": "http://localhost:7860",
        "LANGFLOW_MCP_API_KEY": "sk-..."
      }
    }
  }
}

Configuration

All configuration is via environment variables with the LANGFLOW_MCP_ prefix:

You can also place these in a .env file in your working directory.

Custom Headers

If your Langflow endpoint requires additional authorization headers (e.g., a reverse proxy with Bearer auth, custom gateway tokens, or org-level API keys), use LANGFLOW_MCP_CUSTOM_HEADERS to include them in every request:

export LANGFLOW_MCP_CUSTOM_HEADERS='{"Authorization": "Bearer my-gateway-token", "X-Org-Id": "org-123"}'

Or in your MCP config JSON:

{
  "mcpServers": {
    "langflow-builder": {
      "command": "python",
      "args": ["-m", "langflow_builder_mcp.server"],
      "env": {
        "LANGFLOW_MCP_LANGFLOW_URL": "http://localhost:7860",
        "LANGFLOW_MCP_API_KEY": "sk-...",
        "LANGFLOW_MCP_CUSTOM_HEADERS": "{\"Authorization\": \"Bearer my-gateway-token\"}"
      }
    }
  }
}

The value must be a valid JSON object mapping header names to string values. These headers are merged with the default headers (Content-Type and x-api-key), and custom headers take precedence if there's a conflict.

Available Tools

Component Discovery

Flow Management

Build & Execution

Node Manipulation

Layout & Positioning

Connection Management

Langflow Source Exploration

Examples

Build a Flow Step by Step

"Create a flow where a Chat Input feeds into a Prompt template, which then goes to an OpenAI model, and finally to Chat Output"

create_flow(name="Prompt Chain")

add_node(flow_id="...", component_type="ChatInput", position_x=100, position_y=300)
add_node(flow_id="...", component_type="Prompt", position_x=600, position_y=300)
add_node(flow_id="...", component_type="OpenAIModel", position_x=1100, position_y=300)
add_node(flow_id="...", component_type="ChatOutput", position_x=1600, position_y=300)

connect_nodes(source_node_id="ChatInput-abc", source_output="message",
              target_node_id="Prompt-def", target_input="input_value")
connect_nodes(source_node_id="Prompt-def", source_output="prompt",
              target_node_id="OpenAIModel-ghi", target_input="input_value")
connect_nodes(source_node_id="OpenAIModel-ghi", source_output="text",
              target_node_id="ChatOutput-jkl", target_input="input_value")

build_flow(flow_id="...")

Add a Custom Component (No Restart!)

"Add a custom component that reverses the input text and connects it to the agent as a tool"

add_custom_component(
  flow_id="...",
  tool_mode=True,
  code="""
from langflow.custom import Component
from langflow.io import MessageTextInput, Output
from langflow.schema.message import Message

class TextReverser(Component):
    display_name = "Text Reverser"
    description = "Reverses the input text"
    icon = "ArrowLeftRight"

    inputs = [
        MessageTextInput(
            name="input_text",
            display_name="Input Text",
            tool_mode=True,
        ),
    ]

    outputs = [
        Output(display_name="Reversed", name="reversed", method="reverse_text"),
    ]

    def reverse_text(self) -> Message:
        text = self.input_text if isinstance(self.input_text, str) else self.input_text.text
        return Message(text=text[::-1])
"""
)

connect_nodes(source_node_id="TextReverser-xyz", source_output="component_as_tool",
              target_node_id="Agent-abc", target_input="tools")

The component is validated and added instantly — no Langflow restart needed. With tool_mode=True, it automatically gets a component_as_tool output that the Agent can call.

Enable Tool Mode on an Existing Component

"Make the URL Reader component usable as a tool by the agent"

set_tool_mode(flow_id="...", node_id="URLReader-abc", enabled=True)

connect_nodes(source_node_id="URLReader-abc", source_output="component_as_tool",
              target_node_id="Agent-def", target_input="tools")

Create a Custom Data Processor as a Tool

"Create a component that parses CSV text into structured data"

add_custom_component(
  flow_id="...",
  tool_mode=True,
  code="""
import csv
import io
from langflow.custom import Component
from langflow.io import MessageTextInput, Output
from langflow.schema import Data

class CSVParser(Component):
    display_name = "CSV Parser"
    description = "Parses CSV text into structured records"
    icon = "Table"

    inputs = [
        MessageTextInput(
            name="csv_text",
            display_name="CSV Text",
            info="Raw CSV content to parse",
            tool_mode=True,
        ),
    ]

    outputs = [
        Output(display_name="Records", name="records", method="parse_csv"),
    ]

    def parse_csv(self) -> Data:
        text = self.csv_text if isinstance(self.csv_text, str) else self.csv_text.text
        reader = csv.DictReader(io.StringIO(text))
        records = [row for row in reader]
        self.status = f"Parsed {len(records)} records"
        return Data(data={"records": records, "count": len(records)})
"""
)

Modify an Existing Flow

"Change the model in my agent to Claude and update the system prompt"

list_flows()
get_flow(flow_id="...")

update_node(flow_id="...", node_id="Agent-abc",
            config={"model_name": "claude-3-5-sonnet", "system_prompt": "You are a coding assistant."})

build_flow(flow_id="...")

Explore What Components Are Available

"What vector store components does Langflow have?"

search_components(query="vector")

Returns matching components like Qdrant, Pinecone, Chroma, AstraDB, etc. with descriptions.

"Show me the full schema for the Qdrant component"

get_component_schema(component_type="Qdrant")

Returns all inputs (with types, defaults, options), outputs, and base classes.

Layout and Arrangement

"Clean up the layout of my flow"

analyze_flow_layout(flow_id="...")
get_layout_suggestions(flow_id="...")
auto_arrange_flow(flow_id="...", direction="horizontal", spacing=400)

Or for precise control:

move_nodes_batch(flow_id="...", moves=[
  {"node_id": "ChatInput-abc", "x": 100, "y": 300},
  {"node_id": "Agent-def", "x": 800, "y": 300},
  {"node_id": "ChatOutput-ghi", "x": 1500, "y": 300},
  {"node_id": "OpenAIModel-jkl", "x": 600, "y": 0},
])

Key Concepts

Custom Components: Inline Code vs File-Based

This MCP server uses inline code for custom components. When you call add_custom_component, the Python code is sent to Langflow's API which evaluates it dynamically and builds the node template on the fly. The code is stored directly on the node — no .py file creation, no server restart.

This is the same mechanism the Langflow UI uses when you edit a Custom Component node.

Tool Mode

Any Langflow component can be made into a tool that an Agent can call. When you enable tool_mode:

1. The component's outputs are replaced with a single component_as_tool output (type: Tool)
2. A tools_metadata field is added for configuring tool names and descriptions
3. The component_as_tool output can be connected to an Agent's tools input

Use set_tool_mode or pass tool_mode=True to add_node/add_custom_component.

Important: Inputs marked tool_mode=True in the component code become parameters the Agent provides at call time. Inputs without tool_mode (or tool_mode=False) remain as static configuration.

Build vs Save

API changes (adding nodes, connecting, updating config) only modify the flow's saved structure. Components don't execute until you call build_flow. Always build after making changes to verify everything works.

Architecture

src/langflow_builder_mcp/
├── server.py           # MCP server entry point and tool registrations
├── instructions.py     # MCP server instructions for LLM guidance
├── concepts.py         # Langflow concept reference documentation
├── config.py           # Environment configuration (pydantic-settings)
├── client.py           # Langflow HTTP API client (with NDJSON support)
├── types.py            # Pydantic data models
├── schema_cache.py     # Component metadata cache
├── validator.py        # Connection type validation
├── generators.py       # Node/edge ID and structure generators
├── layout_engine.py    # Flow layout analysis and optimization
├── source_repo.py      # Langflow source code exploration
├── backup.py           # Flow backup functionality
└── tools/
    ├── build.py        # Build and execution tools
    ├── components.py   # Component discovery tools
    ├── flows.py        # Flow CRUD tools
    ├── nodes.py        # Node manipulation tools
    ├── edges.py        # Connection management tools
    └── source.py       # Langflow source code exploration tools

Development

# Clone and install in development mode
git clone https://github.com/sportsrecruits/langflow-builder-mcp.git
cd langflow-builder-mcp
pip install -e ".[dev]"

# Run tests
pytest

# Format code
ruff format .

# Lint
ruff check .

Running the server directly

# Via the entry point
langflow-builder-mcp

# Via Python module
python -m langflow_builder_mcp.server

The server communicates over stdio using the MCP protocol. It's designed to be launched by an MCP client (Claude Code, Cursor, etc.), not run standalone.

Troubleshooting

"Component type not found"

The component name is case-sensitive and must match exactly. Use search_components to find the correct name:

search_components(query="openai")

"Error executing tool build_flow"

Make sure your Langflow instance is running and accessible at the configured URL. The build API uses NDJSON streaming — this server handles it correctly, but network timeouts on large flows may need the timeout increased:

export LANGFLOW_MCP_REQUEST_TIMEOUT=60.0

Custom component code errors

If add_custom_component fails, the error message will include the validation error from Langflow. Common issues:

• Missing imports (always import from langflow.custom, langflow.io, langflow.schema)
• Method referenced in Output doesn't exist on the class
• Return type annotation missing on output methods

Connection type mismatches

Use validate_connection before connecting, or find_compatible_connections to discover what can connect to what:

find_compatible_connections(flow_id="...", node_id="Agent-abc", direction="inputs")

License

MIT