Skip to main content
Glama
holoviz-viz-mcp

holoviz-viz-mcp

by ghostiee-11
README.md
# 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.

![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)
![Tests](https://img.shields.io/badge/tests-148%20passed-brightgreen.svg)
![Tools](https://img.shields.io/badge/MCP%20tools-36-purple.svg)
![MCP Apps](https://img.shields.io/badge/MCP%20Apps-8-orange.svg)
![Prompts](https://img.shields.io/badge/prompts-9-yellow.svg)
![License](https://img.shields.io/badge/license-MIT-lightgrey.svg)
![Version](https://img.shields.io/badge/version-0.5.0-blue.svg)

---

## 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

| Category | What you get |
|----------|-------------|
| **36 tools** | Data loading, transforms, 14 chart types, annotations, crossfiltering, streaming, dashboards, export, and more |
| **Intelligent analysis** | One-call auto-EDA, statistical testing (t-test, ANOVA, regression, chi-square), data quality scoring, natural language queries |
| **8 MCP Apps** | Specialized UI viewers for charts, dashboards, streaming, crossfilter, EDA reports, statistics, time series, and data quality |
| **9 workflow prompts** | Guided workflows for EDA, crossfiltering, statistics, time series, big data, comparisons, storytelling, dashboards, and data quality |
| **Big data** | Datashader-powered visualization for 10K-5M+ points |
| **Time series** | Rolling stats, trend decomposition, anomaly detection, multi-series comparison |
| **Dual output** | Every viz returns PNG preview (inline in chat) + interactive HTML (full Bokeh interactivity) |
| **Plot versioning** | Modify freely, undo anytime — every change creates a new version |
| **Session persistence** | Save/load entire analysis sessions as JSON |
| **8 sample datasets** | iris, penguins, tips, stocks, diamonds, gapminder, weather, earthquakes |
| **Professional templates** | Material Design, Bootstrap, and Fast Design dashboard layouts |

---

## Quick start

**Copy-paste these 4 lines to get started:**

```bash
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
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](DEMO_PROMPTS.md) for 12 ready-to-use demo prompts.

### Manual setup

<details>
<summary>Claude Desktop</summary>

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

```json
{
  "mcpServers": {
    "holoviz-viz": {
      "command": "holoviz-viz-mcp"
    }
  }
}
```
</details>

<details>
<summary>Claude Code (CLI)</summary>

```bash
claude mcp add holoviz-viz -- holoviz-viz-mcp
```
</details>

<details>
<summary>Cursor</summary>

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "holoviz-viz": {
      "command": "holoviz-viz-mcp"
    }
  }
}
```
</details>

<details>
<summary>VS Code Copilot Chat</summary>

Add to `.vscode/settings.json`:

```json
{
  "github.copilot.chat.mcpServers": {
    "holoviz-viz": {
      "command": "holoviz-viz-mcp"
    }
  }
}
```
</details>

---

## Tools (36)

### Data Management (5)

| Tool | Description |
|------|------------|
| `load_data` | Load from CSV/JSON text, URL, or file. Auto-detects Parquet/Excel/JSON from extension |
| `load_sample_data` | 8 built-in datasets: iris, penguins, tips, stocks, diamonds, gapminder, weather, earthquakes |
| `list_datasets` | List all loaded datasets with shapes and columns |
| `analyze_data` | Statistical profile with distributions, correlations, and data types |
| `suggest_visualizations` | Auto-recommend plot types based on column characteristics |

### Data Transformation (2)

| Tool | Description |
|------|------------|
| `transform_data` | Filter, groupby, sort, derive columns, sample, drop nulls, pivot |
| `merge_datasets` | Join two datasets on shared columns (inner/left/right/outer) |

### Visualization (5)

| Tool | Description | Output |
|------|------------|--------|
| `create_plot` | 14 chart types: scatter, line, bar, barh, area, step, box, violin, hist, heatmap, hexbin, kde, contour, errorbars | PNG + HTML |
| `modify_plot` | Change title, colors, colormap, size, axis labels, legend position | PNG + HTML |
| `undo_plot` | Revert to any previous version | PNG + HTML |
| `list_plots` | List all plots with IDs and version counts | Text |
| `execute_code` | Run arbitrary hvPlot/HoloViews/Panel code | PNG + HTML |

### Advanced Visualization (6)

| Tool | Description | Output |
|------|------------|--------|
| `create_crossfilter` | Linked brushing across views — select in one, all update | PNG + HTML |
| `create_streaming_plot` | Live-updating chart with play/pause/reset controls | PNG + HTML |
| `annotate_plot` | Add hline/vline/hspan/vspan/text/point/arrow annotations | PNG + HTML |
| `overlay_plots` | Composite multiple plots onto shared axes | PNG + HTML |
| `create_datashader_plot` | Big data visualization for 10K-5M+ points | PNG + HTML |
| `time_series_analysis` | Rolling stats, decomposition, anomaly detection, multi-series comparison | PNG + HTML |

### Interactive (4)

| Tool | Description |
|------|------------|
| `handle_click` | Process chart clicks — returns percentile, outlier status, group context |
| `set_theme` | Set global theme: default, dark, midnight |
| `launch_panel` | Open any chart as a full Panel app in the browser |
| `stop_panel` | Stop a running Panel server |

### Dashboard & Export (3)

| Tool | Description | Output |
|------|------------|--------|
| `create_dashboard` | Combine plots in column/row/tabs/grid with Material/Bootstrap/Fast templates | PNG + HTML |
| `get_plot_html` | Get raw interactive HTML for embedding | HTML |
| `export_plot` | Export to HTML, PNG, or SVG | Encoded |

### Intelligent Analysis (4)

| Tool | Description | Output |
|------|------------|--------|
| `auto_eda` | One-call complete EDA: distributions, correlations, missing data, outliers, narrative insights | PNG + HTML |
| `statistical_test` | T-test, correlation, regression, chi-square, normality, ANOVA — real p-values + diagnostic plots | PNG + HTML |
| `data_quality_report` | Missing values, outliers, type validation, duplicates, quality score (0-100) | PNG + HTML |
| `compare_datasets` | Side-by-side statistical comparison of two datasets | Text |

### Natural Language (1)

| Tool | Description |
|------|------------|
| `natural_language_query` | Plain English -> structured execution plan. "Show sales by region where revenue > 1M" -> filter + groupby + bar chart |

### Utility (6)

| Tool | Description |
|------|------------|
| `describe_plot` | AI-readable plot description for accessibility and context |
| `clone_plot` | Duplicate a plot for independent modification |
| `get_data_sample` | Return formatted data rows for AI context |
| `save_session` | Persist datasets + plot specs to JSON |
| `load_session` | Restore a saved session |
| `generate_large_dataset` | Generate synthetic data (clusters/spiral/grid/uniform, up to 5M points) |

---

## MCP Apps (8 interactive viewers)

| Resource URI | Viewer | Key features |
|-------------|--------|-------------|
| `ui://holoviz/viz` | Chart Viewer | Theme toggle, save, open in browser |
| `ui://holoviz/dashboard` | Dashboard Viewer | Multi-panel layout with stats sidebar |
| `ui://holoviz/stream` | Stream Viewer | Live pulse indicator, status bar |
| `ui://holoviz/crossfilter` | Crossfilter Viewer | Linked brush hint, open full size |
| `ui://holoviz/eda` | EDA Report | Tabbed insights/charts, completion badge |
| `ui://holoviz/statistics` | Statistics Viewer | P-value highlighting (green/red), side-by-side results+chart |
| `ui://holoviz/timeseries` | Time Series Viewer | Metrics bar, analysis type badge |
| `ui://holoviz/quality` | Quality Report | Score gauge (0-100, color-coded), issue severity cards |

---

## Workflow Prompts (9)

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

| Prompt | Purpose |
|--------|---------|
| `eda_workflow` | Complete exploratory data analysis |
| `crossfilter_workflow` | Build linked brushing dashboards |
| `data_quality_workflow` | Assess and clean data quality |
| `statistical_analysis_workflow` | Rigorous hypothesis testing |
| `storytelling_workflow` | Data storytelling with annotations |
| `time_series_workflow` | Temporal analysis and trend detection |
| `big_data_workflow` | Datashader visualization for large datasets |
| `comparison_workflow` | Compare groups or datasets |
| `dashboard_design_workflow` | Polished, presentation-ready dashboards |

---

## 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)

```python
# 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

```bash
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

```bash
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

TDQS

A3.6/5.0

Scored across 36 tools

Disambiguation4/5

Most tools have clearly distinct purposes with detailed descriptions. Some overlap exists (e.g., analyze_data vs. auto_eda vs. data_quality_report) but descriptions emphasize different aspects. Overall, an agent can reliably distinguish tools.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., analyze_data, create_plot, export_plot). There are no deviations or mixed conventions, making it easy to predict tool names.

Tool Count3/5

With 36 tools, the server is on the heavier side for a typical MCP server. While it provides extensive functionality for visualization and data analysis, the count feels slightly bloated and could be streamlined by merging related tools.

Completeness5/5

The tool surface is exceptionally complete: data loading, transformation, analysis, statistical testing, plotting, animation, dashboards, crossfilters, streaming, and session management are all covered. There are no obvious gaps for the intended domain.

Maintenance

ActivityInactive
ResponsivenessNo recent community issues