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

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
demos		demos
deploy		deploy
docs		docs
samples		samples
scripts		scripts
skills		skills
src		src
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
README.md		README.md
SPEC.md		SPEC.md
TESTING.md		TESTING.md
TOOLS-REFERENCE.md		TOOLS-REFERENCE.md
events.jsonl		events.jsonl
package-lock.json		package-lock.json
package.json		package.json
predictions.jsonl		predictions.jsonl
state.json		state.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

FlowMCP

What It Does

Installation

Quick Start

With Claude Desktop

With MCP Inspector

Direct Execution (stdio)

HTTP Transport (remote deployment)

Tools (75)

Intelligence & Analysis (5)

Data Extraction (2)

Flow API Gateway (8)

Compute-Intensive (6)

Graph & Network (2)

Statistical Analysis (5)

Data Transformation (17)

Aggregation & Reshaping (5)

Spatial & Temporal (4)

Export & Integration (3)

Narrative Intelligence (3)

Data Generation (1)

Holodeck Intelligence (14)

Demos

Pipeline Example

Scripts

Testing

Environment Variables

Sample Datasets

Celebrity Network Demos

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages