holoviz-viz-mcp

holoviz-viz-mcp

The most advanced MCP server for data visualization. Give any AI assistant the power to create interactive charts, run statistical tests, perform auto-EDA, and build polished dashboards — all using the HoloViz ecosystem.

Why this exists

Most AI visualization tools generate static images or hand-roll JavaScript. This server uses Panel's embed mode to produce self-contained interactive HTML with the full Bokeh rendering pipeline — real pan/zoom/hover, linked selections, and Panel widgets. Not a JavaScript approximation.

pn.pane.HoloViews(plot).save(buf, embed=True)

One line. Standalone HTML. All Bokeh JS/CSS inlined. No server. No CDN. Open in any browser.

Feature highlights

Quick start

Copy-paste these 4 lines to get started:

git clone https://github.com/ghostiee-11/holoviz-viz-mcp.git
cd holoviz-viz-mcp
pip install -e .
claude mcp add holoviz-viz -- holoviz-viz-mcp

That's it — restart your AI client and start asking for visualizations.

One-command setup for any AI client

bash setup.sh claude-desktop    # Claude Desktop
bash setup.sh claude-code       # Claude Code CLI
bash setup.sh cursor            # Cursor
bash setup.sh vscode            # VS Code Copilot
bash setup.sh all               # All clients at once

Restart your AI client and try:

"Load the iris dataset and create a scatter plot of sepal_length vs sepal_width, colored by species"

"Run auto_eda on the diamonds dataset"

"Test if sepal_length differs significantly between species using a t-test"

See DEMO_PROMPTS.md for 12 ready-to-use demo prompts.

Manual setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "holoviz-viz": {
      "command": "holoviz-viz-mcp"
    }
  }
}

claude mcp add holoviz-viz -- holoviz-viz-mcp

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "holoviz-viz": {
      "command": "holoviz-viz-mcp"
    }
  }
}

Add to .vscode/settings.json:

{
  "github.copilot.chat.mcpServers": {
    "holoviz-viz": {
      "command": "holoviz-viz-mcp"
    }
  }
}

Tools (36)

Data Management (5)

Data Transformation (2)

Visualization (5)

Advanced Visualization (6)

Interactive (4)

Dashboard & Export (3)

Intelligent Analysis (4)

Natural Language (1)

Utility (6)

MCP Apps (8 interactive viewers)

Workflow Prompts (9)

Pre-built step-by-step guides that the AI follows:

Architecture

AI Assistant (Claude / Copilot / Cursor / any MCP client)
    |
    v  MCP Protocol (JSON-RPC 2.0 over stdio)
+------------------------------------------------------------------+
|  holoviz-viz-mcp Server (FastMCP 3.1)                             |
|                                                                   |
|  Data Layer (7 tools)        Viz Layer (11 tools)                 |
|    load_data, analyze_data     create_plot (14 chart types)       |
|    suggest_visualizations      crossfilter, streaming, datashader |
|    transform_data, merge       annotate, overlay, time_series     |
|                                                                   |
|  Intelligence Layer (5 tools)  Utility Layer (6 tools)            |
|    auto_eda                    describe_plot, clone_plot           |
|    statistical_test            get_data_sample                    |
|    data_quality_report         save/load_session                  |
|    natural_language_query      generate_large_dataset             |
|                                                                   |
|  Rendering Pipeline            State Manager                      |
|    hvPlot -> HoloViews           Versioned plots with undo        |
|    -> Panel embed=True           Dataset storage                  |
|    Output: PNG + HTML            Session persistence              |
|                                                                   |
|  8 MCP Apps  |  9 Prompts  |  3 Dashboard Templates              |
+------------------------------------------------------------------+

How the output works

Each visualization tool returns three items in a single MCP response:

1. TextContent — Plot ID and description
2. ImageContent — PNG preview (renders inline in chat)
3. EmbeddedResource — Interactive HTML at viz://plots/{id} (self-contained Bokeh document)

This dual-output pattern means the AI shows a quick preview while providing the full interactive version.

Examples

Auto-EDA (one call, complete analysis)

> "Run auto_eda on the diamonds dataset"

Returns: 6+ charts (distributions, correlations, categories, scatter),
narrative insights (skewness, outliers, strongest correlations),
all in a single tool call.

Statistical testing with real p-values

> "Test if sepal_length differs between iris species"

Returns: t-statistic, p-value, Cohen's d effect size,
box plot comparing groups, significance assessment.

Crossfilter (linked brushing)

# Behind the scenes:
from holoviews.selection import link_selections
linked = link_selections(hv.Layout([scatter, hist, box]))
# Brush in scatter -> histogram and box plot filter in real time

Time series decomposition

> "Decompose the weather temperature into trend, seasonal, and residual"

Returns: 4-panel decomposition plot + trend stats + seasonal amplitude.

Natural language queries

> natural_language_query("iris", "compare sepal_length by species")

Returns structured plan:
  Step 1: transform_data('iris', 'groupby', group_by='species', agg='mean')
  Step 2: create_plot('iris_grouped', 'bar', x='species', y='sepal_length')

Demos

python demos/quick_demo.py                # Full feature tour
python demos/showcase_stock_analysis.py   # Stock prices + annotations + dashboard
python demos/showcase_ml_evaluator.py     # Feature importance + confusion matrix + crossfilter

Testing

pytest tests/ -v
# 148 tests across 16 test files covering:
# state, data, viz, transforms, crossfilter, streaming, annotations,
# export, interaction, auto-EDA, statistics, data quality, NLQ,
# big data, time series, utilities, server integration

Project structure

src/holoviz_viz_mcp/
  server.py            # FastMCP entry: 36 tools, 8 resources, 9 prompts
  state.py             # Dataset + plot state with versioning/undo
  rendering.py         # HoloViews -> PNG/HTML via Panel embed (+ Material/Bootstrap/Fast templates)
  tools/
    data.py            # load, analyze, suggest, list, sample (8 datasets)
    transform.py       # filter, groupby, pivot, derive, merge
    viz.py             # create, modify, undo, list, execute_code
    crossfilter.py     # linked selections via hv.link_selections
    streaming.py       # live-updating charts with BokehJS streaming
    annotations.py     # hline, vline, spans, text, points, arrows, overlays
    dashboard.py       # layout composition with template support
    export.py          # HTML/PNG/SVG export
    interact.py        # handle_click, set_theme, launch/stop_panel
    auto_eda.py        # one-call complete exploratory analysis
    statistics.py      # t-test, correlation, regression, chi2, normality, ANOVA
    data_quality.py    # quality report + dataset comparison
    nlq.py             # natural language query interpretation
    bigdata.py         # datashader + synthetic data generation
    timeseries.py      # rolling stats, decomposition, anomaly detection
    utils.py           # describe, clone, sample, session management
  apps/
    viz.html           # Chart viewer with toolbar
    dashboard.html     # Dashboard viewer with stats
    stream.html        # Streaming viewer with pulse indicator
    crossfilter.html   # Crossfilter viewer with brush hints
    eda.html           # EDA report with tabbed insights
    statistics.html    # Statistics viewer with p-value highlights
    timeseries.html    # Time series viewer with metrics
    quality.html       # Quality report with score gauge
tests/                 # 148 tests across 16 files
demos/                 # 3 showcase scripts

Technical notes

• Panel embed vs raw BokehJS: Most MCP viz tools use bokeh.embed.json_item() for static Bokeh. Panel's embed=True captures widget state, linked selections, and layout logic into standalone HTML. This is what makes crossfiltering work without a server.

• Why hvPlot: Consistent .hvplot() API across pandas, xarray, dask, and geopandas. One API, many backends.

• State management: Plots are versioned. Every modify_plot creates a new version; undo_plot reverts. The AI iterates freely without losing previous work.

• Statistical rigor: Uses scipy.stats for real hypothesis testing — actual p-values, effect sizes, confidence intervals. Not approximations.

• Code execution: execute_code is the escape hatch — run arbitrary HoloViews/Panel code in a sandboxed namespace with pd, np, hv, pn, and all loaded datasets.

• Dashboard templates: create_dashboard supports template_style='material' (Material Design), 'bootstrap' (Bootstrap), and 'fast' (Fast Design) for polished, professional output.

Dependencies

Core: fastmcp, holoviews, hvplot, panel, bokeh, pandas, numpy, scipy

Optional: openpyxl (Excel), pyarrow (Parquet), scikit-learn (sample data)

License

MIT