flowspec-mcp

MCP (Model Context Protocol) server for FlowSpec — exposes project specifications to Claude Code and other MCP-compatible AI tools.

Quick Start

Add to your ~/.claude.json:

{
  "mcpServers": {
    "flowspec": {
      "command": "npx",
      "args": ["-y", "flowspec-mcp"],
      "env": {
        "FLOWSPEC_MODE": "cloud",
        "DATABASE_URL": "your-neon-connection-string",
        "FLOWSPEC_USER_ID": "your-clerk-user-id"
      }
    }
  }
}

Local Mode (with FlowSpec Desktop)

{
  "mcpServers": {
    "flowspec": {
      "command": "npx",
      "args": ["-y", "flowspec-mcp"],
      "env": {
        "FLOWSPEC_MODE": "local"
      }
    }
  }
}

Local mode connects to the FlowSpec desktop server at http://localhost:3456.

Environment Variables

Variable	Required	Default	Description
FLOWSPEC_MODE	No	cloud	cloud for direct Neon SQL, local for desktop server HTTP
DATABASE_URL	Cloud mode	—	Neon Postgres connection string
FLOWSPEC_USER_ID	Cloud mode	—	Clerk user ID — find yours at flowspec.app/account
FLOWSPEC_LOCAL_URL	No	http://localhost:3456	Desktop server URL (local mode)

Available Tools (v5.6.0 — 32 tools)

Set FLOWSPEC_TOOLS=core for 11 essential tools only. Default (all) loads all 32.

Read Tools

• flowspec_list_projects — List all projects with names and dates
• flowspec_get_json — Get full JSON spec for a project (optimised for Claude Code)
• flowspec_get_project — Get raw canvas_state JSON
• flowspec_search_nodes — Search nodes by label across all projects
• flowspec_get_screen_context — Get screen/region/element structure

Write Tools

• flowspec_create_project — Create a new project
• flowspec_update_project — Update project name or canvas state
• flowspec_delete_project — Delete a project
• flowspec_clone_project — Clone a project for backup or branching
• flowspec_create_node — Add a node (datapoint, component, transform, table, actor)
• flowspec_update_node — Update node data or position
• flowspec_delete_node — Remove a node and connected edges
• flowspec_create_edge — Connect two nodes with an edge type
• flowspec_update_edge — Update edge type, label, or handle positions
• flowspec_delete_edge — Remove an edge
• flowspec_analyse_project — Run orphan node and duplicate label analysis
• flowspec_validate_project — Validate data flow semantics and type matching

Bulk / Import Tools

• flowspec_import_json — Import a JSON spec (create/merge nodes, edges, screens)
• flowspec_auto_layout — Auto-arrange nodes using dagre hierarchical layout

Screen & Region Tools

• flowspec_upload_image — Upload a wireframe image and get its URL
• flowspec_create_screen — Add a wireframe screen to a project
• flowspec_update_screen — Update screen name or image properties
• flowspec_delete_screen — Delete a screen and its regions
• flowspec_add_region — Add an annotated region to a screen
• flowspec_update_region — Update region position, size, or linked elements
• flowspec_remove_region — Remove a region from a screen

Decision Tree Tools

• flowspec_list_decision_trees — List decision trees for a project
• flowspec_get_decision_tree — Get a decision tree with full node/edge structure
• flowspec_delete_decision_tree — Delete a decision tree
• flowspec_analyse_decision_tree — Analyse tree depth, outcomes, and issues

Boring Logic Board Tools

• flowspec_get_logic_board — Get the logic board (input/output/process/decision canvas)
• flowspec_upsert_logic_board — Save the logic board state for a project

Development

npm install
npm run build
node dist/index.js

Notes

• MCP SDK pinned to 1.12.1 due to zod v4 compatibility constraints in later versions
• Node.js >= 18.0.0 required

License

MIT