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

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

flowchart TB
  subgraph A[LLM Client Layer]
    C1[VS Code Copilot]
    C2[Claude Desktop]
    C3[Cursor]
  end

  subgraph B[MCP Orchestration Layer - FastMCP]
    M1[Core tools
    show stream load_data validate]
    M2[Guided tools
    viz.create dashboard stream multi]
    M3[Introspection tools
    pn.* hvplot.* hv.* skills]
  end

  subgraph V[Validation and Safety Pipeline]
    V1[AST syntax check]
    V2[Ruff security rules + blocked imports]
    V3[Package availability checks]
    V4[Panel extension availability]
    V5[Runtime validation in isolated module]
  end

  subgraph D[Display Runtime - Panel Subprocess]
    D1[REST API
    /api/snippet /api/health]
    D2[Snippet execution and rendering]
    D3[View routes
    /view and feed]
  end

  subgraph P[Persistence Layer]
    P1[SQLite + FTS5 snippets database]
    P2[Metadata status requirements extensions]
  end

  subgraph U[MCP App UI Templates]
    U1[show.html
    chart viewer + interactions]
    U2[dashboard.html
    filters stats table]
    U3[stream.html
    live stream shell]
    U4[multi.html
    multi-chart container]
  end

  subgraph S[HoloViz Stack]
    S1[hvPlot]
    S2[HoloViews]
    S3[Panel]
    S4[Bokeh]
    S5[Param]
  end

  subgraph Data[Data Layer]
    R1[CSV TSV JSON Parquet Excel Zarr]
    R2[Remote URLs
    s3:// https://]
    R3[pandas numpy xarray]
  end

  C1 --> M1
  C2 --> M1
  C3 --> M1
  C1 --> M2
  C2 --> M2
  C3 --> M2
  C1 --> M3
  C2 --> M3
  C3 --> M3

  M1 --> V
  M2 --> V
  V --> D1
  D1 --> D2
  D2 --> P1
  P1 --> P2
  D2 --> U
  D2 --> S
  M1 --> Data
  M2 --> Data

Layer responsibilities

End-to-end flow

1. An agent calls a tool such as show, viz.create, or viz.dashboard.
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).

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", "holoviz-mcp-server", "hvmcp", "mcp"]
    }
  }
}

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

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

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

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

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

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
│   ├── guided_mcp.py    # viz.* tools (create, dashboard, stream, multi)
│   ├── panel_mcp.py     # pn.* tools
│   ├── hvplot_mcp.py    # hvplot.* tools
│   └── holoviews_mcp.py # hv.* tools
│
├── codegen/             # Code generators (config → Python)
│   └── codegen.py
│
├── 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
│   ├── dashboard.html   # Dashboard viewer
│   └── multi.html       # Multi-chart grid
│
└── skills/              # Best-practice guides (SKILL.md files)
    ├── panel/
    ├── hvplot/
    ├── holoviews/
    ├── param/
    └── data/

License

BSD 3-Clause