FlowMCP

The world's first AI-to-3D data visualization bridge. An MCP server with 75 tools that lets any AI assistant transform raw data into interactive 3D spatial visualizations via Flow Immersive.

1363 tests. 40 smoke checks. Zero competitors in 3D viz MCP.

"Turn any data into an interactive 3D visualization from your AI assistant."

What It Does

FlowMCP connects AI assistants (Claude, GPT, Gemini) to Flow Immersive's 3D visualization platform. Say "visualize this data" and the AI analyzes, transforms, pre-computes layouts, and renders data in 3D — no code required.

Text/CSV → Extract → Analyze → Transform → Layout → Upload → 3D Visualization

Installation

npm install flow-immersive-mcp

Or from source:

git clone https://github.com/Halyxa/flowmcp.git
cd flowmcp
npm install
npm run build

Requirements: Node.js >= 18. Optional: FalkorDB for graph database queries.

Quick Start

With Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "flow-immersive": {
      "command": "node",
      "args": ["/path/to/flowmcp/dist/index.js"]
    }
  }
}

With MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Direct Execution (stdio)

node dist/index.js

HTTP Transport (remote deployment)

node dist/index.js --http                    # Default: http://127.0.0.1:3100/mcp
MCP_HTTP_PORT=8080 node dist/index.js --http # Custom port
MCP_AUTH_TOKEN=mysecret node dist/index.js --http # With bearer auth

Health check: GET /health returns {"status":"ok","tools":75,"transport":"streamable-http"}

Tools (75)

Intelligence & Analysis (5)

Tool	What it does
analyze_data_for_flow	Score data for 3D viz potential across 8 signal dimensions
validate_csv_for_flow	Diagnose CSV format and data quality for Flow
suggest_flow_visualization	Recommend optimal viz type from column metadata
get_flow_template	Setup instructions and column requirements per template
flow_nlp_to_viz	Natural language → synthetic data + template + instructions

Data Extraction (2)

Tool	What it does
flow_extract_from_text	Extract entities, relationships, metrics from text → CSV
flow_extract_from_url	Fetch URL → extract structured data → Flow-ready CSV

Flow API Gateway (8)

Tool	What it does
flow_authenticate	Email/password → bearer token (cached)
flow_upload_data	Create/update datasets via Flow API
flow_browse_flows	Browse 4k+ public flows (no auth)
flow_get_flow	Full flow definition by selector (no auth)
flow_list_templates	37 viz templates with column requirements
flow_list_categories	8 categories (derived from templates)
flow_semantic_search	Multi-signal search across public flows
generate_flow_python_code	Ready-to-run Python upload scripts

Compute-Intensive (6)

Tool	What it does
flow_precompute_force_layout	d3-force-3d → full convergence, instant-load x,y,z
flow_scale_dataset	Intelligent reduction: random, stratified, spatial binning
flow_compute_graph_metrics	Degree, PageRank, components, clustering per node
flow_cluster_data	K-means with auto k via silhouette scoring
flow_pca_reduce	Principal component analysis (2D or 3D projection)
flow_distance_matrix	Pairwise distance computation (euclidean/manhattan/cosine)

Graph & Network (2)

Tool	What it does
transform_to_network_graph	Edge list → Flow id + pipe-delimited connections
flow_query_graph	FalkorDB Cypher → Flow CSV + optional force layout

Statistical Analysis (5)

Tool	What it does
flow_correlation_matrix	Pairwise Pearson correlations → heatmap-ready matrix
flow_regression_analysis	Linear regression: slope, R², p-value, predicted/residual
flow_anomaly_detect	Z-score/IQR anomaly detection with scoring
flow_outlier_fence	Tukey fence outlier detection
flow_rank_values	Dense/ordinal/min/max ranking

Data Transformation (17)

Tool	What it does
flow_normalize_data	Min-max, z-score, or robust (MAD) normalization
flow_fill_missing	Impute: constant, mean, median, mode, forward fill, linear/nearest/zero interpolation
flow_deduplicate_rows	Remove duplicates with optional case-insensitive matching
flow_bin_data	Histogram binning (Sturges' rule)
flow_discretize	Equal-width/equal-frequency discretization
flow_computed_columns	Add calculated columns via safe formulas
flow_parse_dates	Extract year/month/day/quarter/epoch from dates
flow_validate_rules	Data quality: not_null, min, max, unique, pattern
flow_filter_rows	Filter by conditions: equals, contains, greater_than
flow_encode_categorical	Label or one-hot encoding
flow_string_split	Split delimited strings into columns
flow_string_extract	Regex capture group extraction
flow_column_stats	Descriptive stats: mean, median, std, quartiles
flow_describe_dataset	Full dataset profiling: shape, types, nulls, uniques
flow_lag_lead	Shift values forward/backward for time series
flow_concat_rows	Concatenate datasets vertically
flow_unpivot	Wide → long format transformation

Aggregation & Reshaping (5)

Tool	What it does
flow_pivot_table	Group by + aggregate (sum/avg/count/min/max)
flow_cross_tabulate	Contingency tables with aggregation
flow_window_functions	Rolling/sliding window operations
flow_cumulative	Running cumulative sum/min/max/count
flow_hierarchical_data	Flat data → hierarchical tree for network viz

Spatial & Temporal (4)

Tool	What it does
flow_geo_enhance	Geocoding: city/country → latitude/longitude
flow_time_series_animate	Temporal data → animation frames
flow_live_data	Real-time: USGS earthquakes, weather, World Bank
flow_compare_datasets	Side-by-side dataset diff

Export & Integration (3)

Tool	What it does
flow_export_formats	CSV → JSON, GeoJSON, HTML 3D viewer, stats summary
flow_merge_datasets	Join/concatenate CSVs with conflict resolution
flow_join_datasets	SQL-style joins (inner/left/right/full)

Narrative Intelligence (3)

Tool	What it does
flow_narrate_data	CSV → narrative arc with statistical characters, 3 styles
flow_guided_tour	CSV → tour stops with camera hints, narration, 5 focus strategies
flow_famous_network	Person name → Wikidata celebrity network CSV (zero-cost)

Data Generation (1)

Tool	What it does
flow_generate_synthetic	On-demand synthetic CSV: configurable schemas, distributions, correlations, network/geo/timeseries modes

Holodeck Intelligence (14)

Tools that transform datasets into explorable data worlds with progressive revelation, quests, and multi-lens analysis.

Tool	What it does
flow_quest_generator	Procedural quests from data topology — turns analysis into guided missions
flow_near_miss_detector	Find patterns that almost hold — the interesting failures in your data
flow_progressive_disclosure	Fog-of-war layering — reveal data progressively by depth or theme
flow_anomaly_explain	Detective-story anomaly narratives — why outliers exist, not just where
flow_insight_scorer	Statistical peer review — score and rank insights by significance
flow_waypoint_map	GPS waypoints for data worlds — navigation anchors across dimensions
flow_visor_mode	Switch analytical lenses (5 visors: statistical, network, temporal, spatial, categorical)
flow_data_world_builder	One-call data world synthesis — combines multiple tools into a complete explorable environment
flow_sparkle_engine	Progressive intelligence by dwell time — the longer you look, the smarter it gets
flow_exploration_dna	Dataset personality fingerprinting — characterize a dataset's analytical identity
flow_fog_of_war	Fog-of-war visibility system — progressive data reveal with exploration state tracking
flow_explorer_profile	Explorer personality profiling — classify exploration style and recommend strategies
flow_viral_video_spec	Viral video specification generator — data-driven storyboards for 3D viz content
flow_discovery_narrator	Discovery narration — real-time storytelling as data is explored

Plus 3 prompts and 5 resources for guided workflows.

Demos

Interactive 3D viewers generated by FlowMCP — Live Demo:

• Neural Network Architecture — 160 nodes, 2,610 connections
• Global Startup Funding — 420 companies, 30 countries
• Global Supply Chain — 100 nodes, 200 edges, 6 tiers
• Climate Change Indicators — 1,040 observations, 26 years

Pipeline Example

1. flow_extract_from_text       → entities + relationships from article
2. analyze_data_for_flow        → 3D fitness score (9.2/10)
3. transform_to_network_graph   → Flow network CSV format
4. flow_precompute_force_layout → offline physics → x,y,z positions
5. flow_compute_graph_metrics   → PageRank, centrality, communities
6. flow_upload_data             → push to Flow Immersive
7. flow_export_formats          → standalone HTML 3D viewer

Scripts

node scripts/demo-30-second.mjs      # 6-tool pipeline demo (describe → cluster → narrate → quest → stats)
node scripts/stress-test-force.mjs   # Force layout at scale: 1k → 50k nodes
node scripts/stress-test-tools.mjs   # Tool performance benchmark at increasing dataset sizes

Testing

npm test           # 1363 tests
npm run smoke-test # 40 standalone MCP checks
npm run ci         # Full pipeline: build + test + smoke

Environment Variables

Variable	Default	Description
FALKORDB_HOST	localhost	FalkorDB server host
FALKORDB_PORT	6379	FalkorDB server port
FALKORDB_USERNAME	—	FalkorDB auth username
FALKORDB_PASSWORD	—	FalkorDB auth password
MCP_AUTH_TOKEN	—	Bearer token for HTTP transport auth
MCP_HTTP_PORT	3100	HTTP transport port
MCP_HTTP_HOST	127.0.0.1	HTTP transport bind address

Sample Datasets

Pre-built datasets in samples/ for testing and demos:

Dataset	Rows	Type
demo-ai-ecosystem-network.csv	22 nodes	Network graph
tech-collaboration-network.csv	20 nodes	Network graph
supply-chain-network.csv	100 nodes	Network graph
neural-network-architecture.csv	160 nodes	Network graph
global-startup-funding.csv	420 rows	Geographic + funding
global-renewable-energy-map.csv	30 rows	Geographic + numeric
climate-change-indicators.csv	1,040 rows	Time series
saas-growth-timeseries.csv	36 rows	Time series
startup-metrics-scatter.csv	30 rows	Multi-dimensional
programming-languages-comparison.csv	20 rows	Multi-dimensional
celebrity-bryan-johnson.csv	16 nodes	Longevity network
celebrity-joe-rogan.csv	25 nodes	Podcast guest network
celebrity-taylor-swift.csv	30 nodes	Relationship + collaboration

Celebrity Network Demos

Pre-built in demos/ — exercise the Holodeck Intelligence tools:

Dataset	Nodes	Type
taylor-swift-network.csv	28	Music collaboration network
elon-musk-network.csv	30	Multi-domain company constellation
einstein-network.csv	25	Scientific collaboration network

License

MIT