HoloViz MCP Server

Let AI agents create interactive visualizations that render live inside your chat — no code required.

Built with FastMCP · Panel · HoloViews · hvPlot · Bokeh

PyPI Python License

27 MCP tools · 4 interactive UI templates · live streaming · bidirectional interaction

Demo

1. Inline Chart

"Create a bar chart comparing programming language popularity: Python=32%, JavaScript=28%, Java=18%, TypeScript=12%, Others=10%"

2. Panel Widgets & Interactivity

"Build a Panel dashboard with a slider controlling sigma in a normal distribution, updating the histogram in real time"

3. Streaming / Live Data

"Create a live dashboard showing a real-time sine wave that updates every 500ms"

4. Remote Data Loading

"Load this dataset and profile it, then show a correlation heatmap: https://raw.githubusercontent.com/mwaskom/seaborn-data/master/tips.csv"

5. Maps

"Plot the top 10 most populous cities in the world on an interactive tile map with population shown as point size"

6. Multi-Panel Dashboard

"Build a dashboard with 3 panels: a bar chart of fruit sales (Apple=50, Banana=30, Mango=45), a pie chart of the same data, and a summary stats table"

7. Bidirectional Interaction

"Create an interactive scatter plot of the tips dataset where selecting points in the chart updates a summary statistics table below it"

Architecture

This project is designed as an MCP-native visualization platform: LLMs call tools, the server validates and executes visualization code safely, and users get live, interactive UIs inline in chat.

Architecture at a glance

Layer responsibilities

End-to-end flow

1. An agent calls a tool such as show or stream.
2. The server runs a 5-layer validation pipeline (syntax, security, packages, extensions, runtime).
3. Validated code/config is sent to the Panel display subprocess via REST.
4. The display server executes and persists the snippet in SQLite.
5. The tool returns either:
   • a Bokeh JSON spec for direct in-chat embedding, or
   • a Panel URL rendered in an iframe.
6. MCP App templates provide rich UX (filters, theme toggle, exports, click-to-insight).

Development Setup

For contributing or running from source:

1. Install Pixi

curl -fsSL https://pixi.sh/install.sh | bash
source ~/.bashrc

2. Clone and install

git clone https://github.com/SuMayaBee/HoloViz-MCP-Server
cd HoloViz-MCP-Server

pixi install
pixi run postinstall

3. Verify

.pixi/envs/default/bin/hvmcp --version

Example Prompts

Simple chart:

Create a bar chart showing: Jan=120, Feb=95, Mar=140, Apr=110

Scatter plot:

Show a scatter plot of 50 random points using hvplot

Full dashboard:

Create a dashboard with this sales data:
products=[Apples, Bananas, Oranges, Grapes],
revenue=[500, 300, 450, 200],
units=[50, 30, 45, 20]

Load a dataset:

Load /path/to/data.csv and create a visualization

Live streaming chart:

Create a live streaming chart that updates every second with random values

Explore available tools:

What hvplot chart types are available?
What Panel widgets are available?
Show me the hvplot skill guide

Features

Core Visualization

• Ask your AI assistant to create a chart — renders inline in the chat via MCP Apps
• Interactive charts (zoom, pan, hover) powered by Bokeh
• Every visualization persisted and accessible via URL
• Works in VS Code Insiders, Claude Desktop, and Cursor

View Code Button

Every chart rendered inline has a View Code button in the toolbar — click it to see the exact Python that generated the visualization, with a one-click copy. Great for learning HoloViz.

Kaggle Integration

Paste any Kaggle dataset or competition URL directly into the chat:

Load https://www.kaggle.com/datasets/uciml/iris and show a scatter plot colored by species

Requires KAGGLE_USERNAME and KAGGLE_KEY in your MCP config env (free Kaggle account).

HuggingFace Datasets

Paste any HuggingFace dataset URL and get instant EDA:

Load https://huggingface.co/datasets/scikit-learn/iris and show a correlation heatmap

HF_TOKEN is optional — only needed for private datasets.

Automatic Chart Recommendations

After load_data(), the server analyses column types and returns up to 3 ready-to-render chart recommendations with working hvplot code — no manual chart selection needed.

Datashader for Big Data

Datasets with >100k rows automatically use datashade=True in all recommended chart code — rendering stays fast regardless of dataset size.

Live Streaming Dashboards

Real-time dashboards with periodic callbacks — sine waves, counters, live feeds — all rendered inline.

Maps

Interactive tile maps using hvPlot + GeoViews:

Plot the top 10 most populous cities on an interactive map with population as point size

Tools

Project Structure

src/holoviz_mcp_server/
├── cli.py               # CLI entry point (hvmcp serve / mcp / status)
├── config.py            # Pydantic config + env var loading
├── validation.py        # 5-layer code validation pipeline
├── utils.py             # Code execution, extension detection utilities
│
├── server/              # MCP server layer (FastMCP)
│   ├── main.py          # Main server + core tools (show, stream, load_data, ...)
│   ├── compose.py       # Mounts all sub-servers with namespaces
│   ├── panel_mcp.py     # pn.* tools
│   ├── hvplot_mcp.py    # hvplot.* tools
│   └── holoviews_mcp.py # hv.* tools
│
├── introspection/       # Pure Python discovery functions
│   ├── panel.py         # Panel component discovery
│   ├── holoviews.py     # HoloViews element discovery
│   ├── hvplot.py        # hvPlot chart type discovery
│   └── skills.py        # Skill file loading
│
├── display/             # Panel display server (runs as subprocess)
│   ├── app.py           # Panel server entry point
│   ├── manager.py       # Subprocess lifecycle management
│   ├── client.py        # HTTP client (MCP → Panel)
│   ├── database.py      # SQLite + FTS5 persistence
│   ├── endpoints.py     # REST handlers (/api/snippet, /api/health)
│   └── pages/           # Web UI pages (feed, view, add, admin)
│
├── templates/           # MCP App HTML (inline rendering in chat)
│   ├── show.html        # Chart viewer + click-to-insight
│   └── stream.html      # Live streaming viewer
│
└── skills/              # Best-practice guides (SKILL.md files)
    ├── panel/
    ├── hvplot/
    ├── holoviews/
    ├── param/
    └── data/

Installation

Prerequisite: Install uv first:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.sh | iex"
# Or via pip
pip install uv

{
  "servers": {
    "holoviz": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "hvmcp", "hvmcp", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "holoviz": {
      "command": "uvx",
      "args": ["--from", "hvmcp", "hvmcp", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "holoviz": {
      "command": "uvx",
      "args": ["--from", "hvmcp", "hvmcp", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "holoviz": {
      "command": "uvx",
      "args": ["--from", "hvmcp", "hvmcp", "mcp"]
    }
  }
}

Optional extras

The base install is lightweight. Add only what you need:

Optional: Kaggle & HuggingFace Integration

To load datasets directly from Kaggle or HuggingFace URLs, add credentials to the env section of your config:

{
  "env": {
    "KAGGLE_USERNAME": "your_kaggle_username",
    "KAGGLE_KEY": "your_kaggle_api_key",
    "HF_TOKEN": "your_huggingface_token"
  }
}

• Kaggle token: kaggle.com → Account → Settings → Create New Token
• HuggingFace token: huggingface.co → Settings → Access Tokens → New token (Read role)

HF_TOKEN is optional — only needed for private HuggingFace datasets. If credentials are not provided, Kaggle/HuggingFace URLs will return a friendly message instead of failing silently.

Example prompts once configured:

Load https://www.kaggle.com/datasets/uciml/iris and show a scatter plot colored by species

Load https://huggingface.co/datasets/scikit-learn/iris and show a correlation heatmap

License

BSD 3-Clause