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